4.4.4 Operations on Network Connections

Function: list connected_players ([include-all])

Returns a list of the object numbers of those player objects with currently-active connections. If include-all is provided and true, then the list includes the object numbers associated with all current connections, including ones that are outbound and/or not yet logged-in.

Function: int connected_seconds (obj player)

Function: int idle_seconds (obj player)

These functions return the number of seconds that the currently-active connection to player has existed and been idle, respectively. If player is not the object number of a player object with a currently-active connection, then E_INVARG is raised.

Function: none notify (obj conn, str string [, no-flush])

Enqueues string for output (on a line by itself) on the connection conn. If the programmer is not conn or a wizard, then E_PERM is raised. If conn is not a currently-active connection, then this function does nothing. Output is normally written to connections only between tasks, not during execution.

The server will not queue an arbitrary amount of output for a connection; the MAX_QUEUED_OUTPUT compilation option (see section Server Compilation Options) controls the limit. When an attempt is made to enqueue output that would take the server over its limit, it first tries to write as much output as possible to the connection without having to wait for the other end. If that doesn't result in the new output being able to fit in the queue, the server starts throwing away the oldest lines in the queue until the new ouput will fit. The server remembers how many lines of output it has `flushed' in this way and, when next it can succeed in writing anything to the connection, it first writes a line like >> Network buffer overflow: X lines of output to you have been lost << where X is the number of flushed lines.

If no-flush is provided and true, then notify() never flushes any output from the queue; instead it immediately returns false. Notify() otherwise always returns true.

Function: int buffered_output_length ([obj conn])

Returns the number of bytes currently buffered for output to the connection conn. If conn is not provided, returns the maximum number of bytes that will be buffered up for output on any connection.

Function: str read ([obj conn [, non-blocking]])

Reads and returns a line of input from the connection conn (or, if not provided, from the player that typed the command that initiated the current task). If non-blocking is false or not provided, this function suspends the current task, resuming it when there is input available to be read. If non-blocking is provided and true, this function never suspends the calling task; if there is no input currently available for input, read() simply returns 0 immediately.

If conn is provided, then the programmer must either be a wizard or the owner of conn; if conn is not provided, then read() may only be called by a wizard and only in the task that was last spawned by a command from the connection in question. Otherwise, E_PERM is raised. If conn is not currently connected and has no pending lines of input, or if the connection is closed while a task is waiting for input but before any lines of input are received, then read() raises E_INVARG.

The restriction on the use of read() without any arguments preserves the following simple invariant: if input is being read from a player, it is for the task started by the last command that player typed. This invariant adds responsibility to the programmer, however. If your program calls another verb before doing a read(), then either that verb must not suspend or else you must arrange that no commands will be read from the connection in the meantime. The most straightforward way to do this is to call

set_connection_option(player, "hold-input", 1)

before any task suspension could happen, then make all of your calls to read() and other code that might suspend, and finally call

set_connection_option(player, "hold-input", 0)

to allow commands once again to be read and interpreted normally.

Function: none force_input (obj conn, str line [, at-front])

Inserts the string line as an input task in the queue for the connection conn, just as if it had arrived as input over the network. If at_front is provided and true, then the new line of input is put at the front of conn's queue, so that it will be the very next line of input processed even if there is already some other input in that queue. Raises E_INVARG if conn does not specify a current connection and E_PERM if the programmer is neither conn nor a wizard.

Function: none flush_input (obj conn [show-messages])

Performs the same actions as if the connection conn's defined flush command had been received on that connection, i.e., removes all pending lines of input from conn's queue and, if show-messages is provided and true, prints a message to conn listing the flushed lines, if any. See the chapter on server assumptions about the database for more information about a connection's defined flush command.

Function: list output_delimiters (obj player)

Returns a list of two strings, the current output prefix and output suffix for player. If player does not have an active network connection, then E_INVARG is raised. If either string is currently undefined, the value "" is used instead. See the discussion of the PREFIX and SUFFIX commands in the next chapter for more information about the output prefix and suffix.

Function: none boot_player (obj player)

Marks for disconnection any currently-active connection to the given player. The connection will not actually be closed until the currently-running task returns or suspends, but all MOO functions (such as notify(), connected_players(), and the like) immediately behave as if the connection no longer exists. If the programmer is not either a wizard or the same as player, then E_PERM is raised. If there is no currently-active connection to player, then this function does nothing.

If there was a currently-active connection, then the following verb call is made when the connection is actually closed:

$user_disconnected(player)

It is not an error if this verb does not exist; the call is simply skipped.

Function: str connection_name (obj player)

Returns a network-specific string identifying the connection being used by the given player. If the programmer is not a wizard and not player, then E_PERM is raised. If player is not currently connected, then E_INVARG is raised.

For the TCP/IP networking configurations, for in-bound connections, the string has the form

"port lport from host, port port"

where lport is the decimal TCP listening port on which the connection arrived, host is either the name or decimal TCP address of the host from which the player is connected, and port is the decimal TCP port of the connection on that host.

For outbound TCP/IP connections, the string has the form

"port lport to host, port port"

where lport is the decimal local TCP port number from which the connection originated, host is either the name or decimal TCP address of the host to which the connection was opened, and port is the decimal TCP port of the connection on that host.

For the System V `local' networking configuration, the string is the UNIX login name of the connecting user or, if no such name can be found, something of the form

"User #number"

where number is a UNIX numeric user ID.

For the other networking configurations, the string is the same for all connections and, thus, useless.

Function: none set_connection_option (obj conn, str option, value)

Controls a number of optional behaviors associated the connection conn. Raises E_INVARG if conn does not specify a current connection and E_PERM if the programmer is neither conn nor a wizard. Unless otherwise specified below, options can only be set (value is true) or unset (otherwise). The following values for option are currently supported:

binary

When set, the connection is in binary mode, in which case both input from and output to conn can contain arbitrary bytes. Input from a connection in binary mode is not broken into lines at all; it is delivered to either the read() function or normal command parsing as binary strings, in whatever size chunks come back from the operating system. (See section fine point on binary strings, for a description of the binary string representation.) For output to a connection in binary mode, the second argument to `notify()' must be a binary string; if it is malformed, E_INVARG is raised.

