Info Catalog elisp: Transaction Queues elisp: Processes elisp: Network Servers

elisp: Network

 
 36.14 Network Connections
 =========================
 
 Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
 connections (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.  
 Low-Level Network, 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.  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’, Network Processes.)
 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 either built-in
 or external support.  The built-in support uses the GnuTLS Transport
 Layer Security Library; see the GnuTLS project page
 (http://www.gnu.org/software/gnutls/).  If your Emacs was compiled with
 GnuTLS support, the function ‘gnutls-available-p’ is defined and returns
 non-‘nil’.  For more details, Overview (emacs-gnutls)Top.  The
 external support uses the ‘starttls.el’ library, which requires a helper
 utility such as ‘gnutls-cli’ to be installed on the system.  The
 ‘open-network-stream’ function can transparently handle the details of
 creating encrypted connections for you, using whatever support is
 available.
 
  -- Function: open-network-stream name buffer host service &rest
           parameters
      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).
 
      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.
 
      ‘: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 string to query the host capabilities.
 
      ‘: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’, and ‘:return-value’ is also non-‘nil’, Emacs
           will warn if the connection isn’t encrypted.  This is useful
           for protocols like IMAP and the like, where most users would
           expect the network traffic to be encrypted.
 
      ‘: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 (
           Overview (auth)Top.).  Only used for TLS or STARTTLS.
 
      ‘: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 has 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’.
 

Info Catalog elisp: Transaction Queues elisp: Processes elisp: Network Servers