57.12 Network Connections

SXEmacs Lisp programs can open TCP network connections to other processes on the same machine or other machines. A network connection is handled by Lisp much like a subprocess, and is represented by a process object.

However, the process you are communicating with is not a child of the SXEmacs process, so you can’t kill it or send it signals. All you can do is send and receive data. delete-process closes the connection, but does not kill the process at the other end; that process must decide what to do about closure of the connection.

You can distinguish process objects representing network connections from those representing subprocesses with the process-status function. It always returns either open or closed for a network connection, and it never returns either of those values for a real subprocess. See Process Information.

Function: open-network-stream name buffer-or-name host service &optional protocol

This function opens a TCP connection for a service to a host. It returns a process object to represent the connection.

Input and output work as for other process objects. delete-process closes the connection.

The name argument specifies the name for the process object. It is modified as necessary to make it unique.

The buffer-or-name argument is the buffer to associate with the connection. It can be a buffer or the name of one. Output from the connection is inserted in the buffer, unless you specify a filter function to handle the output. If buffer-or-name is nil, it means that the connection is not associated with any buffer.

The arguments host and service specify where to connect to; host is the host name or IP address (a string), and service is the name of a defined network service (a string) or a port number (an integer).

Optional fifth arg protocol is the network protocol to use. Currently only tcp (Transmission Control Protocol) and udp (User Datagram Protocol) are supported. When omitted, tcp is assumed.

Output via process-send-string and input via buffer or filter (see set-process-filter) are stream-oriented. That means UDP datagrams are not guaranteed to be sent and received in discrete packets. (But small datagrams around 500 bytes that are not truncated by process-send-string are usually fine.) Note further that the UDP protocol does not guard against lost packets.

Function: open-network-server-stream name buffer-or-name host service &optional protocol acceptor filter sentinel

This function establishes listening for TCP connections for a service to the local host. It returns a process object to represent the listening connection.

When a new connection request arrives, it is automatically accepted. A network-stream process is automatically created for that connection. If needed a new buffer is also created. If given the acceptor function is called. If defined filter and sentinel are set for the new connection process .

Input and output work as for other process objects. delete-process closes the connection.

The name argument is name for process. It is modified if necessary to make it unique. This name is taken as the basis for the name of the accepted connection’s processes.

The buffer-or-name is the buffer to associate with the process. Listening Process output goes at end of that buffer, unless you specify an output stream or filter function to handle the output. No real process output of listening process is expected. However the name of this buffer will be used as a base for generating a new buffer name for the accepted connections.

If buffer-or-name is nil, this process is not associated with any buffer. In this case a filter should be specified otherwise there will be no way to retrieve the process output.

When buffer-or-name is auto a buffer is automatically created for the accepted connection.

The argument host is the name of the IP to bind to, or its IP address, If it is nil or ip_any will bind to all addresses on the machine. When host is localhost, the listening connection will listen to connections from the local machine only.

The service argument is name of the service desired, or an integer specifying a port number to listen for connections.

The optional protocol argument is a network protocol. Currently tcp (Transmission Control Protocol) and udp (User Datagram Protocol) are supported. When omitted, tcp is assumed.

The argument acceptor is a function which will be called upon connection acceptance with two the accepted connection process. This can be used to exchange or accept credentials, establish an SSL layer, etc.

The acceptor takes a single argument: the network stream itself. In the function acceptor you can use network-process-listener to get the original listen process, and process-buffer to retrieve the associated buffers. If sentinels and/or filters are set in the acceptor they will override the filter and sentinel args to this function.

When the argument filter is specified the function will be set as filter for the accepted connections automatically. See set-process-filter for more details.

The optional sentinel is a function which will be set as sentinel the accepted connections automatically. see set-process-sentinel for more details.

Output via process-send-string and input via buffer or filter (see set-process-filter) are stream-oriented. That means UDP datagrams are not guaranteed to be sent and received in discrete packets. (But small datagrams around 500 bytes that are not truncated by process-send-string are usually fine.) Note further that the UDP protocol does not guard against lost packets.

Function: network-process-listener process

This function returns the process that listened and accepted the given network process. Returns nil if process is closed or was not accepted through a network server stream.

The argument process should be a network-stream process accepted through a network server stream.