summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorDaniel Stenberg <daniel@haxx.se>2017-09-05 11:14:42 +0200
committerDaniel Stenberg <daniel@haxx.se>2017-09-05 11:15:02 +0200
commiteae21db920b19ed0729196165f0abf54749cf6db (patch)
treee8e22ff67f702b1518aac83a4f662a56690afc8b /docs
parent889723b004667abc061f9a23e928aba064b7f2a0 (diff)
downloadcurl-eae21db920b19ed0729196165f0abf54749cf6db.tar.gz
docs/curl_mime_*.3: added examples
Diffstat (limited to 'docs')
-rw-r--r--docs/libcurl/curl_mime_addpart.315
-rw-r--r--docs/libcurl/curl_mime_data.314
-rw-r--r--docs/libcurl/curl_mime_data_cb.32
-rw-r--r--docs/libcurl/curl_mime_filedata.326
-rw-r--r--docs/libcurl/curl_mime_filename.322
-rw-r--r--docs/libcurl/curl_mime_headers.315
-rw-r--r--docs/libcurl/curl_mime_name.314
-rw-r--r--docs/libcurl/curl_mime_subparts.32
-rw-r--r--docs/libcurl/curl_mime_type.320
9 files changed, 128 insertions, 2 deletions
diff --git a/docs/libcurl/curl_mime_addpart.3 b/docs/libcurl/curl_mime_addpart.3
index 7bdd43d72..e5a72dbc4 100644
--- a/docs/libcurl/curl_mime_addpart.3
+++ b/docs/libcurl/curl_mime_addpart.3
@@ -38,6 +38,21 @@ appended.
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 EXAMPLE
+.nf
+ struct curl_mime *mime;
+ struct mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* continue and set name + data to the part */
+ curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED);
+ curl_mime_name(part, "data", CURL_ZERO_TERMINATED);
+.fi
.SH "SEE ALSO"
.BR curl_mime_init "(3),"
.BR curl_mime_name "(3),"
diff --git a/docs/libcurl/curl_mime_data.3 b/docs/libcurl/curl_mime_data.3
index c458f2d38..1b6ac235c 100644
--- a/docs/libcurl/curl_mime_data.3
+++ b/docs/libcurl/curl_mime_data.3
@@ -48,6 +48,20 @@ Setting very large data is memory consuming: one might consider using
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
+.nf
+ struct curl_mime *mime;
+ struct mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* add data to the part */
+ curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED);
+.fi
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_data_cb "(3)"
diff --git a/docs/libcurl/curl_mime_data_cb.3 b/docs/libcurl/curl_mime_data_cb.3
index 9fc975341..b174d3b37 100644
--- a/docs/libcurl/curl_mime_data_cb.3
+++ b/docs/libcurl/curl_mime_data_cb.3
@@ -156,3 +156,5 @@ int seek_callback(void *arg, curl_off_t offset, int origin)
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"
+.BR curl_mime_data "(3)"
+.BR curl_mime_name "(3)"
diff --git a/docs/libcurl/curl_mime_filedata.3 b/docs/libcurl/curl_mime_filedata.3
index e70e3b269..c0d545dbe 100644
--- a/docs/libcurl/curl_mime_filedata.3
+++ b/docs/libcurl/curl_mime_filedata.3
@@ -30,7 +30,8 @@ curl_mime_filedata - set a mime part's body data from a file contents
.ad
.SH DESCRIPTION
\fIcurl_mime_filedata(3)\fP sets a mime part's body content from the named
-file's contents.
+file's contents. This is an alernative to \fIcurl_mime_data(3)\fP for setting
+data to a mime part.
\fIpart\fP is the part's to assign contents to.
@@ -42,14 +43,35 @@ 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(3)\fP.
+The contents of the file is read during the file transfer in a streaming
+manner to allow huge files to get transfered without using much memory. It
+therefore requires that the file is kept intact during the entire request.
+
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 EXAMPLE
+.nf
+ struct curl_mime *mime;
+ struct mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* send data from this file */
+ curl_mime_filedata(part, "image.png");
+ /* set name */
+ curl_mime_name(part, "data", CURL_ZERO_TERMINATED);
+.fi
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
+.BR curl_mime_data "(3),"
.BR curl_mime_filename "(3)"
+.BR curl_mime_name "(3),"
diff --git a/docs/libcurl/curl_mime_filename.3 b/docs/libcurl/curl_mime_filename.3
index db4482cdd..5a2ca6ec2 100644
--- a/docs/libcurl/curl_mime_filename.3
+++ b/docs/libcurl/curl_mime_filename.3
@@ -35,6 +35,7 @@ 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.
@@ -45,6 +46,27 @@ name twice is valid: only the value set by the last call is retained.
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
+.nf
+ struct curl_mime *mime;
+ struct mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* send image data from memory */
+ curl_mime_data(part, imagebuf, imagebuf_len);
+
+ /* set a file name to make it look like a file upload */
+ curl_mime_filename(part, "image.png");
+
+ /* set name */
+ curl_mime_name(part, "data", CURL_ZERO_TERMINATED);
+.fi
.SH "SEE ALSO"
.BR curl_mime_addpart "(3) "
.BR curl_mime_filedata "(3) "
+.BR curl_mime_data "(3) "
diff --git a/docs/libcurl/curl_mime_headers.3 b/docs/libcurl/curl_mime_headers.3
index 34e623ae0..87724ae1b 100644
--- a/docs/libcurl/curl_mime_headers.3
+++ b/docs/libcurl/curl_mime_headers.3
@@ -46,5 +46,20 @@ the last call is retained.
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
+.nf
+ struct curl_slist *headers = NULL;
+
+ headers = curl_slist_append("Custom-Header: mooo", headers);
+
+ /* use these headers, please take ownership */
+ curl_mime_headers(part, headers, TRUE);
+
+ /* pass on this data */
+ curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED);
+
+ /* set name */
+ curl_mime_name(part, "numbers", CURL_ZERO_TERMINATED);
+.fi
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"
diff --git a/docs/libcurl/curl_mime_name.3 b/docs/libcurl/curl_mime_name.3
index 71c9d8a1e..58ee9697e 100644
--- a/docs/libcurl/curl_mime_name.3
+++ b/docs/libcurl/curl_mime_name.3
@@ -48,6 +48,20 @@ part by setting \fIname\fP to NULL.
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
+.nf
+ struct curl_mime *mime;
+ struct mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* give the part a name */
+ curl_mime_name(part, "shoe_size", CURL_ZERO_TERMINATED);
+.fi
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"
.BR curl_mime_data "(3)"
diff --git a/docs/libcurl/curl_mime_subparts.3 b/docs/libcurl/curl_mime_subparts.3
index 13d34c361..d5d46febb 100644
--- a/docs/libcurl/curl_mime_subparts.3
+++ b/docs/libcurl/curl_mime_subparts.3
@@ -46,6 +46,8 @@ is retained. It is possible to unassign previous part's contents by setting
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
+TODO
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_init "(3)"
diff --git a/docs/libcurl/curl_mime_type.3 b/docs/libcurl/curl_mime_type.3
index 6907b9462..aa6b5b27a 100644
--- a/docs/libcurl/curl_mime_type.3
+++ b/docs/libcurl/curl_mime_type.3
@@ -57,6 +57,26 @@ extension, or application/octet-stream by default.
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
+.nf
+ struct curl_mime *mime;
+ struct mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* get data from this file */
+ curl_mime_filedata(part, "image.png");
+
+ /* content-type for this part */
+ curl_mime_name(part, "image/png");
+
+ /* set name */
+ curl_mime_name(part, "image", CURL_ZERO_TERMINATED);
+.fi
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"
.BR curl_mime_name "(3)"