Fine point: If the connection mode is changed at any time when there is pending input on the connection, said input will be delivered as per the previous mode (i.e., when switching out of binary mode, there may be pending "lines" containing tilde-escapes for embedded linebreaks, tabs, tildes and other characters; when switching into binary mode, there may be pending lines containing raw tabs and from which nonprintable characters have been silently dropped as per normal mode. Only during the initial invocation of $do_login_command() on an incoming connection or immediately after the call to open_network_connection() that creates an outgoing connection is there guaranteed not to be pending input. At other times you will probably want to flush any pending input immediately after changing the connection mode.

hold-input

When set, no input received on conn will be treated as a command; instead, all input remains in the queue until retrieved by calls to read() or until this connection option is unset, at which point command processing resumes. Processing of out-of-band input lines is unaffected by this option.

disable-oob

When set, disables all out of band processing (see section 5.1.2 Out-of-Band Processing). All subsequent input lines until the next command that unsets this option will be made available for reading tasks or normal command parsing exactly as if the out-of-band prefix and the out-of-band quoting prefix had not been defined for this server.

client-echo

The setting of this option is of no significance to the server. However calling set_connection_option() for this option sends the Telnet Protocol `WONT ECHO' or `WILL ECHO' according as value is true or false, respectively. For clients that support the Telnet Protocol, this should toggle whether or not the client echoes locally the characters typed by the user. Note that the server itself never echoes input characters under any circumstances. (This option is only available under the TCP/IP networking configurations.)

flush-command

This option is string-valued. If the string is non-empty, then it is the flush command for this connection, by which the player can flush all queued input that has not yet been processed by the server. If the string is empty, then conn has no flush command at all. set_connection_option also allows specifying a non-string value which is equivalent to specifying the empty string. The default value of this option can be set via the property $server_options.default_flush_command; see Flushing Unprocessed Input for details.

intrinsic-commands

This option value is a list of strings, each being the name of one of the available server intrinsic commands (see section Command Lines That Receive Special Treatment). Commands not on the list are disabled, i.e., treated as normal MOO commands to be handled by $do_command and/or the built-in command parser

set_connection_option also allows specifying an integer value which, if zero, is equivalent to specifying the empty list, and otherwise is taken to be the list of all available intrinsic commands (the default setting).

Thus, one way to make the verbname `PREFIX' available as an ordinary command is as follows:

set_connection_option( player, "intrinsic-commands", setremove(connection_option(player, "intrinsic-commands"), "PREFIX"));

Note that connection_option() always returns the list, even if set_connection_option was previously called with a numeric value. Thus,

save = connection_option(player,"intrinsic-commands"); set_connection_option(player, "intrinsic-commands, 1); full_list = connection_option(player,"intrinsic-commands"); set_connection_option(player,"intrinsic-commands", save); return full_list;

is a way of getting the full list of intrinsic commands available in the server while leaving the current connection unaffected.

Function: list connection_options (obj conn)

Returns a list of {name, value} pairs describing the current settings of all of the allowed options for the connection conn. Raises E_INVARG if conn does not specify a current connection and E_PERM if the programmer is neither conn nor a wizard.

Function: value connection_option (obj conn, str name)

Returns the current setting of the option name for the connection conn. Raises E_INVARG if conn does not specify a current connection and E_PERM if the programmer is neither conn nor a wizard.

Function: obj open_network_connection (value, ... [, listener])

Establishes a network connection to the place specified by the arguments and more-or-less pretends that a new, normal player connection has been established from there. The new connection, as usual, will not be logged in initially and will have a negative object number associated with it for use with read(), notify(), and boot_player(). This object number is the value returned by this function.

If the programmer is not a wizard or if the OUTBOUND_NETWORK compilation option was not used in building the server, then E_PERM is raised. If the network connection cannot be made for some reason, then other errors will be returned, depending upon the particular network implementation in use.

For the TCP/IP network implementations (the only ones as of this writing that support outbound connections), there must be at least two arguments, a string naming a host (possibly using the numeric Internet syntax) and an integer specifying a TCP port. If a connection cannot be made because the host does not exist, the port does not exist, the host is not reachable or refused the connection, E_INVARG is raised. If the connection cannot be made for other reasons, including resource limitations, then E_QUOTA is raised.

Beginning with version 1.8.3, an optional third argument may be supplied, listener must be an object, whose listening verbs will be called at appropriate points. See the description in listen(), below, for more details.

The outbound connection process involves certain steps that can take quite a long time, during which the server is not doing anything else, including responding to user commands and executing MOO tasks. See the chapter on server assumptions about the database for details about how the server limits the amount of time it will wait for these steps to successfully complete.

It is worth mentioning one tricky point concerning the use of this function. Since the server treats the new connection pretty much like any normal player connection, it will naturally try to parse any input from that connection as commands in the usual way. To prevent this treatment, you should use set_connection_option() to set the hold-input option true on the connection.

Function: value listen (obj object, point [, print-messages])

Create a new point at which the server will listen for network connections, just as it does normally. object is the object whose verbs do_login_command, do_command, do_out_of_band_command, user_connected, user_created, user_reconnected, user_disconnected, and user_client_disconnected will be called at appropriate points, just as these verbs are called on #0 for normal connections. (See the chapter on server assumptions about the database for the complete story on when these functions are called.) point is a network-configuration-specific parameter describing the listening point. If print-messages is provided and true, then the various database-configurable messages (also detailed in the chapter on server assumptions) will be printed on connections received at the new listening point. listen() returns canon, a `canonicalized' version of point, with any configuration-specific defaulting or aliasing accounted for.

This raises E_PERM if the programmer is not a wizard, E_INVARG if object is invalid or there is already a listening point described by point, and E_QUOTA if some network-configuration-specific error occurred.

For the TCP/IP configurations, point is a TCP port number on which to listen and canon is equal to point unless point is zero, in which case canon is a port number assigned by the operating system.

For the local multi-user configurations, point is the UNIX file name to be used as the connection point and canon is always equal to point.

In the single-user configuration, the can be only one listening point at a time; point can be any value at all and canon is always zero.

Function: none unlisten (canon)

Stop listening for connections on the point described by canon, which should be the second element of some element of the list returned by listeners(). Raises E_PERM if the programmer is not a wizard and E_INVARG if there does not exist a listener with that description.

Function: list listeners ()

Returns a list describing all existing listening points, including the default one set up automatically by the server when it was started (unless that one has since been destroyed by a call to unlisten()). Each element of the list has the following form:

{object, canon, print-messages}

where object is the first argument given in the call to listen() to create this listening point, print-messages is true if the third argument in that call was provided and true, and canon was the value returned by that call. (For the initial listening point, object is #0, canon is determined by the command-line arguments or a network-configuration-specific default, and print-messages is true.)

Please note that there is nothing special about the initial listening point created by the server when it starts; you can use unlisten() on it just as if it had been created by listen(). This can be useful; for example, under one of the TCP/IP configurations, you might start up your server on some obscure port, say 12345, connect to it by yourself for a while, and then open it up to normal users by evaluating the statments

unlisten(12345); listen(#0, 7777, 1)