romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-07-31 09:08:03 +03:00
Code Issues Projects Releases Packages Wiki Activity

mime: new MIME API.

Browse source 
Available in HTTP, SMTP and IMAP.
Deprecates the FORM API.
See CURLOPT_MIMEPOST.
Lib code and associated documentation.
This commit is contained in:
Patrick Monnerat 2017-09-02 17:47:10 +01:00
parent 5bae72734b
commit ce0881edee
38 changed files with 2946 additions and 994 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/libcurl/Makefile.inc
View file

@ -17,4 +17,8 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \
curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \
curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3 \
curl_multi_socket_action.3 curl_multi_wait.3 libcurl-symbols.3 \
libcurl-thread.3 curl_multi_socket_all.3 curl_global_sslset.3
libcurl-thread.3 curl_multi_socket_all.3 curl_global_sslset.3 \
curl_mime_init.3 curl_mime_free.3 curl_mime_addpart.3 curl_mime_name.3 \
curl_mime_data.3 curl_mime_data_cb.3 curl_mime_filedata.3 \
curl_mime_filename.3 curl_mime_subparts.3 \
curl_mime_type.3 curl_mime_headers.3

2
docs/libcurl/curl_easy_setopt.3
View file

@ -411,6 +411,8 @@ Size of file to send. \fICURLOPT_INFILESIZE(3)\fP
Size of file to send. \fICURLOPT_INFILESIZE_LARGE(3)\fP
.IP CURLOPT_UPLOAD
Upload data. See \fICURLOPT_UPLOAD(3)\fP
.IP CURLOPT_MIMEPOST
Post/send MIME data. See \fICURLOPT_MIMEPOST(3)\fP
.IP CURLOPT_MAXFILESIZE
Maximum file size to get. See \fICURLOPT_MAXFILESIZE(3)\fP
.IP CURLOPT_MAXFILESIZE_LARGE

11
docs/libcurl/curl_formadd.3
View file

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -29,6 +29,8 @@ curl_formadd - add a section to a multipart/formdata HTTP POST
.BI "struct curl_httppost ** " lastitem, " ...);"
.ad
.SH DESCRIPTION
This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
curl_formadd() is used to append sections when building a multipart/formdata
HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
at a time until you've added all the sections you want included and then you
@ -169,6 +171,8 @@ the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
See example below.
.SH AVAILABILITY
Deprecated in 7.56.0.
.SH RETURN VALUE
0 means everything was ok, non-zero means an error occurred corresponding
to a CURL_FORMADD_* constant defined in
@ -254,5 +258,6 @@ to a CURL_FORMADD_* constant defined in
curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), "
.BR curl_formfree "(3)"
.BR curl_easy_setopt "(3),"
.BR curl_formfree "(3),"
.BR curl_mime_init "(3)"

8
docs/libcurl/curl_formfree.3
View file

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -28,6 +28,8 @@ curl_formfree - free a previously build multipart/formdata HTTP POST chain
.BI "void curl_formfree(struct curl_httppost *" form);
.ad
.SH DESCRIPTION
This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
curl_formfree() is used to clean up data previously built/appended with
\fIcurl_formadd(3)\fP. This must be called when the data has been used, which
typically means after \fIcurl_easy_perform(3)\fP has been called.
@ -38,7 +40,9 @@ the \fIcurl_formadd(3)\fP invoke(s).
\fBform\fP is the pointer as returned from a previous call to
\fIcurl_formadd(3)\fP and may be NULL.
.SH AVAILABILITY
Deprecated in 7.56.0.
.SH RETURN VALUE
None
.SH "SEE ALSO"
.BR curl_formadd "(3) "
.BR curl_formadd "(3), " curl_mime_init "(3), " curl_mime_free "(3)"

7
docs/libcurl/curl_formget.3
View file

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -65,6 +65,7 @@ request as only then will libcurl get the actual read callback to use!
return total_size;
}
.SH AVAILABILITY
This function was added in libcurl 7.15.5
This function was added in libcurl 7.15.5. The form API is deprecated in
libcurl 7.56.0.
.SH "SEE ALSO"
.BR curl_formadd "(3) "
.BR curl_formadd "(3), " curl_mime_init "(3)"

52
docs/libcurl/curl_mime_addpart.3 Normal file
View file

@ -0,0 +1,52 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_addpart 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_addpart - append a new empty part to a mime structure
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "curl_mimepart * curl_mime_addpart(curl_mime * " mime ");"
.ad
.SH DESCRIPTION
curl_mime_addpart() appends a new empty part to the given mime structure and
returns a handle to it.
The returned part can be subsequently filled using functions from the mime API.
\fImime\fP is the handle of the mime structure in which the new part must be
appended.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
A mime part structure handle, or NULL upon failure.
.SH "SEE ALSO"
.BR curl_mime_init "(3),"
.BR curl_mime_name "(3),"
.BR curl_mime_data "(3),"
.BR curl_mime_data_cb "(3),"
.BR curl_mime_filedata "(3),"
.BR curl_mime_filename "(3),"
.BR curl_mime_subparts "(3),"
.BR curl_mime_type "(3),"
.BR curl_mime_headers "(3)"

54
docs/libcurl/curl_mime_data.3 Normal file
View file

@ -0,0 +1,54 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_data 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_data - set a mime part's body data from memory
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "CURLcode curl_mime_data(curl_mimepart * " part ", const char * " data
.BI ", ssize_t " datasize ");"
.ad
.SH DESCRIPTION
curl_mime_data() sets a mime part's body content from memory data.
\fIdata\fP points to the data bytes: those are copied to the part and their
storage may safely be reused after call.
\fIdatasize\fP is the number of data bytes: it can be set to -1 to indicate
\fIdata\fP is a nul-terminated character string.
\fIpart\fP is the part's to assign contents to.
Setting a part's contents twice is valid: only the value set by the last call
is retained. It is possible to unassign part's contents by setting
\fIdata\fP to NULL.
Setting very large data is memory consuming: one might consider using
\fIcurl_mime_data_cb\fP() in such a case.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_data_cb "(3)"

154
docs/libcurl/curl_mime_data_cb.3 Normal file
View file

@ -0,0 +1,154 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_data_cb 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_data_cb - set a callback-based data source for a mime part's body
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
.br
int seekfunc(void *arg, curl_off_t offset, int origin);
.br
void freefunc(void *arg);
.sp
.BI "CURLcode curl_mime_data(curl_mimepart * " part ", curl_off_t " datasize ,
.br
.BI " curl_read_callback " readfunc ", curl_seek_callback " seekfunc ,
.br
.BI " curl_free_callback " freefunc ", void * " arg ");"
.ad
.SH DESCRIPTION
curl_mime_data_cb() sets the data source of a mime part's body content from
a data read callback function.
\fIpart\fP is the part's to assign contents to.
\fIreadfunc\fP is a pointer to a data read callback function, with a
signature as shown by the above prototype. It may not be set to NULL.
\fIseekfunc\fP is a pointer to a seek callback function, with a
signature as shown by the above prototype. This function will be used upon
resending data (i.e.: after a redirect); this pointer may be set to NULL,
in which case a resend is not possible.
\fIfreefunc\fP is a pointer to a user resource freeing callback function, with
a signature as shown by the above prototype. If no resource is to be freed,
it may safely be set to NULL. This function will be called upon mime
structure freeing.
\fIarg\fP is a user defined argument to callback functions.
The read callback function gets called by libcurl as soon as it needs to
read data in order to send it to the peer - like if you ask it to upload or
post data to the server. The data area pointed at by the pointer \fIbuffer\fP
should be filled up with at most \fIsize\fP multiplied with \fInmemb\fP number
of bytes by your function.
Your read function must then return the actual number of bytes that it stored
in that memory area. Returning 0 will signal end-of-file to the library and
cause it to stop the current transfer.
If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
server expected it, like when you've said you will upload N bytes and you
upload less than N bytes), you may experience that the server "hangs" waiting
for the rest of the data that won't come.
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
code from the transfer.
The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
The seek function gets called by libcurl to rewind input stream data or to
seek to a certain position. The function shall work like fseek(3) or lseek(3)
and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP,
although libcurl currently only passes SEEK_SET.
The callback function must return \fICURL_SEEKFUNC_OK\fP on success,
\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or
\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl
is free to work around the problem if possible. The latter can sometimes be
done by instead reading from the input or similar.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH EXAMPLE
Sending a huge data string will cause the same amount of memory to be
allocated: to avoid overhead resources consumption, one might want to use a
callback source to avoid data duplication. In this case, original data
must be retained until after the transfer terminates.
.nf
char hugedata[512000];
struct ctl {
char *buffer;
curl_off_t size;
curl_off_t position;
};
size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
{
struct ctl *p = (struct ctl *) arg;
curl_off_t sz = p->size - p->position;
nitems *= size;
if(sz > nitems)
sz = nitems;
if(sz)
memcpy(buffer, p->buffer + p->position, sz);
p->position += sz;
return sz;
}
int seek_callback(void *arg, curl_off_t offset, int origin)
{
struct ctl *p = (struct ctl *) arg;
switch(origin) {
case SEEK_END:
offset += p->size;
break;
case SEEK_CUR:
offset += p->position;
break;
}
if(offset < 0)
return CURL_SEEKFUNC_FAIL;
p->position = offset;
return CURL_SEEKFUNC_OK;
}
CURL *easy = curl_easy_init();
curl_mime *mime = curl_mime_init(easy);
curl_mimepart *part = curl_mime_addpart(mime);
struct ctl hugectl;
hugectl.buffer = hugedata;
hugectl.size = sizeof hugedata;
hugectl.position = 0;
curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
&hugectl);
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"

