# Synchronet JavaScript Object Model Reference

Generated for Synchronet v3.11a beta Debug, compiled Dec 6 2003 19:56
Includes Properties and Methods added in Synchronet v3.11 only.

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

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

`global` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
log | string | `log([level,] value [,value])` | add a line of text to the server and/or system log, values are typically string constants or variables, level is the debug level/priority (default: `LOG_INFO`)
read | string | `read([count])` | read up to count characters from input stream
readln | string | `readln([count])` | read a single line, up to count characters, from input stream
write | void | `write(value [,value])` | send one or more values (typically strings) to the server output
writeln | void | `writeln(value [,value])` | send a line of text to the console or event log with automatic line termination (CRLF), values are typically string constants or variables (AKA print)
exit | void | `exit([number exit_code])` | stop script execution, optionally setting the global property `exit_code` to the specified numeric value
load | boolean | `load([object scope,] string filename [,args])` | load and execute a JavaScript module (filename), optionally specifying a target scope object (default: this) and a list of arguments to pass to the module (as argv), returns true if the execution was successful
yield | void | `yield([bool forced])` | release current thread time-slice, a forced yield will yield to all other pending tasks (lowering CPU utilization), a non-forced yield will yield only to pending tasks of equal or higher priority. forced defaults to true
ctrl | string | `ctrl(number or string)` | return ASCII control character representing character passed - Example: `ctrl('C') returns ''`
file_getname | string | `file_getname(string path)` | returns filename portion of passed path string
file_getext | string | `file_getext(string path)` | returns file extension portion of passed path/filename string (including '.') or undefined if no extension is found
file_getcase | string | `file_getcase(string filename)` | returns correct case of filename (long version of filename on Win32) or undefined if the file doesn't exist
file_rename | boolean | `file_rename(oldname, newname)` | rename a file, possibly moving it to another directory in the process
file_copy | boolean | `file_copy(source, destination)` | copy a file from one directory or filename to another
file_backup | boolean | `file_backup(string filename [,number level] [,bool rename])` | backup the specified filename as `filename.number.extension` where number is the backup number 0 through level-1 (default backup level is 5), if rename is true, the original file is renamed instead of copied (default is false)
file_utime | boolean | `file_utime(string filename [,access_time] [,mod_time])` | change a file's last accessed and modification date/time (in time_t format), or change to current time
file_touch | boolean | `file_touch(string filename)` | updates a file's last modification date/time to current time, creating an empty file if it doesn't already exist
dir_freespace | number | `dir_freespace(string directory [,unit_size])` | returns the amount of available disk space in the specified directory using the specified unit_size in bytes (default: 1), specify a unit_size of `1024` to return the available space in kilobytes.
socket_select | array | `socket_select([array of socket objects or descriptors] [,number timeout] [,bool write])` | checks an array of socket objects or descriptors for read or write ability (default is read), default timeout value is 0.0 seconds (immediate timeout), returns an array of 0-based index values into the socket array, representing the sockets that were ready for reading or writing
html_encode | string | `html_encode(string text [,bool ex_ascii] [,bool white_space] [,bool ansi] [,bool ctrl_a])` | return an HTML-encoded text string (using standard HTML character entities), escaping IBM extended-ASCII, white-space characters, ANSI codes, and CTRL-A codes by default
html_decode | string | `html_decode(string text)` | return a decoded HTML-encoded text string
word_wrap | string | `word_wrap(string text [,line_length])` | returns a word-wrapped version of the text string argument, line_length defaults to 79
quote_msg | string | `quote_msg(string text [,line_length] [,prefix])` | returns a quoted version of the message text string argumnet, line_length defaults to 79, prefix defaults to `" > "`
rot13_translate | string | `rot13_translate(string text)` | returns ROT13-translated version of text string (will encode or decode text)
base64_encode | string | `base64_encode(string text)` | returns base64-encoded version of text string or null on error
base64_decode | string | `base64_decode(string text)` | returns base64-decoded text string or null on error (not useful for binary data)
crc16_calc | number | `crc16_calc(string text)` | calculate and return 16-bit CRC of text string
crc32_calc | number | `crc32_calc(string text)` | calculate and return 32-bit CRC of text string
chksum_calc | number | `chksum_calc(string text)` | calculate and return 32-bit checksum of text string
md5_calc | string | `md5_calc(string text [,bool hex])` | calculate and return 128-bit MD5 digest of text string, result encoded in base64 (default) or hexadecimal
resolve_ip | string | `resolve_ip(string hostname)` | resolve IP address of specified hostname (AKA gethostbyname)
resolve_host | string | `resolve_host(string ip_address)` | resolve hostname of specified IP address (AKA gethostbyaddr)

