Next: Network Servers, Previous: Transaction Queues, Up: Processes [Contents][Index]
41.14 Network ConnectionsEmacs Lisp programs can open stream (TCP) and datagram (UDP) network connections (see Datagrams) 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 Emacs process, has no process ID, and 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 program at the other end; that program must decide what to do about closure of the connection.
Lisp programs can listen for connections by creating network servers. A network server is also represented by a kind of process object, but unlike a network connection, the network server never transfers data itself. When it receives a connection request, it creates a new network connection to represent the connection just made. (The network connection inherits certain information, including the process plist, from the server.) The network server then goes back to listening for more connection requests.
Network connections and servers are created by calling make-network-process with an argument list consisting of keyword/argument pairs, for example :server t to create a server process, or :type 'datagram to create a datagram connection. See Low-Level Network Access, for details. You can also use the open-network-stream function described below.
To distinguish the different types of processes, the process-type function returns the symbol network for a network connection or server, serial for a serial port connection, pipe for a pipe connection, or real for a real subprocess.
The process-status function returns open, closed, connect, stop, or failed for network connections. For a network server, the status is always listen. Except for stop, none of those values is possible for a real subprocess. See Process Information.
You can stop and resume operation of a network process by calling stop-process and continue-process. For a server process, being stopped means not accepting new connections. (Up to 5 connection requests will be queued for when you resume the server; you can increase this limit, unless it is imposed by the operating system—see the :server keyword of make-network-process, make-network-process.) For a network stream connection, being stopped means not processing input (any arriving input waits until you resume the connection). For a datagram connection, some number of packets may be queued but input may be lost. You can use the function process-command to determine whether a network connection or server is stopped; a non-nil value means yes.
Emacs can create encrypted network connections, using the built-in support for the GnuTLS Transport Layer Security Library; see the GnuTLS project page. If your Emacs was compiled with GnuTLS support, the function gnutls-available-p is defined and returns non-nil. For more details, see Overview in The Emacs-GnuTLS manual. The open-network-stream function can transparently handle the details of creating encrypted connections for you, using whatever support is available.
This function opens a TCP connection, with optional encryption, and returns a process object that represents the connection.
The name argument specifies the name for the process object. It is modified as necessary to make it unique.
The buffer argument is the buffer to associate with the connection. Output from the connection is inserted in the buffer, unless you specify your own filter function to handle the output. If buffer 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 (a string), and service is the name of a defined network service (a string) or a port number (an integer like 80 or an integer string like "80").
The remaining arguments parameters are keyword/argument pairs that are mainly relevant to encrypted connections:
:nowait boolean
If non-nil, try to make an asynchronous connection.
:noquery query-flag
Initialize the process query flag to query-flag. See Querying Before Exit.
:coding coding
Use this to set the coding systems used by the network process, in preference to binding coding-system-for-read or coding-system-for-write. See make-network-process, for details.
:type type
The type of connection. Options are:
plain
An ordinary, unencrypted connection.
tls
ssl
A TLS (Transport Layer Security) connection.
nil
network
Start with a plain connection, and if parameters ‘:success’ and ‘:capability-command’ are supplied, try to upgrade to an encrypted connection via STARTTLS. If that fails, retain the unencrypted connection.
starttls
As for nil, but if STARTTLS fails, drop the connection.
shell
A shell connection.
:always-query-capabilities boolean
If non-nil, always ask for the server’s capabilities, even when doing a ‘plain’ connection.
:capability-command capability-command
Command to query the host capabilities. This can either be a string (which will then be sent verbatim to the server) or a function (called with a single parameter: the “greeting” from the server when connecting) that should return a string.
:end-of-command regexp
:end-of-capability regexp
Regular expression matching the end of a command, or the end of the command capability-command. The latter defaults to the former.
:starttls-function function
Function of one argument (the response to capability-command), which returns either nil or the command to activate STARTTLS, if supported.
:success regexp
Regular expression matching a successful STARTTLS negotiation.
:use-starttls-if-possible boolean
If non-nil, do opportunistic STARTTLS upgrades even if Emacs doesn’t have built-in TLS support.
:warn-unless-encrypted boolean
If non-nil, warn the user if the final connection type is not encrypted. This is useful for protocols like IMAP and the like, where most users would expect the network traffic to be encrypted. This may be due to STARTTLS upgrade failure, specifying :return-list non-nil allows you to capture any error encountered.
:client-certificate list-or-t
Either a list of the form (key-file cert-file), naming the certificate key file and certificate file itself, or t, meaning to query auth-source for this information (see auth-source in Emacs auth-source Library). Only used for TLS or STARTTLS. To enable automatic queries of auth-source when :client-certificate is not specified customize network-stream-use-client-certificates to t.
:return-list cons-or-nil
The return value of this function. If omitted or nil, return a process object. Otherwise, a cons of the form (process-object . plist), where plist can include the following keywords:
:greeting string-or-nil
If non-nil, the greeting string returned by the host.
:capabilities string-or-nil
If non-nil, the host’s capability string.
:type symbol
The connection type: ‘plain’ or ‘tls’.
:error symbol
A string describing any error encountered when performing STARTTLS upgrade.
:shell-command string-or-nil
If the connection type is shell, this parameter will be interpreted as a format-spec string (see Custom Format Strings) that will be executed to make the connection. The specs available are ‘%s’ for the host name and ‘%p’ for the port number. For instance, if you want to first ssh to ‘gateway’ before making a plain connection, then this parameter’s value could be something like ‘ssh gateway nc %s %p’.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4