mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-06 06:20:55 -08:00
Code Issues Projects Releases Wiki Activity

Improve 'open-network-stream' documentation.

Browse source 
* 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'.
This commit is contained in:
Robert Pluim 2024-11-05 13:51:21 +01:00
parent fb55431c44
commit 3231af3727
2 changed files with 19 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

13
doc/lispref/processes.texi
View file

@ -2686,10 +2686,12 @@ If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs
doesn't have built-in @acronym{TLS} support. doesn't have built-in @acronym{TLS} support.
@item :warn-unless-encrypted @var{boolean} @item :warn-unless-encrypted @var{boolean}
If non-@code{nil}, and @code{:return-value} is also non-@code{nil}, If non-@code{nil}, warn the user if the final connection type is not
Emacs will warn if the connection isn't encrypted. This is useful for encrypted. This is useful for protocols like @acronym{IMAP} and the
protocols like @acronym{IMAP} and the like, where most users would like, where most users would expect the network traffic to be encrypted.
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 @vindex network-stream-use-client-certificates
@item :client-certificate @var{list-or-t} @item :client-certificate @var{list-or-t}
@ -2715,6 +2717,9 @@ If non-@code{nil}, the greeting string returned by the host.
If non-@code{nil}, the host's capability string. If non-@code{nil}, the host's capability string.
@item :type @var{symbol} @item :type @var{symbol}
The connection type: @samp{plain} or @samp{tls}. 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 @end table
@item :shell-command @var{string-or-nil} @item :shell-command @var{string-or-nil}

16
lisp/net/network-stream.el
View file

@ -117,15 +117,18 @@ values:
used to decode and encode the data which the process reads and used to decode and encode the data which the process reads and
writes. See `make-network-process' for details. writes. See `make-network-process' for details.
:return-list specifies this function's return value. :return-list controls the form of the function's return value.
If omitted or nil, return a process object. A non-nil means to If omitted or nil, return a process object. Anything else means to
return (PROC . PROPS), where PROC is a process object and PROPS return (PROC . PROPS), where PROC is a process object, and PROPS is a
is a plist of connection properties, with these keywords: plist of connection properties, which may include the following
keywords:
:greeting -- the greeting returned by HOST (a string), or nil. :greeting -- the greeting returned by HOST (a string), or nil.
:capabilities -- a string representing HOST's capabilities, :capabilities -- a string representing HOST's capabilities,
or nil if none could be found. or nil if none could be found.
:type -- the resulting connection type; `plain' (unencrypted) :type -- the resulting connection type; `plain' (unencrypted)
or `tls' (TLS-encrypted). 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-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 :use-starttls-if-possible is a boolean that says to do opportunistic
STARTTLS upgrades even if Emacs doesn't have built-in TLS functionality. STARTTLS upgrades even if Emacs doesn't have built-in TLS functionality.
:warn-unless-encrypted is a boolean which, if :return-list is :warn-unless-encrypted, if non-nil, warn the user if the connection
non-nil, is used warn the user if the connection isn't encrypted. 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 :nogreeting is a boolean that can be used to inhibit waiting for
a greeting from the server. a greeting from the server.