# Synchronet JavaScript Object Model Reference

Generated for Synchronet v3.12a, compiled Dec 31 2004 01:54
Includes Properties and Methods added or substantially modified in Synchronet v3.12 only.

1. [+] global object
   - methods
   - properties
2. [+] js object
   - methods
3. [+] system object
   - methods
   - properties
4. [+] server object
5. [+] client object
6. [+] user object
   - methods
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
14. [+] Queue class
    - methods
    - properties
15. [+] Socket class
    - methods

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

`global` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
load | undefined | `load([bool background or 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 the result (last executed statement) of the executed script or a newly created Queue object if background is true). Background (added in v3.12): If background is true, the loaded script runs in the background (in a child thread) but may communicate with the parent script/thread by reading from and/or writing to the parent_queue (an automatically created Queue object). The result (last executed statement) of the executed script will also be automatically written to the parent_queue which may be read later by the parent script.
backslash | string | `backslash(string path)` | returns directory path with trailing (platform-specific) path delimeter (i.e. "slash" or "backslash")
file_cfgname | string | `file_cfgname(string path, filename)` | returns completed configuration filename from supplied path and filename, optionally including the local hostname (e.g. `path/file.host.domain.ext` or `path/file.host.ext`) if such a variation of the filename exists
file_mutex | boolean | `file_mutex(string filename [,text])` | attempts to create an exclusive (e.g. lock) file, optionally with the contents of text
netaddr_type | number | `netaddr_type(string email_address)` | returns the proper message net_type for the specified email_address, (e.g. `NET_INTERNET` for Internet e-mail or `NET_NONE` for local e-mail)
list_named_queues | array | `list_named_queues()` | returns an array of named queues (created with the Queue constructor)

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

## system object
Global system-related properties and methods

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

`system` properties
Name | Type | Description
--- | --- | ---
temp_path | string | platform-specific temporary file directory

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

## bbs object
Controls the Telnet/RLogin BBS experience

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

`bbs` properties
Name | Type | Description
--- | --- | ---
errorlevel | number | error level returned from last executed external program
msg_thread_back | number | message thread, back message number (AKA msg_thread_orig)

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

`console` methods
Name | Returns | Usage | Description
--- | --- | --- | ---
uselect | number | `console.uselect([number, string title, string item, string ars])` | user selection menu, call for each item, then with no args to display select menu

`console` properties
Name | Type | Description
--- | --- | ---
input_buffer_level | number | number of bytes currently in the input buffer (from the remote client) - READ ONLY
input_buffer_space | number | number of bytes available in the input buffer - READ ONLY
output_buffer_level | number | number of bytes currently in the output buffer (from the local server) - READ ONLY
output_buffer_space | number | number of bytes available in the output buffer - READ ONLY

## 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_header | object | `MsgBase.get_msg_header([boolean by_offset,] number_or_id [,boolean expand_fields])` | returns a specific message header, null on failure. New in v3.12: Pass false for the expand_fields argument (default: true) if you will be re-writing the header later with put_msg_header()
save_msg | boolean | `MsgBase.save_msg(object header [,client] [,body_text] [,array rcpt_list])` | create a new message in message base, the header object may contain the following properties:
`subject` | Message subject (required)
`to` | Recipient's name (required)
`to_ext` | Recipient's user number (for local e-mail)
`to_org` | Recipient's organization
`to_net_type` | Recipient's network type (default: 0 for local)
`to_net_addr` | Recipient's network address
`to_agent` | Recipient's agent type
`from` | Sender's name (required)
`from_ext` | Sender's user number
`from_org` | Sender's organization
`from_net_type` | Sender's network type (default: 0 for local)
`from_net_addr` | Sender's network address
`from_agent` | Sender's agent type
`from_ip_addr` | Sender's IP address (if available, for security tracking)
`from_host_name` | Sender's host name (if available, for security tracking)
`from_protocol` | TCP/IP protocol used by sender (if available, for security tracking)
`from_port` | TCP/UDP port number used by sender (if available, for security tracking)
`replyto` | Replies should be sent to this name
`replyto_ext` | Replies should be sent to this user number
`replyto_org` | Replies should be sent to organization
`replyto_net_type` | Replies should be sent to this network type
`replyto_net_addr` | Replies should be sent to this network address
`replyto_agent` | Replies should be sent to this agent type
`id` | Message's RFC-822 compliant Message-ID
`reply_id` | Message's RFC-822 compliant Reply-ID
`reverse_path` | Message's SMTP sender address
`path` | Messages's NNTP path
`newsgroups` | Message's NNTP newsgroups header
`ftn_msgid` | FidoNet FTS-9 Message-ID
`ftn_reply` | FidoNet FTS-9 Reply-ID
`ftn_area` | FidoNet FTS-4 echomail AREA tag
`ftn_flags` | FidoNet FSC-53 FLAGS
`ftn_pid` | FidoNet FSC-46 Program Identifier
`ftn_tid` | FidoNet FSC-46 Tosser Identifier
`date` | RFC-822 formatted date/time
`attr` | Attribute bitfield
`auxattr` | Auxillary attribute bitfield
`netattr` | Network attribute bitfield
`when_written_time` | Date/time (in time_t format)
`when_written_zone` | Time zone
`when_imported_time` | Date/time message was imported
`when_imported_zone` | Time zone
`thread_back` | Message number that this message is a reply to
`thread_next` | Message number of the next reply to the original message in this thread
`thread_first` | Message number of the first reply to this message
`field_list[].type` | Other SMB header fields (type)
`field_list[].data` | Other SMB header fields (data)
New in v3.12: The optional client argument is an instance of the Client class to be used for the security log header fields (e.g. sender IP address, hostname, protocol, and port). New in v3.12: The optional rcpt_list is an array of objects that specifies multiple recipients for a single message (e.g. bulk e-mail). Each object in the array may include the following header properties (described above): to, to_ext, to_org, to_net_type, to_net_addr, and to_agent

`MsgBase` properties
Name | Type | Description
--- | --- | ---
status | number | return value of last SMB Library function call - READ ONLY

## 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
--- | --- | --- | ---
iniSetValue | boolean | `File.iniSetValue(section, key, value)` | set the specified key to the specified value in the specified section of a `.ini` file. to set a key in the root section, pass null for section.
iniSetObject | boolean | `File.iniSetObject(section, object)` | write all the properties of the specified object as separate `key=value` pairs in the specified section of a `.ini` file. to write an object in the root section, pass null for section.
iniSetAllObjects | array | `File.iniSetAllObjects(object array [,name_property])` | write an array of objects to a .ini file, each object in its own section named after the object's name_property (default: `name`)

## 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
--- | --- | --- | ---
poll | undefined | `Queue.poll([timeout])` | wait for a value on the queue for up to timeout milliseconds (default: infinite), returns true or the name (string) of the value waiting (if it has one), or false if no values are waiting
read | undefined | `Queue.read([name])` | read a value from the queue, if name not specified, reads next value from the bottom of the queue
peek | undefined | `Queue.peek()` | peek at the value at the bottom of the queue
write | boolean | `Queue.write(value [,name])` | write a value (optionally named) to the queue

`Queue` properties
Name | Type | Description
--- | --- | ---
name | undefined | name of the queue (if it has one)
data_waiting | boolean | true if data is waiting to be read from queue
read_level | number | number of values in the read queue
write_level | number | number of values in the write qeueue

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

Totals: 12 properties, 16 methods