55
docs/libcurl/curl_mime_filedata.3 Normal file
View file

@ -0,0 +1,55 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_filedata 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_filedata - set a mime part's body data from a file contents
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "CURLcode curl_mime_filedata(curl_mimepart * " part ,
.BI " const char * " filename ");"
.ad
.SH DESCRIPTION
curl_mime_filedata() sets a mime part's body content from the named file's
contents.
\fIpart\fP is the part's to assign contents to.
\fIfilename\fP points to the nul-terminated file's path name. The pointer can
be NULL to detach previous part contents settings.
If \fIfilename\fP is "-", part contents data will be read from stdin.
Filename storage can be safely be reused after this call.
As a side effect, the part's remote file name is set to the base name of the
given \fIfilename\fP if it is a valid named file. This can be undone or
overriden by a subsequent call to \fIcurl_mime_filename\fP().
Setting a part's contents twice is valid: only the value set by the last call
is retained.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_filename "(3)"

51
docs/libcurl/curl_mime_filename.3 Normal file
View file

@ -0,0 +1,51 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_filename 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_filename - set a mime part's remote file name
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "CURLcode curl_mime_filename(curl_mimepart * " part ,
.BI "const char * " filename ");"
.ad
.SH DESCRIPTION
curl_mime_filename() sets a mime part's remote file name. When remote file
name is set, content data is processed as a file, whatever is the part's
content source. A part's remote file name is transmitted to the server in
the associated Content-Disposition generated header.
\fIpart\fP is the part's handle to assign the remote file name to.
\fIfilename\fP points to the nul-terminated file name string; it may be set to
NULL to remove a previously attached remote file name.
The remote file name string is copied into the part, thus the associated
storage may safely be released or reused after call. Setting a part's file
name twice is valid: only the value set by the last call is retained.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"

48
docs/libcurl/curl_mime_free.3 Normal file
View file

@ -0,0 +1,48 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_free 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_free - free a previously built mime structure
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "void curl_mime_free(curl_mime *" mime);
.ad
.SH DESCRIPTION
curl_mime_free() is used to clean up data previously built/appended with
\fIcurl_mime_addpart(3)\fP and other mime-handling functions.
This must be called when the data has been used, which
typically means after \fIcurl_easy_perform(3)\fP has been called.
The handle to free is the one you passed to
the \fICURLOPT_MIMEPOST(3)\fP option: attached subparts mime structures must
not be explicitly freed as they are by the top structure freeing.
\fBmime\fP is the handle as returned from a previous call to
\fIcurl_mime_init(3)\fP and may be NULL.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
None
.SH "SEE ALSO"
.BR curl_mime_init "(3)"

50
docs/libcurl/curl_mime_headers.3 Normal file
View file

@ -0,0 +1,50 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_headers 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_headers - set a mime part's custom headers
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "CURLcode curl_mime_headers(curl_mimepart * " part ,
.BI "struct curl_slist * " headers ", int " take_ownership ");"
.ad
.SH DESCRIPTION
curl_mime_headers() sets a mime part's custom headers.
\fIpart\fP is the part's handle to assign the custom headers list to.
\fIheaders\fP is the head of a list of custom headers; it may be set to
NULL to remove a previously attached custom header list.
\fItake_ownership\fP: when non-zero, causes the list to be freed upon
replacement or mime structure deletion; in this case the list must not be
freed explicitly.
Setting a part's custom headers list twice is valid: only the value set by
the last call is retained.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"

68
docs/libcurl/curl_mime_init.3 Normal file
View file

@ -0,0 +1,68 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_init 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_init - create a mime handle
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "curl_mime * curl_mime_init(CURL * " easy_handle ");"
.ad
.SH DESCRIPTION
curl_mime_init() creates a handle to a new empty mime structure intended to be
used with \fIeasy_handle\fP. This mime structure can be subsequently filled
using the mime API, then attached to \fIeasy_handle\fP using option
\fICURLOPT_MIMEPOST\fP within a \fIcurl_easy_setopt\fP() call.
Using a mime handle is the recommended way to post an HTTP form, format and
send a multi-part e-mail with SMTP or upload such an e-mail to an IMAP server.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
A mime struct handle, or NULL upon failure.
.SH EXAMPLE
.nf
CURL *easy = curl_easy_init();
struct curl_mime *mime;
struct mimepart *part;
/* Build an HTTP form with a single field named "data", */
mime = curl_mime_init(easy);
part = curl_mime_addpart(mime);
curl_mime_data(part, "This is the field data", -1);
curl_mime_name(part, "data", -1);
/* Post and send it. */
curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime);
curl_easy_setopt(easy, CURLOPT_URL, "http://example.com");
curl_easy_perform(easy);
/* Clean-up. */
curl_easy_cleanup(easy);
curl_mime_free(mime);
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_free "(3),"
.BR CURLOPT_MIMEPOST "(3)"

52
docs/libcurl/curl_mime_name.3 Normal file
View file

@ -0,0 +1,52 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_name 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_name - set a mime part's name
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "CURLcode curl_mime_name(curl_mimepart * " part ", const char * " name
.BI ", ssize_t " namesize ");"
.ad
.SH DESCRIPTION
curl_mime_name() sets a mime part's name. This is the way HTTP form fields are
named.
\fIname\fP points to the name byte string; the string may contain nul bytes
unless \fInamesize\fP is -1.
\fInamesize\fP is the name length: it can be set to -1 to indicate
\fIname\fP is a nul-terminated string.
\fIpart\fP is the part's handle to assign a name to.
The name string is copied into the part, thus the associated storage may safely
be released or reused after call. Setting a part's name twice is valid:
only the value set by the last call is retained. It is possible to "unname"
a part by setting \fIname\fP to NULL.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"

52
docs/libcurl/curl_mime_subparts.3 Normal file
View file

@ -0,0 +1,52 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_subparts 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_subparts - set subparts of a multipart mime part
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "CURLcode curl_mime_subparts(curl_mimepart * " part ,
.BI "curl_mime * " subparts ");"
.ad
.SH DESCRIPTION
curl_mime_subparts() sets a multipart mime part's content from a mime
structure.
\fIpart\fP is a handle to the multipart part.
\fIsubparts\fP is a mime structure handle holding the subparts. After
\fIcurl_mime_subparts\fP succeeds, the mime structure handle belongs to the
multipart part and must not be freed explicitly. It may however be updated
by subsequent calls to mime API functions.
Setting a part's contents twice is valid: only the value set by the last call
is retained. It is possible to unassign previous part's contents by setting
\fIsubparts\fP to NULL.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_init "(3)"

62
docs/libcurl/curl_mime_type.3 Normal file
View file

@ -0,0 +1,62 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_mime_type 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
.SH NAME
curl_mime_type - set a mime part's content type
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "CURLcode curl_mime_type(curl_mimepart * " part ,
.BI "const char * " mimetype ");"
.ad
.SH DESCRIPTION
curl_mime_type() sets a mime part's content type.
\fIpart\fP is the part's handle to assign the content type to.
\fImimetype\fP points to the nul-terminated file mime type string; it may be
set to NULL to remove a previously attached mime type.
The mime type string is copied into the part, thus the associated
storage may safely be released or reused after call. Setting a part's type
twice is valid: only the value set by the last call is retained.
In the absence of a mime type and if needed by the protocol specifications,
a default mime type is determined by the context:
.br
- If set as a custom header, use this value.
.br
- application/form-data for a HTTP form post.
.br
- If a remote file name is set, the mime type is taken from the file name
extension, or application/octet-stream by default.
.br
- For a multipart part, multipart/mixed.
.br
- text/plain in other cases.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"

11
docs/libcurl/opts/CURLOPT_HTTPPOST.3
View file

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -42,6 +42,9 @@ You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP.
When setting \fICURLOPT_HTTPPOST(3)\fP, it will automatically set
\fICURLOPT_NOBODY(3)\fP to 0.
This option is deprecated! Do not use it. Use \fICURLOPT_MIMEPOST(3)\fP
instead after having prepared mime data.
.SH DEFAULT
NULL
.SH PROTOCOLS
@ -71,9 +74,9 @@ curl_formadd(&formpost,
CURLFORM_END);
.fi
.SH AVAILABILITY
As long as HTTP is enabled
As long as HTTP is enabled. Deprecated in 7.56.0.
.SH RETURN VALUE
Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POST "(3), "
.BR curl_formadd "(3), " curl_formfree "(3), "
.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POST "(3), " CURLOPT_MIMEPOST "(3),"
.BR curl_formadd "(3), " curl_formfree "(3), " curl_mime_init "(3)"

52
docs/libcurl/opts/CURLOPT_MIMEPOST.3 Normal file
View file

@ -0,0 +1,52 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MIMEPOST 3 "22 Aug 2017" "libcurl 7.56.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MIMEPOST \- set post/send data from mime structure
.SH SYNOPSIS
.nf
#include <curl/curl.h>
curl_mime *mime;
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIMEPOST, mime);
.SH DESCRIPTION
Pass a mime handle previously obtained from \fIcurl_mime_init()\fP.
This setting is supported by the HTTP protocol to post forms and by the
SMTP and IMAP protocols to provide the e-mail data to send/upload.
This option is the preferred way of posting an HTTP form, replacing
and extending the deprecated \fICURLOPT_HTTPPOST\fP option.
.SH PROTOCOLS
HTTP, SMTP, IMAP.
.SH AVAILABILITY
Since 7.56.0.
.SH RETURN VALUE
This will return CURLE_OK.
.SH EXAMPLE
Using this option implies the use of several mime structure building
functions: see https://curl.haxx.se/libcurl/c/smtp-mime.html for a complete
example.
.SH "SEE ALSO"
.BR curl_mime_init "(3)"

1
docs/libcurl/opts/Makefile.inc
View file

@ -175,6 +175,7 @@ man_MANS = \
CURLOPT_MAXREDIRS.3 \
CURLOPT_MAX_RECV_SPEED_LARGE.3 \
CURLOPT_MAX_SEND_SPEED_LARGE.3 \
CURLOPT_MIMEPOST.3 \
CURLOPT_NETRC.3 \
CURLOPT_NETRC_FILE.3 \
CURLOPT_NEW_DIRECTORY_PERMS.3 \

1
docs/libcurl/symbols-in-versions
View file

@ -441,6 +441,7 @@ CURLOPT_MAXFILESIZE_LARGE 7.11.0
CURLOPT_MAXREDIRS 7.5
CURLOPT_MAX_RECV_SPEED_LARGE 7.15.5
CURLOPT_MAX_SEND_SPEED_LARGE 7.15.5
CURLOPT_MIMEPOST 7.56.0
CURLOPT_MUTE 7.1 7.8 7.15.5
CURLOPT_NETRC 7.1
CURLOPT_NETRC_FILE 7.11.0