docs/curl_mime_*.3: added examples

diff --git a/docs/libcurl/curl_mime_addpart.3 b/docs/libcurl/curl_mime_addpart.3
index 7bdd43d7287f2210183c2627ff9760040b652667..e5a72dbc43c04512796b4f8e67ae74d151625f9d 100644 (file)
--- 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 c458f2d38bba6d84950942acab67a26de8aa7293..1b6ac235c73d79e8729c6a4280a63a443fc74fd4 100644 (file)
--- 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 9fc9753414820741d7a8a3e6af88076609be116b..b174d3b3768c43135af36322149a5caadda3bad9 100644 (file)
--- 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 e70e3b26987283e40c0ce3702e41affcf2b7acb8..c0d545dbe8299cc858daa8670f36e4dff9a41525 100644 (file)
--- 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 db4482cdd3ad7a5b116817923855f6fd3e55cc6d..5a2ca6ec2821525aa7549a39e75361ae4baff8f5 100644 (file)
--- 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 34e623ae0ab0b06a36a64cc5f0ce86ece4984789..87724ae1b597b0a6f8f7af932f9e2cbb962d6e16 100644 (file)
--- 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 71c9d8a1eb180ecfd429ea53bc8fda4226b99ac3..58ee9697e97afb2a22ce3f4b5806493b34f78802 100644 (file)
--- 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 13d34c36107204d864d84a763f3d882abde7f55d..d5d46febb02798f6833a03f95fabb46516bf2d9e 100644 (file)
--- 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 6907b9462df7766826512807be70544daf0f6fc7..aa6b5b27ad9525421bd24a5c0756d2616b47e4af 100644 (file)
--- 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)"