Annotation of embedaddon/curl/docs/libcurl/curl_formadd.3, revision 1.1
1.1 ! misho 1: .\" **************************************************************************
! 2: .\" * _ _ ____ _
! 3: .\" * Project ___| | | | _ \| |
! 4: .\" * / __| | | | |_) | |
! 5: .\" * | (__| |_| | _ <| |___
! 6: .\" * \___|\___/|_| \_\_____|
! 7: .\" *
! 8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
! 9: .\" *
! 10: .\" * This software is licensed as described in the file COPYING, which
! 11: .\" * you should have received as part of this distribution. The terms
! 12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
! 13: .\" *
! 14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
! 15: .\" * copies of the Software, and permit persons to whom the Software is
! 16: .\" * furnished to do so, under the terms of the COPYING file.
! 17: .\" *
! 18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
! 19: .\" * KIND, either express or implied.
! 20: .\" *
! 21: .\" **************************************************************************
! 22: .TH curl_formadd 3 "March 23, 2020" "libcurl 7.70.0" "libcurl Manual"
! 23:
! 24: .SH NAME
! 25: curl_formadd - add a section to a multipart/formdata HTTP POST
! 26: .SH SYNOPSIS
! 27: .B #include <curl/curl.h>
! 28: .sp
! 29: .BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem,
! 30: .BI "struct curl_httppost ** " lastitem, " ...);"
! 31: .ad
! 32: .SH DESCRIPTION
! 33: This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
! 34:
! 35: curl_formadd() is used to append sections when building a multipart/formdata
! 36: HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
! 37: at a time until you've added all the sections you want included and then you
! 38: pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_HTTPPOST(3)\fP.
! 39: \fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated
! 40: invokes it should be left as set to allow repeated invokes to find the end of
! 41: the list faster.
! 42:
! 43: After the \fIlastitem\fP pointer follow the real arguments.
! 44:
! 45: The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
! 46: NULL in the first call to this function. All list-data will be allocated by
! 47: the function itself. You must call \fIcurl_formfree(3)\fP on the
! 48: \fIfirstitem\fP after the form post has been done to free the resources.
! 49:
! 50: Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
! 51: You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
! 52:
! 53: First, there are some basics you need to understand about multipart/formdata
! 54: posts. Each part consists of at least a NAME and a CONTENTS part. If the part
! 55: is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
! 56: Below, we'll discuss what options you use to set these properties in the
! 57: parts you want to add to your post.
! 58:
! 59: The options listed first are for making normal parts. The options from
! 60: \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
! 61: parts.
! 62: .SH OPTIONS
! 63: .IP CURLFORM_COPYNAME
! 64: followed by a string which provides the \fIname\fP of this part. libcurl
! 65: copies the string so your application doesn't need to keep it around after
! 66: this function call. If the name isn't NUL-terminated, you must set its length
! 67: with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to contain
! 68: zero-valued bytes. The copied data will be freed by \fIcurl_formfree(3)\fP.
! 69: .IP CURLFORM_PTRNAME
! 70: followed by a string which provides the \fIname\fP of this part. libcurl
! 71: will use the pointer and refer to the data in your application, so you
! 72: must make sure it remains until curl no longer needs it. If the name
! 73: isn't NUL-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
! 74: The \fIname\fP is not allowed to contain zero-valued bytes.
! 75: .IP CURLFORM_COPYCONTENTS
! 76: followed by a pointer to the contents of this part, the actual data
! 77: to send away. libcurl copies the provided data, so your application doesn't
! 78: need to keep it around after this function call. If the data isn't null
! 79: terminated, or if you'd like it to contain zero bytes, you must
! 80: set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
! 81: data will be freed by \fIcurl_formfree(3)\fP.
! 82: .IP CURLFORM_PTRCONTENTS
! 83: followed by a pointer to the contents of this part, the actual data
! 84: to send away. libcurl will use the pointer and refer to the data in your
! 85: application, so you must make sure it remains until curl no longer needs it.
! 86: If the data isn't NUL-terminated, or if you'd like it to contain zero bytes,
! 87: you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP.
! 88: .IP CURLFORM_CONTENTLEN
! 89: followed by a curl_off_t value giving the length of the contents. Note that
! 90: for \fICURLFORM_STREAM\fP contents, this option is mandatory.
! 91:
! 92: If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
! 93: the contents to figure out the size. If you really want to send a zero byte
! 94: content then you must make sure strlen() on the data pointer returns zero.
! 95:
! 96: (Option added in 7.46.0)
! 97: .IP CURLFORM_CONTENTSLENGTH
! 98: (This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!)
! 99:
! 100: followed by a long giving the length of the contents. Note that for
! 101: \fICURLFORM_STREAM\fP contents, this option is mandatory.
! 102:
! 103: If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
! 104: the contents to figure out the size. If you really want to send a zero byte
! 105: content then you must make sure strlen() on the data pointer returns zero.
! 106: .IP CURLFORM_FILECONTENT
! 107: followed by a filename, causes that file to be read and its contents used
! 108: as data in this part. This part does \fInot\fP automatically become a file
! 109: upload part simply because its data was read from a file.
! 110:
! 111: The specified file needs to kept around until the associated transfer is done.
! 112: .IP CURLFORM_FILE
! 113: followed by a filename, makes this part a file upload part. It sets the
! 114: \fIfilename\fP field to the basename of the provided filename, it reads the
! 115: contents of the file and passes them as data and sets the content-type if the
! 116: given file match one of the internally known file extensions. For
! 117: \fBCURLFORM_FILE\fP the user may send one or more files in one part by
! 118: providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
! 119: (and each \fICURLFORM_FILE\fP is allowed to have a
! 120: \fICURLFORM_CONTENTTYPE\fP).
! 121:
! 122: The given upload file has to exist in its full in the file system already when
! 123: the upload starts, as libcurl needs to read the correct file size beforehand.
! 124:
! 125: The specified file needs to kept around until the associated transfer is done.
! 126: .IP CURLFORM_CONTENTTYPE
! 127: is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
! 128: string which provides the content-type for this part, possibly instead of an
! 129: internally chosen one.
! 130: .IP CURLFORM_FILENAME
! 131: is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
! 132: string, it tells libcurl to use the given string as the \fIfilename\fP in the
! 133: file upload part instead of the actual file name.
! 134: .IP CURLFORM_BUFFER
! 135: is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
! 136: tells libcurl that the file contents are already present in a buffer. The
! 137: parameter is a string which provides the \fIfilename\fP field in the content
! 138: header.
! 139: .IP CURLFORM_BUFFERPTR
! 140: is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
! 141: to the buffer to be uploaded. This buffer must not be freed until after
! 142: \fIcurl_easy_cleanup(3)\fP is called. You must also use
! 143: \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
! 144: .IP CURLFORM_BUFFERLENGTH
! 145: is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
! 146: long which gives the length of the buffer.
! 147: .IP CURLFORM_STREAM
! 148: Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
! 149: data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
! 150: to the read callback's fourth argument. If you want the part to look like a
! 151: file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
! 152: when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
! 153: set with the total expected length of the part unless the formpost is sent
! 154: chunked encoded. (Option added in libcurl 7.18.2)
! 155: .IP CURLFORM_ARRAY
! 156: Another possibility to send options to curl_formadd() is the
! 157: \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
! 158: its value. Each curl_forms structure element has a CURLformoption and a char
! 159: pointer. The final element in the array must be a CURLFORM_END. All available
! 160: options can be used in an array, except the CURLFORM_ARRAY option itself! The
! 161: last argument in such an array must always be \fBCURLFORM_END\fP.
! 162: .IP CURLFORM_CONTENTHEADER
! 163: specifies extra headers for the form POST section. This takes a curl_slist
! 164: prepared in the usual way using \fBcurl_slist_append\fP and appends the list
! 165: of headers to those libcurl automatically generates. The list must exist while
! 166: the POST occurs, if you free it before the post completes you may experience
! 167: problems.
! 168:
! 169: When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
! 170: the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
! 171: you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
! 172:
! 173: See example below.
! 174: .SH AVAILABILITY
! 175: Deprecated in 7.56.0. Before this release, field names were allowed to
! 176: contain zero-valued bytes. The pseudo-filename "-" to read stdin is
! 177: discouraged although still supported, but data is not read before being
! 178: actually sent: the effective data size can then not be automatically
! 179: determined, resulting in a chunked encoding transfer. Backslashes and
! 180: double quotes in field and file names are now escaped before transmission.
! 181: .SH RETURN VALUE
! 182: 0 means everything was ok, non-zero means an error occurred corresponding
! 183: to a CURL_FORMADD_* constant defined in
! 184: .I <curl/curl.h>
! 185: .SH EXAMPLE
! 186: .nf
! 187:
! 188: struct curl_httppost* post = NULL;
! 189: struct curl_httppost* last = NULL;
! 190: char namebuffer[] = "name buffer";
! 191: long namelength = strlen(namebuffer);
! 192: char buffer[] = "test buffer";
! 193: char htmlbuffer[] = "<HTML>test buffer</HTML>";
! 194: long htmlbufferlength = strlen(htmlbuffer);
! 195: struct curl_forms forms[3];
! 196: char file1[] = "my-face.jpg";
! 197: char file2[] = "your-face.jpg";
! 198: /* add null character into htmlbuffer, to demonstrate that
! 199: transfers of buffers containing null characters actually work
! 200: */
! 201: htmlbuffer[8] = '\\0';
! 202:
! 203: /* Add simple name/content section */
! 204: curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
! 205: CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
! 206:
! 207: /* Add simple name/content/contenttype section */
! 208: curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
! 209: CURLFORM_COPYCONTENTS, "<HTML></HTML>",
! 210: CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
! 211:
! 212: /* Add name/ptrcontent section */
! 213: curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
! 214: CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
! 215:
! 216: /* Add ptrname/ptrcontent section */
! 217: curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
! 218: CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
! 219: namelength, CURLFORM_END);
! 220:
! 221: /* Add name/ptrcontent/contenttype section */
! 222: curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
! 223: CURLFORM_PTRCONTENTS, htmlbuffer,
! 224: CURLFORM_CONTENTSLENGTH, htmlbufferlength,
! 225: CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
! 226:
! 227: /* Add simple file section */
! 228: curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
! 229: CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
! 230:
! 231: /* Add file/contenttype section */
! 232: curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
! 233: CURLFORM_FILE, "my-face.jpg",
! 234: CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
! 235:
! 236: /* Add two file section */
! 237: curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
! 238: CURLFORM_FILE, "my-face.jpg",
! 239: CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
! 240:
! 241: /* Add two file section using CURLFORM_ARRAY */
! 242: forms[0].option = CURLFORM_FILE;
! 243: forms[0].value = file1;
! 244: forms[1].option = CURLFORM_FILE;
! 245: forms[1].value = file2;
! 246: forms[2].option = CURLFORM_END;
! 247:
! 248: /* Add a buffer to upload */
! 249: curl_formadd(&post, &last,
! 250: CURLFORM_COPYNAME, "name",
! 251: CURLFORM_BUFFER, "data",
! 252: CURLFORM_BUFFERPTR, record,
! 253: CURLFORM_BUFFERLENGTH, record_length,
! 254: CURLFORM_END);
! 255:
! 256: /* no option needed for the end marker */
! 257: curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
! 258: CURLFORM_ARRAY, forms, CURLFORM_END);
! 259: /* Add the content of a file as a normal post text value */
! 260: curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
! 261: CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
! 262: /* Set the form info */
! 263: curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
! 264:
! 265: .SH "SEE ALSO"
! 266: .BR curl_easy_setopt "(3),"
! 267: .BR curl_formfree "(3),"
! 268: .BR curl_mime_init "(3)"
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to curl_formadd.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl