mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-21 06:55:39 +00:00
Code Issues Releases 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
Show Stats 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.
@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}
@ -2715,6 +2717,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}

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
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.