# Synchronet JavaScript Object Model Reference

Generated for Synchronet v3.14a, compiled Dec 27 2006 17:06
Includes Properties and Methods added or substantially modified in Synchronet v3.14 only.

1. [+] global object
   - methods
   - properties
2. [+] js object
   - methods
   - properties
3. [+] system object
   - methods
   - properties
4. [+] server object
5. [+] client object
6. [+] user object
   - methods
   - properties
7. [+] bbs object
   - methods
   - properties
8. [+] console object
   - methods
9. [+] msg_area object
10. [+] file_area object
11. [+] xtrn_area object
12. [+] MsgBase class
    - methods
13. [+] File class
    - methods
14. [+] Queue class
    - methods
15. [+] Socket class
    - methods

## global object
Top-level functions and properties (common to all servers and services)

`global` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
write_raw | void | `write_raw(value [,value])` | send a stream of bytes (possibly containing NULLs or special control code sequences) to the server output
wildmatch | boolean | `wildmatch([case_sensitive=`false`,] string [,pattern=`'*'`] [,path=`false`])` | returns `true` if the string matches the wildcard pattern (wildcards supported are '*' and '?'), if path is `true`, '*' will not match path delimeter characters (e.g. '/')
file_removecase | boolean | `file_removecase(path/filename)` | delete files case insensitively
file_compare | boolean | `file_compare(path/file1, path/file2)` | compare 2 files, returning true if they are identical, false otherwise
disk_size | number | `disk_size(directory [,unit_size=`1`])` | returns the total disk size of the specified directory using the specified unit_size in bytes (default: 1), specify a unit_size of `1024` to return the total disk size in kilobytes.

`global` properties
Name | Type | Description
--- | --- | ---
argc | number | number of arguments passed to the script
argv | array | array of argument strings (argv.length == argc)
errno | number | last system error number
errno_str | string | description of last system error
socket_errno | number | last socket-related error number (same as errno on Unix platforms)

## js object
JavaScript execution and garbage collection control object

`js` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
get_parent | object | `js.get_parent(object)` | return the parent of the specified object

`js` properties
Name | Type | Description
--- | --- | ---
global | object | global (top level) object - READ ONLY

## system object
Global system-related properties and methods

`system` methods
Name | Returns | Usage | Description
--- | --- | --- | ---

`system` properties
Name | Type | Description
--- | --- | ---
cmd_shell | string | platform-specific command processor/shell
timer | number | high-resolution timer, in seconds (fractional seconds supported)

## server object
Server-specifc properties

## client object
Represents a TCP/IP client session

## user object
Instance of User class, representing current user online

To create a new user object: `var u = new User(number)`

`user` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
adjust_credits | boolean | `user.adjust_credits(count)` | Adjust user's credits by count (negative to subtract)
adjust_minutes | boolean | `user.adjust_minutes(count)` | Adjust user's extra minutes count (negative to subtract)
posted_message | boolean | `user.posted_message([count])` | Adjust user's posted-messages statistics by count (default: 1) (negative to subtract)
sent_email | boolean | `user.sent_email([count] [,bool feedback])` | Adjust user's email/feedback-sent statistics by count (default: 1) (negative to subtract)
uploaded_file | boolean | `user.uploaded_file([bytes] [,files])` | Adjust user's files/bytes-uploaded statistics
downloaded_file | boolean | `user.downloaded_file([bytes] [,files])` | Adjust user's files/bytes-downloaded statistics

`user` properties
Name | Type | Description
--- | --- | ---
cached | boolean | record is currently cached in memory

## bbs object
Controls the Telnet/RLogin BBS experience

`bbs` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
send_file | boolean | `bbs.send_file(filename [,protocol])` | send specified filename (complete path) to user via user-prompted (or optionally specified) protocol
receive_file | boolean | `bbs.receive_file(filename [,protocol])` | received specified filename (complete path) frome user via user-prompted (or optionally specified) protocol
list_msgs | number | `bbs.list_msgs([sub-board=current] [,mode=`SCAN_READ`] [,message_number=`0`] [,string find])` | list messages in the specified message sub-board (number or internal code), optionally search for 'find' string, returns number of messages listed

`bbs` properties
Name | Type | Description
--- | --- | ---
start_time | number | time from which user's time left is calculated, in time_t format
cursub_code | string | current message sub-board internal code
curdir_code | string | current file directory internal code
command_str | string | current command shell/module command string value

## console object
Controls the user's Telnet/RLogin terminal

`console` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
term_supports | boolean | `console.term_supports([terminal_flags])` | either returns bool, indicating whether or not the current user/client supports all the specified terminal_flags, or returns the current user/client's terminal_flags (numeric bit-field) if no terminal_flags were specified

## msg_area object
Message Areas

## file_area object
File Transfer Areas

## xtrn_area object
External Program Areas

## MsgBase class
Class used for accessing message bases

To create a new MsgBase object: `var msgbase = new MsgBase('code')`
where code is a sub-board internal code, or `mail` for the e-mail message base

`MsgBase` methods
Name | Returns | Usage | Description
--- | --- | --- | ---

## File class
Class used for opening, creating, reading, or writing files on the local file system

Special features include:

1. Exclusive-access files (default) or shared files
   1. optional record-locking
   2. buffered or non-buffered I/O
2. Support for binary files
   1. native or network byte order (endian)
   2. automatic Unix-to-Unix (UUE), yEncode (yEnc) or Base64 encoding/decoding
3. Support for ASCII text files
   1. supports line-based I/O
      1. entire file may be read or written as an array of strings
      2. individual lines may be read or written one line at a time
   2. supports fixed-length records
      1. optional end-of-text (etx) character for automatic record padding/termination
      2. Synchronet `.dat` files use an etx value of 3 (Ctrl-C)
   3. supports `.ini` formated configuration files
      1. concept and support of root ini sections added in v3.12
   4. optional ROT13 encoding/translation
4. Dynamically-calculated industry standard checksums (e.g. CRC-16, CRC-32, MD5)

To create a new File object: `var f = new File(filename)`

`File` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
truncate | boolean | `File.truncate([length=`0`])` | changes the file length (default: 0) and repositions the file pointer (position) to the new end-of-file
iniRemoveKey | boolean | `File.iniRemoveKey(section, key)` | remove specified key from specified section in `.ini` file.
iniRemoveSection | boolean | `File.iniRemoveSection(section)` | remove specified section from `.ini` file.

## Queue class
Class for bi-directional message queues. Used for inter-thread/module communications.

To create a new (named) Queue object: `var q = new Queue(name)`

`Queue` methods
Name | Returns | Usage | Description
--- | --- | --- | ---

## Socket class
Class used for TCP/IP socket communications

To create a new Socket object: `load('sockdefs.js'); var s = new Socket(type, protocol)`
where type = `SOCK_STREAM` for TCP (default) or `SOCK_DGRAM` for UDP
and protocol (optional) = the name of the protocol or service the socket is to be used for

`Socket` methods
Name | Returns | Usage | Description
--- | --- | --- | ---

Totals: 8 properties, 19 methods