`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

## js object
JavaScript execution and garbage collection control object

`js` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
eval | string | `js.eval(string script)` | evaluate a JavaScript string in its own (secure) context, returning the result
gc | void | `js.gc(bool forced)` | perform a garbage collection operation (freeing memory for unused allocated objects), if forced is true (the default) a garbage collection is always performed, otherwise it is only performed if deemed appropriate by the JavaScript engine

`js` properties
Name | Type | Description
--- | --- | ---
version | string | JavaScript engine version information (AKA system.js_version)
auto_terminate | boolean | set to false to disable the automatic termination of the script upon external request
terminated | boolean | termination has been requested (stop execution as soon as possible)
branch_counter | number | number of branch operations performed in this runtime
branch_limit | number | maximum number of branches, used for infinite-loop detection (0=disabled)
yield_interval | number | interval of periodic time-slice yields (lower number=higher frequency, 0=disabled)
gc_interval | number | interval of periodic garbage collection attempts (lower number=higher frequency, 0=disabled)
gc_attempts | number | number of garbage collections attempted in this runtime - READ ONLY
gc_counter | number | number of garbage collections performed in this runtime - READ ONLY
gc_last_bytes | number | number of heap bytes in use after last garbage collection - READ ONLY
bytes | number | number of heap bytes currently in use - READ ONLY
max_bytes | number | maximum number of bytes available for heap

## system object
Global system-related properties and methods

`system` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
username | string | `system.username(number)` | returns name of user in specified user record number, or empty string if not found
filter_ip | boolean | `system.filter_ip([protocol, reason, host, ip, username])` | add an IP address (with comment) to the system's IP filter file
get_node_message | string | `system.get_node_message(number node)` | read any messages waiting for the specified node and return in a single string
get_telegram | string | `system.get_telegram(number user)` | returns any short text messages waiting for the specified user
exec | number | `system.exec(command-line)` | executes a native system/shell command-line, returns 0 on success
popen | array | `system.popen(command-line)` | executes a native system/shell command-line, returns array of captured output lines on success (only functional on UNIX systems)
check_syspass | boolean | `system.check_syspass(string password)` | compares the supplied password against the system password and return's true if it matches

`system` properties
Name | Type | Description
--- | --- | ---
inet_addr | string | Internet address (host or domain name)
lastuser | number | last user record number in user database (includes deleted and inactive user records)
devnull | string | null device filename
clock_ticks | number | amount of elapsed processor time in clock 'ticks'
clock_ticks_per_second | number | number of clock ticks per second
local_host_name | string | private host name that uniquely identifies this system on the local network

## server object
Server-specifc properties

`server` properties
Name | Type | Description
--- | --- | ---
interface_ip_address | string | IP address of bound network interface (`0.0.0.0` = ANY)
options | number | bit-field of server-specific startup options
clients | number | number of active clients (if available)

## 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
--- | --- | --- | ---

`user` properties
Name | Type | Description
--- | --- | ---
new_file_time | number | new file scan date/time (time_t format)

## bbs object
Controls the Telnet/RLogin BBS experience

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

`bbs` properties
Name | Type | Description
--- | --- | ---
time_left | number | time left (in seconds)
event_time | number | time of next exclusive event (in time_t format), or 0 if none
event_code | string | internal code of next exclusive event

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

`console` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
inkey | string | `console.inkey([number mode] [,number timeout])` | get a single key with optional timeout in milliseconds (defaults to 0, for no wait), see `K_*` in `sbbsdefs.js` for mode bits
home | void | `console.home()` | send cursor to home position (x,y:1,1)
cleartoeol | void | `console.cleartoeol()` | clear to end-of-line (ANSI)
beep | void | `console.beep([number count])` | beep for count number of times (default count is 1)
pushxy | void | `console.pushxy()` | save current cursor position (AKA ansi_save)
popxy | void | `console.popxy()` | restore saved cursor position (AKA ansi_restore)
gotoxy | void | `console.gotoxy(number x,y)` | Move cursor to a specific screen coordinate (ANSI), arguments can be separate x and y cooridinates or an object with x and y properites (like that returned from `console.getxy()`)
up | void | `console.up([number rows])` | Move cursor up one or more rows (ANSI)
down | void | `console.down([number rows])` | Move cursor down one or more rows (ANSI)
right | void | `console.right([number columns])` | Move cursor right one or more columns (ANSI)
left | void | `console.left([number columns])` | Move cursor left one or more columns (ANSI)
getlines | void | `console.getlines()` | Auto-detect the number of rows/lines on the user's terminal (ANSI)
getxy | object | `console.getxy()` | Returns the current cursor position as an object (with x and y properties)
handle_ctrlkey | boolean | `console.handle_ctrlkey(string key [,number mode])` | Call internal control key handler for specified control key, returns true if handled

`console` properties
Name | Type | Description
--- | --- | ---
screen_columns | number | number of terminal screen columns (in character cells)
terminal | string | terminal type description (e.g. 'ANSI')
getstr_offset | number | cursor position offset for use with `getstr(K_USEOFFSET)`

## 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
--- | --- | --- | ---
get_msg_index | object | `MsgBase.get_msg_index([boolean by_offset,] number)` | returns a specific message index, null on failure. The index object will contain the following properties:
`subject` | CRC-16 of lowercase message subject
`to` | CRC-16 of lowercase recipient's name (or user number if e-mail)
`from` | CRC-16 of lowercase sender's name (or user number if e-mail)
`attr` | Attribute bitfield
`time` | Date/time (in time_t format)
`number` | Message number
`offset` | Byte-offset into header file
remove_msg | boolean | `MsgBase.remove_msg([boolean by_offset,] number_or_id)` | mark message as deleted

`MsgBase` properties
Name | Type | Description
--- | --- | ---
retry_delay | number | delay between message base open/lock retries (in milliseconds)

## 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
   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
--- | --- | --- | ---
rewind | boolean | `File.rewind()` | repositions the file pointer (position) to the beginning of a file and clears error and end-of-file indicators
iniGetSections | array | `File.iniGetSections([prefix])` | parse all section names from a `.ini` file (format = '`[section]`') and return the section names as an array of strings, optionally, only those section names that begin with the specified prefix
iniGetKeys | array | `File.iniGetKeys(section)` | parse all key names from the specified section in a `.ini` file and return the key names as an array of strings
iniGetValue | string | `File.iniGetValue(section, key [,default])` | parse a key from a `.ini` file and return its value (format = '`key = value`'). returns the specified default value if the key or value is missing or invalid. will return a bool, number, string, or an array of strings determined by the type of default value specified
iniGetObject | object | `File.iniGetObject(section)` | parse an entire section from a .ini file and return all of its keys and values as properties of an object
iniGetAllObjects | array | `File.iniGetAllObjects([name_property] [,prefix])` | parse all sections from a .ini file and return all sections and keys an array of objects with each section's keys as properties of each section object, name_property is the name of the property to create to contain the section's name (default is `"name"`), the optional prefix has the same use as in the `iniGetSections` method, if a prefix is specified, it is removed from each section's name

`File` properties
Name | Type | Description
--- | --- | ---
date | number | last modified date/time (in time_t format)
network_byte_order | boolean | set to true if binary data is to be written and read in Network Byte Order (big end first)
rot13 | boolean | set to true to enable automatic ROT13 translatation of text
uue | boolean | set to true to enable automatic Unix-to-Unix encode and decode on `read` and `write` calls
yenc | boolean | set to true to enable automatic yEnc encode and decode on `read` and `write` calls
base64 | boolean | set to true to enable automatic Base64 encode and decode on `read` and `write` calls
crc16 | number | calculated 16-bit CRC of file contents - READ ONLY
crc32 | number | calculated 32-bit CRC of file contents - READ ONLY
chksum | number | calculated 32-bit checksum of file contents - READ ONLY
md5_hex | undefined | calculated 128-bit MD5 digest of file contents as hexadecimal string - READ ONLY
md5_base64 | undefined | calculated 128-bit MD5 digest of file contents as base64-encoded string - READ ONLY

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

To create a new Socket object: `load('sockdefs.js'); var s = new Socket(type)`
where type = `SOCK_STREAM` for TCP (default) or `SOCK_DGRAM` for UDP

`Socket` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
bind | boolean | `Socket.bind([port] [,ip_address])` | bind socket to a TCP or UDP port (number or service name), optionally specifying a network interface (via ip_address)
connect | boolean | `Socket.connect(host, port [,timeout])` | connect to a remote port (number or service name) on the specified host (IP address or host name), default timeout value is 10.0 (seconds)
sendBin | boolean | `Socket.sendBin(number value [,number bytes])` | send a binary integer over the socket, default number of bytes is 4 (32-bits)
recvfrom | object | `Socket.recvfrom([bool binary] [,maxlen or int_size])` | receive data (string or integer) from a socket (typically UDP) returns object with ip_address and port of sender along with data binary defaults to false, maxlen defaults to 512 chars, int_size defaults to 4 bytes (32-bits)
recvBin | number | `Socket.recvBin([number bytes])` | receive a binary integer from the socket, default number of bytes is 4 (32-bits)

`Socket` properties
Name | Type | Description
--- | --- | ---
error | number | error status for the last socket operation that failed - READ ONLY
is_writeable | boolean | true if socket can accept written data - READ ONLY
network_byte_order | boolean | true if binary data is to be sent in Network Byte Order (big end first), default is true

Totals: 43 properties, 68 methods