curl_formadd man page on RedHat

Man page or keyword search:  
man Server   29550 pages
apropos Keyword Search (all sections)
Output format
RedHat logo
[printable version]

curl_formadd(3)			libcurl Manual		       curl_formadd(3)

NAME
       curl_formadd - add a section to a multipart/formdata HTTP POST

SYNOPSIS
       #include <curl/curl.h>

       CURLFORMcode  curl_formadd(struct  curl_httppost	 **  firstitem, struct
       curl_httppost ** lastitem, ...);

DESCRIPTION
       curl_formadd() is used  to  append  sections  when  building  a	multi‐
       part/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 pass the firstitem pointer as parameter to
       CURLOPT_HTTPPOST.  lastitem is set after each curl_formadd(3) call  and
       on  repeated invokes it should be left as set to allow repeated invokes
       to find the end of the list faster.

       After the lastitem pointer follow the real arguments.

       The pointers firstitem and lastitem should both be pointing to NULL  in
       the first call to this function. All list-data will be allocated by the
       function itself. You must call curl_formfree(3) on the firstitemP after
       the form post has been done to free the resources.

       Using  POST  with  HTTP 1.1 implies the use of a "Expect: 100-continue"
       header.	You can disable this header with CURLOPT_HTTPHEADER as usual.

       First, there are some  basics  you  need	 to  understand	 about	multi‐
       part/formdata  posts.  Each part consists of at least a NAME and a CON‐
       TENTS part. If the part is made for  file  upload,  there  are  also  a
       stored  CONTENT-TYPE and a FILENAME.  Below, we'll discuss what options
       you use to set these properties in the parts you want to	 add  to  your
       post.

       The  options listed first are for making normal parts. The options from
       CURLFORM_FILE through CURLFORM_BUFFERLENGTH are for file upload parts.

OPTIONS
       CURLFORM_COPYNAME
	      followed by a string which  provides  the	 name  of  this	 part.
	      libcurl  copies  the  string so your application doesn't need to
	      keep it around after this function call. If the name isn't  NUL-
	      terminated,  or if you'd like it to contain zero bytes, you must
	      set its length with CURLFORM_NAMELENGTH. The copied data will be
	      freed by curl_formfree(3).

       CURLFORM_PTRNAME
	      followed	by  a  string  which  provides	the name of this part.
	      libcurl will use the pointer and	refer  to  the	data  in  your
	      application,  so	you  must  make	 sure it remains until curl no
	      longer needs it. If the name isn't NUL-terminated, or  if	 you'd
	      like  it	to  contain  zero  bytes, you must set its length with
	      CURLFORM_NAMELENGTH.

       CURLFORM_COPYCONTENTS
	      followed by a pointer to the contents of this part,  the	actual
	      data  to	send  away.  libcurl copies the provided data, so your
	      application doesn't need to keep it around after	this  function
	      call.  If the data isn't null terminated, or if you'd like it to
	      contain zero bytes, you must set the length  of  the  name  with
	      CURLFORM_CONTENTSLENGTH.	The  copied  data  will	 be  freed  by
	      curl_formfree(3).

       CURLFORM_PTRCONTENTS
	      followed by a pointer to the contents of this part,  the	actual
	      data to send away. libcurl will use the pointer and refer to the
	      data in your application, so you must make sure it remains until
	      curl  no	longer needs it.  If the data isn't NUL-terminated, or
	      if you'd like it to contain zero bytes, you must set its	length
	      with CURLFORM_CONTENTSLENGTH.

       CURLFORM_CONTENTSLENGTH
	      followed	by a long giving the length of the contents. Note that
	      for CURLFORM_STREAM contents, this option is mandatory.

       CURLFORM_FILECONTENT
	      followed by a filename, causes that file to be read and its con‐
	      tents  used  as  data in this part. This part does not automati‐
	      cally become a file upload part simply because its data was read
	      from a file.

       CURLFORM_FILE
	      followed	by  a filename, makes this part a file upload part. It
	      sets the filename field to the basename of  the  provided	 file‐
	      name,  it reads the contents of the file and passes them as data
	      and sets the content-type if the given file  match  one  of  the
	      internally  known	 file  extensions.  For CURLFORM_FILE the user
	      may send one or more files in one	 part  by  providing  multiple
	      CURLFORM_FILE  arguments each followed by the filename (and each
	      CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE).

       CURLFORM_CONTENTTYPE
	      is used in combination with CURLFORM_FILE. Followed by a pointer
	      to  a string which provides the content-type for this part, pos‐
	      sibly instead of an internally chosen one.

       CURLFORM_FILENAME
	      is used in combination with CURLFORM_FILE. Followed by a pointer
	      to  a  string,  it  tells libcurl to use the given string as the
	      filename in the file upload part	instead	 of  the  actual  file
	      name.

       CURLFORM_BUFFER
	      is  used	for  custom  file  upload  parts  without use of CURL‐
	      FORM_FILE.  It tells libcurl that the file contents are  already
	      present  in  a buffer.  The parameter is a string which provides
	      the filename field in the content header.

       CURLFORM_BUFFERPTR
	      is used in combination with CURLFORM_BUFFER. The parameter is  a
	      pointer  to  the	buffer to be uploaded. This buffer must not be
	      freed until after curl_easy_cleanup(3) is called. You must  also
	      use CURLFORM_BUFFERLENGTH to set the number of bytes in the buf‐
	      fer.

       CURLFORM_BUFFERLENGTH
	      is used in combination with CURLFORM_BUFFER. The parameter is  a
	      long which gives the length of the buffer.

       CURLFORM_STREAM
	      Tells  libcurl  to  use the CURLOPT_READFUNCTION callback to get
	      data. The parameter you pass to CURLFORM_STREAM is  the  pointer
	      passed  on  to  the read callback's fourth argument. If you want
	      the part to look like a file upload one, set the	CURLFORM_FILE‐
	      NAME  parameter  as  well. Note that when using CURLFORM_STREAM,
	      CURLFORM_CONTENTSLENGTH must also be set with the total expected
	      length of the part. (Option added in libcurl 7.18.2)

       CURLFORM_ARRAY
	      Another  possibility  to	send  options to curl_formadd() is the
	      CURLFORM_ARRAY option, that passes  a  struct  curl_forms	 array
	      pointer  as  its	value. Each curl_forms structure element has a
	      CURLformoption and a char pointer.  The  final  element  in  the
	      array  must be a CURLFORM_END. All available options can be used
	      in an array, except the CURLFORM_ARRAY option itself!  The  last
	      argument in such an array must always be CURLFORM_END.

       CURLFORM_CONTENTHEADER
	      specifies extra headers for the form POST section.  This takes a
	      curl_slist prepared in the usual way using curl_slist_append and
	      appends  the list of headers to those libcurl automatically gen‐
	      erates. The list must exist while the POST occurs, if  you  free
	      it before the post completes you may experience problems.

	      When  you've  passed the HttpPost pointer to curl_easy_setopt(3)
	      (using the CURLOPT_HTTPPOST option), you must not free the  list
	      until after you've called curl_easy_cleanup(3) for the curl han‐
	      dle.

	      See example below.

