docs/curl_mime_*.3: added examples

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)"