Function: open-network-stream
open-network-stream is an autoloaded and byte-compiled function
defined in network-stream.el.gz.
Signature
(open-network-stream NAME BUFFER HOST SERVICE &rest PARAMETERS)
Documentation
Open a TCP connection to HOST, optionally with encryption.
Normally, return a network process object; with a non-nil
:return-list parameter, return a list instead (see below).
Input and output work as for subprocesses; delete-process
closes it.
NAME is the name for the process. It is modified if necessary to
make it unique.
BUFFER is a buffer or buffer name to associate with the process.
Process output goes at end of that buffer. BUFFER may be nil,
meaning that the process is not associated with any buffer.
HOST is the name or IP address of the host to connect to.
SERVICE is the name of the service desired, or an integer or
integer string specifying a port number to connect to.
The remaining PARAMETERS should be a sequence of keywords and values:
:type specifies the connection type, one of the following:
nil or network
-- Begin with an ordinary network connection, and if
the parameters :success and :capability-command
are also supplied, try to upgrade to an encrypted
connection via STARTTLS. Even if that
fails (e.g. if HOST does not support TLS), retain
an unencrypted connection.
plain -- An ordinary, unencrypted network connection.
starttls -- Begin with an ordinary connection, and try
upgrading via STARTTLS. If that fails for any
reason, drop the connection; in that case the
returned object is a killed process.
tls -- A TLS connection.
ssl -- Equivalent to tls.
shell -- A shell connection.
:coding is a symbol or a cons used to specify the coding systems
used to decode and encode the data which the process reads and
writes. See make-network-process for details.
:return-list controls the form of the function's return value.
If omitted or nil, return a process object. Anything else means to
return (PROC . PROPS), where PROC is a process object, and PROPS is a
plist of connection properties, which may include the following
keywords:
:greeting -- the greeting returned by HOST (a string), or nil.
:capabilities -- a string representing HOST's capabilities,
or nil if none could be found.
:type -- the resulting connection type; plain (unencrypted)
or tls (TLS-encrypted).
:error -- A string describing any error when attempting
to negotiate STARTTLS.
:end-of-command specifies a regexp matching the end of a command.
:end-of-capability specifies a regexp matching the end of the
response to the command specified for :capability-command.
It defaults to the regexp specified for :end-of-command.
:success specifies a regexp matching a message indicating a
successful STARTTLS negotiation. For instance, the default
should be "^3" for an NNTP connection.
:capability-command specifies a command used to query the HOST
for its capabilities. For instance, for IMAP this should be
"1 CAPABILITY\\r\\n". 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),
and should return a string to send to the server.
:starttls-function specifies a function for handling STARTTLS.
This function should take one parameter, the response to the
capability command, and should return the command to switch on
STARTTLS if the server supports STARTTLS, and nil otherwise.
:always-query-capabilities says whether to query the server for
capabilities, even if we're doing a plain network connection.
:client-certificate should either be a list where the first
element is the certificate key file name, and the second
element is the certificate file name itself, or t, which means
that auth-source will be queried for the key and the
certificate. This parameter will only be used when doing TLS
or STARTTLS connections. To enable automatic queries of
auth-source when :client-certificate is not specified
customize network-stream-use-client-certificates to t.
:use-starttls-if-possible is a boolean that says to do opportunistic
STARTTLS upgrades even if Emacs doesn't have built-in TLS functionality.
:warn-unless-encrypted, if non-nil, warn the user if the connection
isn't encrypted (i.e. STARTTLS failed). Additionally, setting
:return-list non-nil allows capturing any error response.
:nogreeting is a boolean that can be used to inhibit waiting for
a greeting from the server.
:nowait, if non-nil, says the connection should be made
asynchronously, if possible.
:noquery - when exiting Emacs and the network process is running,
don't query the user if it's non-nil.
:shell-command is a format-spec string that can be used if
:type is shell. It has two specs, %s for host and %p for port
number. Example: "ssh gateway nc %s %p".
:tls-parameters is a list that should be supplied if you're
opening a TLS connection. The first element is the TLS
type (either gnutls-x509pki or gnutls-anon), and the
remaining elements should be a keyword list accepted by
gnutls-boot (as returned by gnutls-boot-parameters).
Probably introduced at or before Emacs version 18.
Aliases
open-protocol-stream (obsolete since 26.1)
Source Code
;; Defined in /usr/src/emacs/lisp/net/network-stream.el.gz
;;;###autoload
(defun open-network-stream (name buffer host service &rest parameters)
"Open a TCP connection to HOST, optionally with encryption.
Normally, return a network process object; with a non-nil
:return-list parameter, return a list instead (see below).
Input and output work as for subprocesses; `delete-process'
closes it.
NAME is the name for the process. It is modified if necessary to
make it unique.
BUFFER is a buffer or buffer name to associate with the process.
Process output goes at end of that buffer. BUFFER may be nil,
meaning that the process is not associated with any buffer.
HOST is the name or IP address of the host to connect to.
SERVICE is the name of the service desired, or an integer or
integer string specifying a port number to connect to.
The remaining PARAMETERS should be a sequence of keywords and
values:
:type specifies the connection type, one of the following:
nil or `network'
-- Begin with an ordinary network connection, and if
the parameters :success and :capability-command
are also supplied, try to upgrade to an encrypted
connection via STARTTLS. Even if that
fails (e.g. if HOST does not support TLS), retain
an unencrypted connection.
`plain' -- An ordinary, unencrypted network connection.
`starttls' -- Begin with an ordinary connection, and try
upgrading via STARTTLS. If that fails for any
reason, drop the connection; in that case the
returned object is a killed process.
`tls' -- A TLS connection.
`ssl' -- Equivalent to `tls'.
`shell' -- A shell connection.
:coding is a symbol or a cons used to specify the coding systems
used to decode and encode the data which the process reads and
writes. See `make-network-process' for details.
:return-list controls the form of the function's return value.
If omitted or nil, return a process object. Anything else means to
return (PROC . PROPS), where PROC is a process object, and PROPS is a
plist of connection properties, which may include the following
keywords:
:greeting -- the greeting returned by HOST (a string), or nil.
:capabilities -- a string representing HOST's capabilities,
or nil if none could be found.
:type -- the resulting connection type; `plain' (unencrypted)
or `tls' (TLS-encrypted).
:error -- A string describing any error when attempting
to negotiate STARTTLS.
:end-of-command specifies a regexp matching the end of a command.
:end-of-capability specifies a regexp matching the end of the
response to the command specified for :capability-command.
It defaults to the regexp specified for :end-of-command.
:success specifies a regexp matching a message indicating a
successful STARTTLS negotiation. For instance, the default
should be \"^3\" for an NNTP connection.
:capability-command specifies a command used to query the HOST
for its capabilities. For instance, for IMAP this should be
\"1 CAPABILITY\\r\\n\". 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),
and should return a string to send to the server.
:starttls-function specifies a function for handling STARTTLS.
This function should take one parameter, the response to the
capability command, and should return the command to switch on
STARTTLS if the server supports STARTTLS, and nil otherwise.
:always-query-capabilities says whether to query the server for
capabilities, even if we're doing a `plain' network connection.
:client-certificate should either be a list where the first
element is the certificate key file name, and the second
element is the certificate file name itself, or t, which means
that `auth-source' will be queried for the key and the
certificate. This parameter will only be used when doing TLS
or STARTTLS connections. To enable automatic queries of
`auth-source' when `:client-certificate' is not specified
customize `network-stream-use-client-certificates' to t.
:use-starttls-if-possible is a boolean that says to do opportunistic
STARTTLS upgrades even if Emacs doesn't have built-in TLS functionality.
:warn-unless-encrypted, if non-nil, warn the user if the connection
isn't encrypted (i.e. STARTTLS failed). Additionally, setting
:return-list non-nil allows capturing any error response.
:nogreeting is a boolean that can be used to inhibit waiting for
a greeting from the server.
:nowait, if non-nil, says the connection should be made
asynchronously, if possible.
:noquery - when exiting Emacs and the network process is running,
don't query the user if it's non-nil.
:shell-command is a `format-spec' string that can be used if
:type is `shell'. It has two specs, %s for host and %p for port
number. Example: \"ssh gateway nc %s %p\".
:tls-parameters is a list that should be supplied if you're
opening a TLS connection. The first element is the TLS
type (either `gnutls-x509pki' or `gnutls-anon'), and the
remaining elements should be a keyword list accepted by
gnutls-boot (as returned by `gnutls-boot-parameters')."
(unless (featurep 'make-network-process)
(error "Emacs was compiled without networking support"))
(let ((type (plist-get parameters :type))
(return-list (plist-get parameters :return-list)))
(if (and (not return-list)
(or (eq type 'plain)
(and (memq type '(nil network))
(not (and (plist-get parameters :success)
(plist-get parameters :capability-command))))))
;; The simplest case: wrapper around `make-network-process'.
(make-network-process :name name :buffer buffer
:host (puny-encode-domain host) :service service
:nowait (plist-get parameters :nowait)
:noquery (plist-get parameters :noquery)
:tls-parameters
(plist-get parameters :tls-parameters)
:coding (plist-get parameters :coding))
(let ((work-buffer (or buffer
(generate-new-buffer " *stream buffer*")))
(fun (cond ((and (eq type 'plain)
(not (plist-get parameters
:always-query-capabilities)))
'network-stream-open-plain)
((memq type '(nil network starttls plain))
'network-stream-open-starttls)
((memq type '(tls ssl)) 'network-stream-open-tls)
((eq type 'shell) 'network-stream-open-shell)
(t (error "Invalid connection type %s" type))))
(parameters
(if (and network-stream-use-client-certificates
(not (plist-member parameters :client-certificate)))
(plist-put parameters :client-certificate t)
parameters))
result)
(unwind-protect
(setq result (funcall fun name work-buffer host service parameters))
(unless buffer
(and (processp (car result))
(set-process-buffer (car result) nil))
(kill-buffer work-buffer)))
(if return-list
(list (car result)
:greeting (nth 1 result)
:capabilities (nth 2 result)
:type (nth 3 result)
:error (nth 4 result))
(car result))))))