RETURN VALUE
       0 means everything was ok, non-zero means an error occurred correspond‐
       ing to a CURL_FORMADD_* constant defined in <curl/curl.h>

EXAMPLE
	struct curl_httppost* post = NULL;
	struct curl_httppost* last = NULL;
	char namebuffer[] = "name buffer";
	long namelength = strlen(namebuffer);
	char buffer[] = "test buffer";
	char htmlbuffer[] = "<HTML>test buffer</HTML>";
	long htmlbufferlength = strlen(htmlbuffer);
	struct curl_forms forms[3];
	char file1[] = "my-face.jpg";
	char file2[] = "your-face.jpg";
	/* add null character into htmlbuffer, to demonstrate that
	   transfers of buffers containing null characters actually work
	*/
	htmlbuffer[8] = '\0';

	/* Add simple name/content section */
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
		     CURLFORM_COPYCONTENTS, "content", CURLFORM_END);

	/* Add simple name/content/contenttype section */
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
		     CURLFORM_COPYCONTENTS, "<HTML></HTML>",
		     CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);

	/* Add name/ptrcontent section */
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
		     CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);

	/* Add ptrname/ptrcontent section */
	curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
		     CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
		     namelength, CURLFORM_END);

	/* Add name/ptrcontent/contenttype section */
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
		     CURLFORM_PTRCONTENTS, htmlbuffer,
		     CURLFORM_CONTENTSLENGTH, htmlbufferlength,
		     CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);

	/* Add simple file section */
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
		     CURLFORM_FILE, "my-face.jpg", CURLFORM_END);

	/* Add file/contenttype section */
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
		     CURLFORM_FILE, "my-face.jpg",
		     CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);

	/* Add two file section */
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
		     CURLFORM_FILE, "my-face.jpg",
		     CURLFORM_FILE, "your-face.jpg", CURLFORM_END);

	/* Add two file section using CURLFORM_ARRAY */
	forms[0].option = CURLFORM_FILE;
	forms[0].value	= file1;
	forms[1].option = CURLFORM_FILE;
	forms[1].value	= file2;
	forms[2].option	 = CURLFORM_END;

	/* Add a buffer to upload */
	curl_formadd(&post, &last,
		     CURLFORM_COPYNAME, "name",
		     CURLFORM_BUFFER, "data",
		     CURLFORM_BUFFERPTR, record,
		     CURLFORM_BUFFERLENGTH, record_length,
		     CURLFORM_END);

	/* no option needed for the end marker */
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
		     CURLFORM_ARRAY, forms, CURLFORM_END);
	/* Add the content of a file as a normal post text value */
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
		     CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
	/* Set the form info */
	curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);

SEE ALSO
       curl_easy_setopt(3), curl_formfree(3)

libcurl 7.9.8			 24 June 2002		       curl_formadd(3)
[top]

List of man pages available for RedHat

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net