From: Robert Pluim Date: Tue, 5 Nov 2024 12:51:21 +0000 (+0100) Subject: Improve 'open-network-stream' documentation. X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=cc17d3ecd4536d51bc02960b7f7226211452b797;p=emacs.git Improve 'open-network-stream' documentation. * doc/lispref/processes.texi (Network): Correct explanation of ':warn-unless-encrypted'. Document ':error' return keyword. * lisp/net/network-stream.el (open-network-stream): Improve ':return-list' documentation. Document ':error'. Correct explanation of ':warn-unless-encrypted'. (cherry picked from commit 3231af3727b450404efd6f49ddf5c95c5a8cbb0f) --- diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index bad0f7534e1..eaa465ce7b8 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -2684,10 +2684,12 @@ If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs doesn't have built-in @acronym{TLS} support. @item :warn-unless-encrypted @var{boolean} -If non-@code{nil}, and @code{:return-value} is also non-@code{nil}, -Emacs will warn if the connection isn't encrypted. This is useful for -protocols like @acronym{IMAP} and the like, where most users would -expect the network traffic to be encrypted. +If non-@code{nil}, warn the user if the final connection type is not +encrypted. This is useful for protocols like @acronym{IMAP} and the +like, where most users would expect the network traffic to be encrypted. +This may be due to @acronym{STARTTLS} upgrade failure, specifying +@code{:return-list} non-@code{nil} allows you to capture any error +encountered. @vindex network-stream-use-client-certificates @item :client-certificate @var{list-or-t} @@ -2713,6 +2715,9 @@ If non-@code{nil}, the greeting string returned by the host. If non-@code{nil}, the host's capability string. @item :type @var{symbol} The connection type: @samp{plain} or @samp{tls}. +@item :error @var{symbol} +A string describing any error encountered when perfoming +@acronym{STARTTLS} upgrade. @end table @item :shell-command @var{string-or-nil} diff --git a/lisp/net/network-stream.el b/lisp/net/network-stream.el index dcb3ad61f6d..89d3e4f19c1 100644 --- a/lisp/net/network-stream.el +++ b/lisp/net/network-stream.el @@ -117,15 +117,18 @@ values: used to decode and encode the data which the process reads and writes. See `make-network-process' for details. -:return-list specifies this function's return value. - If omitted or nil, return a process object. A non-nil means to - return (PROC . PROPS), where PROC is a process object and PROPS - is a plist of connection properties, with these keywords: +: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. @@ -164,8 +167,9 @@ writes. See `make-network-process' for details. :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 is a boolean which, if :return-list is -non-nil, is used warn the user if the connection isn't encrypted. +: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.