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
  2. [+]  js object
  3. [+]  system object
  4. [+]  server object
  5. [+]  client object
  6. [+]  user object
  7. [+]  bbs object
  8. [+]  console object
  9. [+]  msg_area object
  10. [+]  file_area object
  11. [+]  xtrn_area object
  12. [+]  MsgBase class
  13. [+]  File class
  14. [+]  Socket class

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

global methods
Name Returns Usage Description
logstringlog([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)
readstringread([count]) read up to count characters from input stream
readlnstringreadln([count]) read a single line, up to count characters, from input stream
writevoidwrite(value [,value]) send one or more values (typically strings) to the server output
writelnvoidwriteln(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)
exitvoidexit([number exit_code]) stop script execution, optionally setting the global property exit_code to the specified numeric value
loadbooleanload([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
yieldvoidyield([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
ctrlstringctrl(number or string) return ASCII control character representing character passed - Example: ctrl('C') returns ''
file_getnamestringfile_getname(string path) returns filename portion of passed path string
file_getextstringfile_getext(string path) returns file extension portion of passed path/filename string (including '.') or undefined if no extension is found
file_getcasestringfile_getcase(string filename) returns correct case of filename (long version of filename on Win32) or undefined if the file doesn't exist
file_renamebooleanfile_rename(oldname, newname) rename a file, possibly moving it to another directory in the process
file_copybooleanfile_copy(source, destination) copy a file from one directory or filename to another
file_backupbooleanfile_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_utimebooleanfile_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_touchbooleanfile_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_freespacenumberdir_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_selectarraysocket_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_encodestringhtml_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_decodestringhtml_decode(string text) return a decoded HTML-encoded text string
word_wrapstringword_wrap(string text [,line_length]) returns a word-wrapped version of the text string argument, line_length defaults to 79
quote_msgstringquote_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_translatestringrot13_translate(string text) returns ROT13-translated version of text string (will encode or decode text)
base64_encodestringbase64_encode(string text) returns base64-encoded version of text string or null on error
base64_decodestringbase64_decode(string text) returns base64-decoded text string or null on error (not useful for binary data)
crc16_calcnumbercrc16_calc(string text) calculate and return 16-bit CRC of text string
crc32_calcnumbercrc32_calc(string text) calculate and return 32-bit CRC of text string
chksum_calcnumberchksum_calc(string text) calculate and return 32-bit checksum of text string
md5_calcstringmd5_calc(string text [,bool hex]) calculate and return 128-bit MD5 digest of text string, result encoded in base64 (default) or hexadecimal
resolve_ipstringresolve_ip(string hostname) resolve IP address of specified hostname (AKA gethostbyname)
resolve_hoststringresolve_host(string ip_address) resolve hostname of specified IP address (AKA gethostbyaddr)

global properties
Name Type Description
argcnumbernumber of arguments passed to the script
argvarrayarray of argument strings (argv.length == argc)
errnonumberlast system error number
errno_strstringdescription of last system error

js object
JavaScript execution and garbage collection control object

js methods
Name Returns Usage Description
evalstringjs.eval(string script) evaluate a JavaScript string in its own (secure) context, returning the result
gcvoidjs.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
versionstring JavaScript engine version information (AKA system.js_version)
auto_terminateboolean set to false to disable the automatic termination of the script upon external request
terminatedboolean termination has been requested (stop execution as soon as possible)
branch_counternumber number of branch operations performed in this runtime
branch_limitnumber maximum number of branches, used for infinite-loop detection (0=disabled)
yield_intervalnumber interval of periodic time-slice yields (lower number=higher frequency, 0=disabled)
gc_intervalnumber interval of periodic garbage collection attempts (lower number=higher frequency, 0=disabled)
gc_attemptsnumber number of garbage collections attempted in this runtime - READ ONLY
gc_counternumber number of garbage collections performed in this runtime - READ ONLY
gc_last_bytesnumber number of heap bytes in use after last garbage collection - READ ONLY
bytesnumber number of heap bytes currently in use - READ ONLY
max_bytesnumber maximum number of bytes available for heap

system object
Global system-related properties and methods

system methods
Name Returns Usage Description
usernamestringsystem.username(number) returns name of user in specified user record number, or empty string if not found
filter_ipbooleansystem.filter_ip([protocol, reason, host, ip, username]) add an IP address (with comment) to the system's IP filter file
get_node_messagestringsystem.get_node_message(number node) read any messages waiting for the specified node and return in a single string
get_telegramstringsystem.get_telegram(number user) returns any short text messages waiting for the specified user
execnumbersystem.exec(command-line) executes a native system/shell command-line, returns 0 on success
popenarraysystem.popen(command-line) executes a native system/shell command-line, returns array of captured output lines on success (only functional on UNIX systems)
check_syspassbooleansystem.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_addrstring Internet address (host or domain name)
lastusernumber last user record number in user database (includes deleted and inactive user records)
devnullstring null device filename
clock_ticksnumber amount of elapsed processor time in clock 'ticks'
clock_ticks_per_secondnumber number of clock ticks per second
local_host_namestring private host name that uniquely identifies this system on the local network

server object
Server-specifc properties

server properties
Name Type Description
interface_ip_addressstring IP address of bound network interface ( = ANY)
optionsnumber bit-field of server-specific startup options
clientsnumber 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_timenumber 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_leftnumber time left (in seconds)
event_timenumber time of next exclusive event (in time_t format), or 0 if none
event_codestring internal code of next exclusive event

console object
Controls the user's Telnet/RLogin terminal

console methods
Name Returns Usage Description
inkeystringconsole.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
homevoidconsole.home() send cursor to home position (x,y:1,1)
cleartoeolvoidconsole.cleartoeol() clear to end-of-line (ANSI)
beepvoidconsole.beep([number count]) beep for count number of times (default count is 1)
pushxyvoidconsole.pushxy() save current cursor position (AKA ansi_save)
popxyvoidconsole.popxy() restore saved cursor position (AKA ansi_restore)
gotoxyvoidconsole.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())
upvoidconsole.up([number rows]) Move cursor up one or more rows (ANSI)
downvoidconsole.down([number rows]) Move cursor down one or more rows (ANSI)
rightvoidconsole.right([number columns]) Move cursor right one or more columns (ANSI)
leftvoidconsole.left([number columns]) Move cursor left one or more columns (ANSI)
getlinesvoidconsole.getlines() Auto-detect the number of rows/lines on the user's terminal (ANSI)
getxyobjectconsole.getxy() Returns the current cursor position as an object (with x and y properties)
handle_ctrlkeybooleanconsole.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_columnsnumber number of terminal screen columns (in character cells)
terminalstring terminal type description (e.g. 'ANSI')
getstr_offsetnumber 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_indexobjectMsgBase.get_msg_index([boolean by_offset,] number) returns a specific message index, null on failure. The index object will contain the following properties:
subjectCRC-16 of lowercase message subject
toCRC-16 of lowercase recipient's name (or user number if e-mail)
fromCRC-16 of lowercase sender's name (or user number if e-mail)
attrAttribute bitfield
timeDate/time (in time_t format)
numberMessage number
offsetByte-offset into header file
remove_msgbooleanMsgBase.remove_msg([boolean by_offset,] number_or_id) mark message as deleted

MsgBase properties
Name Type Description
retry_delaynumber 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
rewindbooleanFile.rewind() repositions the file pointer (position) to the beginning of a file and clears error and end-of-file indicators
iniGetSectionsarrayFile.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
iniGetKeysarrayFile.iniGetKeys(section) parse all key names from the specified section in a .ini file and return the key names as an array of strings
iniGetValuestringFile.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
iniGetObjectobjectFile.iniGetObject(section) parse an entire section from a .ini file and return all of its keys and values as properties of an object
iniGetAllObjectsarrayFile.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
datenumber last modified date/time (in time_t format)
network_byte_orderboolean set to true if binary data is to be written and read in Network Byte Order (big end first)
rot13boolean set to true to enable automatic ROT13 translatation of text
uueboolean set to true to enable automatic Unix-to-Unix encode and decode on read and write calls
yencboolean set to true to enable automatic yEnc encode and decode on read and write calls
base64boolean set to true to enable automatic Base64 encode and decode on read and write calls
crc16number calculated 16-bit CRC of file contents - READ ONLY
crc32number calculated 32-bit CRC of file contents - READ ONLY
chksumnumber calculated 32-bit checksum of file contents - READ ONLY
md5_hexundefined calculated 128-bit MD5 digest of file contents as hexadecimal string - READ ONLY
md5_base64undefined 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
bindbooleanSocket.bind([port] [,ip_address]) bind socket to a TCP or UDP port (number or service name), optionally specifying a network interface (via ip_address)
connectbooleanSocket.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)
sendBinbooleanSocket.sendBin(number value [,number bytes]) send a binary integer over the socket, default number of bytes is 4 (32-bits)
recvfromobjectSocket.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)

recvBinnumberSocket.recvBin([number bytes]) receive a binary integer from the socket, default number of bytes is 4 (32-bits)

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

Totals: 43 properties, 68 methods