moparisthebest/curl
1
0
Fork 0
mirror of https://github.com/moparisthebest/curl synced 2025-02-28 09:21:50 -05:00
Code Issues Releases Wiki Activity

DOCS: Added information for CURLOPT_MAIL_AUTH.

Browse Source 
Added information relating to the new CURLOPT_MAIL_AUTH parameter and
reworked CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT to be a clearer.

Fixed inconsistencies of "vocalisation of the abbreviation" versus
"vocalisation of the first word" for all abbreviations.

Corrected a typo in CURLOPT_NOPROXY.
This commit is contained in:
Steve Holme 2012-01-07 14:10:40 +00:00 committed by Daniel Stenberg
parent b685481d52
commit 154c0d4b93
1 changed files with 50 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
docs/libcurl/curl_easy_setopt.3
View File

@ -419,7 +419,7 @@ built against another SSL library, this functionality is absent.
Function pointer that should match the following prototype: \fBCURLcode
sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called
by libcurl just before the initialization of an SSL connection after having
by libcurl just before the initialization of a SSL connection after having
processed all other SSL related options to give a last chance to an
application to modify the behaviour of openssl's ssl initialization. The
\fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If
@ -434,7 +434,7 @@ the SSL negotiation. The SSL_CTX pointer will be a new one every time.
To use this properly, a non-trivial amount of knowledge of the openssl
libraries is necessary. For example, using this function allows you to use
openssl callbacks to add additional validation code for certificates, and even
to change the actual URI of an HTTPS request (example used in the lib509 test
to change the actual URI of a HTTPS request (example used in the lib509 test
case). See also the example section for a replacement of the key, certificate
and trust file settings.
.IP CURLOPT_SSL_CTX_DATA
@ -711,7 +711,7 @@ pop3://user:password@mail.domain.com/1 - This retrieves the first message
.B SCP
The path part of an SCP request specifies the file to retrieve and from what
The path part of a SCP request specifies the file to retrieve and from what
directory. The file part may not be omitted. The file is taken as an absolute
path from the root directory on the server. To specify a path relative to
the user's home directory on the server, prepend ~/ to the path portion.
@ -725,7 +725,7 @@ user's home directory on the server
.B SFTP
The path part of an SFTP request specifies the file to retrieve and from what
The path part of a SFTP request specifies the file to retrieve and from what
directory. If the file part is omitted then libcurl downloads the directory
listing for the directory specified. If the path ends in a / then a directory
listing is returned instead of a file. If the path is omitted entirely then
@ -778,7 +778,7 @@ proxy's port number may optionally be specified with the separate option. If
not specified, libcurl will default to using port 1080 for proxies.
\fICURLOPT_PROXYPORT\fP.
When you tell the library to use an HTTP proxy, libcurl will transparently
When you tell the library to use a HTTP proxy, libcurl will transparently
convert operations to HTTP even if you specify an FTP URL etc. This may have
an impact on what other features of the library you can use, such as
\fICURLOPT_QUOTE\fP and similar FTP specifics that don't work unless you
@ -817,7 +817,7 @@ affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version
used for "regular" HTTP requests is instead controlled with
\fICURLOPT_HTTP_VERSION\fP.
.IP CURLOPT_NOPROXY
Pass a pointer to a zero terminated string. The should be a comma separated
Pass a pointer to a zero terminated string. This should be a comma separated
list of hosts which do not use a proxy, if one is specified. The only
wildcard is a single * character, which matches all hosts, and effectively
disables the proxy. Each name in this list is matched as either a domain which
@ -1129,7 +1129,7 @@ Pass a parameter set to 1 to enable this. When enabled, libcurl will
automatically set the Referer: field in requests where it follows a Location:
redirect.
.IP CURLOPT_ACCEPT_ENCODING
Sets the contents of the Accept-Encoding: header sent in an HTTP request, and
Sets the contents of the Accept-Encoding: header sent in a HTTP request, and
enables decoding of a response when a Content-Encoding: header is received.
Three encodings are supported: \fIidentity\fP, which does nothing,
\fIdeflate\fP which requests the server to compress its response using the
@ -1157,7 +1157,7 @@ by both HTTP clients and HTTP servers.
(Added in 7.21.6)
.IP CURLOPT_FOLLOWLOCATION
A parameter set to 1 tells the library to follow any Location: header that the
server sends as part of an HTTP header.
server sends as part of a HTTP header.
This means that the library will re-send the same request on the new location
and follow new Location: headers all the way until no more such headers are
@ -1237,7 +1237,7 @@ If you issue a POST request and then want to make a HEAD or GET using the same
re-used handle, you must explicitly set the new request type using
\fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar.
.IP CURLOPT_POSTFIELDS
Pass a void * as parameter, which should be the full data to post in an HTTP
Pass a void * as parameter, which should be the full data to post in a HTTP
POST operation. You must make sure that the data is formatted the way you want
the server to receive it. libcurl will not convert or encode it for you. Most
web servers will assume this data to be url-encoded.
@ -1272,7 +1272,7 @@ Pass a curl_off_t as parameter. Use this to set the size of the
data to figure out the size. This is the large file version of the
\fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1)
.IP CURLOPT_COPYPOSTFIELDS
Pass a char * as parameter, which should be the full data to post in an HTTP
Pass a char * as parameter, which should be the full data to post in a HTTP
POST operation. It behaves as the \fICURLOPT_POSTFIELDS\fP option, but the
original data are copied by the library, allowing the application to overwrite
the original data after setting this option.
@ -1444,25 +1444,48 @@ transfer decoding will be disabled, if set to 1 it is enabled
option is set to zero. (added in 7.16.2)
.SH SMTP OPTIONS
.IP CURLOPT_MAIL_FROM
Pass a pointer to a zero terminated string as parameter. It will be used to
specify the sender address in a mail when sending an SMTP mail with libcurl.
Pass a pointer to a zero terminated string as parameter. This should be used
to specify the sender's email address when sending SMTP mail with libcurl.
An originator email address in SMTP lingo is specified within angle brackets
(<>) which libcurl will not add for you before version 7.21.4. Failing to
provide such brackets may cause the server to reject your mail.
An originator email address should be specified with angled brackets (<>)
around it, which if not specified, will be added by libcurl from version
7.21.4 onwards. Failing to provide such brackets may cause the server to
reject the email.
If this parameter is not specified then an empty address will be sent to the
mail server which may or may not cause the email to be rejected.
(Added in 7.20.0)
.IP CURLOPT_MAIL_RCPT
Pass a pointer to a linked list of recipients to pass to the server in your
SMTP mail request. The linked list should be a fully valid list of \fBstruct
SMTP mail request. The linked list should be a fully valid list of \fBstruct
curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to
create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list.
Each recipient in SMTP lingo is specified with angle brackets (<>), but should
you not use an angle bracket as first letter libcurl will assume you provide a
single email address only and enclose that with angle brackets for you.
Each recipient should be specified within a pair of angled brackets (<>),
however, should you not use an angled bracket as the first character libcurl
will assume you provided a single email address and enclose that address
within brackets for you.
(Added in 7.20.0)
.IP CURLOPT_MAIL_AUTH
Pass a pointer to a zero terminated string as parameter. This will be used
to specify the authentication address (identity) of a submitted message that
is being relayed to another server.
This optional parameter allows co-operating agents in a trusted environment to
communicate the authentication of individual messages and should only be used
by the application program, using libcurl, if the application is itself a
mail server acting in such an environment. If the application is operating as
such and the AUTH address is not known or is invalid, then an empty string
should be used for this parameter.
Unlike CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT, the address should not be
specified within a pair of angled brackets (<>). However, if an empty string
is used then a pair of brackets will be sent by libcurl as required by
RFC-2554.
(Added in 7.24.0)
.SH TFTP OPTIONS
.IP CURLOPT_TFTP_BLKSIZE
Specify block size to use for TFTP data transmission. Valid range as per RFC
@ -1684,7 +1707,7 @@ needed for this method)\fP (Added in 7.20.0)
When sent by a client, this method changes the description of the session. For
example, if a client is using the server to record a meeting, the client can
use Announce to inform the server of all the meta-information about the
session. ANNOUNCE acts like an HTTP PUT or POST just like
session. ANNOUNCE acts like a HTTP PUT or POST just like
\fICURL_RTSPREQ_SET_PARAMETER\fP (Added in 7.20.0)
.IP CURL_RTSPREQ_SETUP
Setup is used to initialize the transport layer for the session. The
@ -1707,7 +1730,7 @@ different connections. (Added in 7.20.0)
.IP CURL_RTSPREQ_GET_PARAMETER
Retrieve a parameter from the server. By default, libcurl will automatically
include a \fIContent-Type: text/parameters\fP header on all non-empty requests
unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST
unless a custom one is set. GET_PARAMETER acts just like a HTTP PUT or POST
(see \fICURL_RTSPREQ_SET_PARAMETER\fP).
Applications wishing to send a heartbeat message (e.g. in the presence of a
server-specified timeout) should send use an empty GET_PARAMETER request.
@ -1715,9 +1738,9 @@ server-specified timeout) should send use an empty GET_PARAMETER request.
.IP CURL_RTSPREQ_SET_PARAMETER
Set a parameter on the server. By default, libcurl will automatically include
a \fIContent-Type: text/parameters\fP header unless a custom one is set. The
interaction with SET_PARAMTER is much like an HTTP PUT or POST. An application
may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like an HTTP
PUT, or it may use \fICURLOPT_POSTFIELDS\fP like an HTTP POST. No chunked
interaction with SET_PARAMTER is much like a HTTP PUT or POST. An application
may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like a HTTP
PUT, or it may use \fICURLOPT_POSTFIELDS\fP like a HTTP POST. No chunked
transfers are allowed, so the application must set the
\fICURLOPT_INFILESIZE\fP in the former and \fICURLOPT_POSTFIELDSIZE\fP in the
latter. Also, there is no use of multi-part POSTs within RTSP. (Added in
@ -1779,7 +1802,7 @@ over FTP. This is a known limitation/flaw that nobody has rectified. libcurl
simply sets the mode to ASCII and performs a standard transfer.
.IP CURLOPT_PROXY_TRANSFER_MODE
Pass a long. If the value is set to 1 (one), it tells libcurl to set the
transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by
transfer mode (binary or ASCII) for FTP transfers done via a HTTP proxy, by
appending ;type=a or ;type=i to the URL. Without this setting, or it being set
to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing
FTP via a proxy. Beware that not all proxies support this feature. (Added in
@ -1817,7 +1840,7 @@ Pass a curl_off_t as parameter. It contains the offset in number of bytes that
you want the transfer to start from. (Added in 7.11.0)
.IP CURLOPT_CUSTOMREQUEST
Pass a pointer to a zero terminated string as parameter. It will be used
instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST
instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST
when doing a FTP directory listing. This is useful for doing DELETE or other
more or less obscure HTTP requests. Don't do this at will, make sure your
server supports the command first.
@ -2160,7 +2183,7 @@ Pass a long as parameter. By default, curl assumes a value of 1.
This option determines whether curl verifies the authenticity of the peer's
certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't.
When negotiating an SSL connection, the server sends a certificate indicating
When negotiating a SSL connection, the server sends a certificate indicating
its identity. Curl verifies whether the certificate is authentic, i.e. that
you can trust that the server is who the certificate says it is. This trust
is based on a chain of digital signatures, rooted in certification authority