diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile.am | 4 | ||||
| -rw-r--r-- | docs/curl_easy_setopt.3 | 2 | ||||
| -rw-r--r-- | docs/curl_formadd.3 | 114 | ||||
| -rw-r--r-- | docs/curl_formfree.3 | 8 | ||||
| -rw-r--r-- | docs/curl_formparse.3 | 4 | ||||
| -rw-r--r-- | docs/curl_slist_append.3 | 2 | ||||
| -rw-r--r-- | docs/examples/Makefile.am | 2 | ||||
| -rw-r--r-- | docs/libcurl.3 | 7 |
8 files changed, 133 insertions, 10 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am index afd79abf8..7520a5c76 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -13,6 +13,7 @@ man_MANS = \ curl_easy_perform.3 \ curl_easy_setopt.3 \ curl_formparse.3 \ + curl_formadd.3 \ curl_formfree.3 \ curl_getdate.3 \ curl_getenv.3 \ @@ -38,6 +39,7 @@ HTMLPAGES = \ curl_easy_init.html \ curl_easy_perform.html \ curl_easy_setopt.html \ + curl_formadd.html \ curl_formparse.html \ curl_formfree.html \ curl_getdate.html \ @@ -56,7 +58,7 @@ HTMLPAGES = \ EXTRA_DIST = $(man_MANS) \ MANUAL BUGS CONTRIBUTE FAQ FEATURES INTERNALS \ - LIBCURL README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS \ + README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS \ $(HTMLPAGES) MAN2HTML= gnroff -man $< | man2html >$@ diff --git a/docs/curl_easy_setopt.3 b/docs/curl_easy_setopt.3 index 6665c9c0f..1a21a3cc4 100644 --- a/docs/curl_easy_setopt.3 +++ b/docs/curl_easy_setopt.3 @@ -275,7 +275,7 @@ instruct what data to pass on to the server. Pass a pointer to a linked list of HTTP post structs as parameter. The linked list should be a fully valid list of 'struct HttpPost' structs properly filled in. The best and most elegant way to do this, is to use -.I curl_formparse(3) +.I curl_formadd(3) as documented. The data in this list must remained intact until you close this curl handle again with curl_easy_cleanup(). .TP diff --git a/docs/curl_formadd.3 b/docs/curl_formadd.3 new file mode 100644 index 000000000..d16328817 --- /dev/null +++ b/docs/curl_formadd.3 @@ -0,0 +1,114 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_formadd 3 "19 August 2001" "libcurl 7.9" "libcurl Manual" +.SH NAME +curl_formadd - add a section to a multipart/formdata HTTP POST +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "CURLcode curl_formadd(struct HttpPost ** " firstitem, +.BI "struct HttpPost ** " lastitem, " ...);" +.ad +.SH DESCRIPTION +curl_formadd() is used to append sections when building a multipart/formdata +HTTP POST (sometimes refered to as rfc1867-style posts). Append one section at +a time until you've added all the sections you want included and then you pass +the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. +\fIlastitem\fP is set after each call and on repeated invokes it should be +left as set to allow repeated invokes to find the end of the list in a faster +way. + +After \fIlastitem\fP follow the real arguments that constitute the +new section (if the following description confuses you jump directly +to the examples): + +The first is always CURLFORM_COPYNAME followed by a string used for +the name of the section. + +Afterwards one may use one of three arguments: CURLFORM_COPYCONTENTS, +CURLFORM_PTRCONTENTS, or CURLFORM_FILE. followed by a char or void +pointer (allowed for PTRCONTENTS). + +The next argument may be CURLFORM_CONTENTTYPE if the +user wishes to specify one (for FILE if no type is given the library +tries to provide the correct one; for CONTENTS no Content-Type is sent +in this case) + +For CURLFORM_PTRCONTENTS the user may also add CURLFORM_CONTENTSLENGTH +followed by the length as a long (if not given the library will use +strlen to determine the length; for COPYCONTENTS this is always done). + +For CURLFORM_FILE the user may send multiple files in one section by +providing multiple CURLFORM_FILE arguments each followed by the filename +(and each FILE is allowed to have a CONTENTTYPE). + +The last argument always is CURLFORM_END. + +The pointers \fI*firstitem\fP and \fI*lastitem\fP 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 \fIcurl_formfree\fP after the form post has +been done to free the resources again. + +This function will copy all input data except the data pointed to by +the argument after CURLFORM_PTRCONTENTS and keep its own +version of it allocated until you call \fIcurl_formfree\fP. When +you've passed the pointer to \fIcurl_easy_setopt\fP, you must not free +the list until after you've called \fIcurl_easy_cleanup\fP for the +curl handle. If you provide a pointer as an argument after +CURLFORM_PTRCONTENTS you must ensure that the pointer stays valid +until you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP. + +See example below. +.SH RETURN VALUE +Returns non-zero if an error occurs. +.SH EXAMPLE +.nf + + HttpPost* post = NULL; + HttpPost* last = NULL; + char buffer[] = "test buffer"; + char htmlbuffer[] = "<HTML>test buffer</HTML>"; + long htmlbufferlength = strlen(htmlbuffer); + /* 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, &past, CURLFORM_COPYNAME, "name_for_ptrcontent", + CURLFORM_PTRCONTENTS, buffer, 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); + /* Set the form info */ + curl_easy_setopt(curl, CURLOPT_HTTPPOST, post); + +.SH "SEE ALSO" +.BR curl_easy_setopt "(3), " +.BR curl_formparse "(3) [deprecated], " +.BR curl_formfree "(3) +.SH BUGS +Surely there are some, you tell me! + diff --git a/docs/curl_formfree.3 b/docs/curl_formfree.3 index 38c53681e..3bf3f999b 100644 --- a/docs/curl_formfree.3 +++ b/docs/curl_formfree.3 @@ -12,12 +12,14 @@ curl_formfree - free a previously build multipart/formdata HTTP POST chain .ad .SH DESCRIPTION curl_formfree() is used to clean up data previously built/appended with -curl_formparse(). This must be called when the data has been used, which -typically means after the curl_easy_perform() has been called. +curl_formadd()/curl_formparse(). This must be called when the data has +been used, which typically means after the curl_easy_perform() has +been called. .SH RETURN VALUE None .SH "SEE ALSO" -.BR curl_formparse "(3) " +.BR curl_formparse "(3) [deprecated], " +.BR curl_formadd "(3) " .SH BUGS libcurl 7.7.1 and earlier versions does not allow a NULL pointer to be used as argument. diff --git a/docs/curl_formparse.3 b/docs/curl_formparse.3 index 6f0286adf..46d48e1fc 100644 --- a/docs/curl_formparse.3 +++ b/docs/curl_formparse.3 @@ -4,7 +4,8 @@ .\" .TH curl_formparse 3 "21 May 2001" "libcurl 7.7.4" "libcurl Manual" .SH NAME -curl_formparse - add a section to a multipart/formdata HTTP POST +curl_formparse - add a section to a multipart/formdata HTTP POST: +deprecated (use curl_formadd instead) .SH SYNOPSIS .B #include <curl/curl.h> .sp @@ -79,6 +80,7 @@ Returns non-zero if an error occurs. .SH "SEE ALSO" .BR curl_easy_setopt "(3), " +.BR curl_formadd "(3), " .BR curl_formfree "(3) .SH BUGS Surely there are some, you tell me! diff --git a/docs/curl_slist_append.3 b/docs/curl_slist_append.3 index b8a02cfed..4737b989b 100644 --- a/docs/curl_slist_append.3 +++ b/docs/curl_slist_append.3 @@ -8,7 +8,7 @@ curl_slist_append - add a string to an slist .SH SYNOPSIS .B #include <curl/curl.h> .sp -.BI "struct curl_slist *curl_slist_append(struct curl_slit *" list, +.BI "struct curl_slist *curl_slist_append(struct curl_slist *" list, .BI "const char * "string ");" .ad .SH DESCRIPTION diff --git a/docs/examples/Makefile.am b/docs/examples/Makefile.am index eca6447a1..909c76100 100644 --- a/docs/examples/Makefile.am +++ b/docs/examples/Makefile.am @@ -4,7 +4,7 @@ AUTOMAKE_OPTIONS = foreign no-dependencies -EXTRA_DIST = README curlgtk.c sepheaders.c simple.c postit.c \ +EXTRA_DIST = README curlgtk.c sepheaders.c simple.c postit.c postit2.c \ win32sockets.c persistant.c ftpget.c Makefile.example \ multithread.c getinmemory.c diff --git a/docs/libcurl.3 b/docs/libcurl.3 index 445ee73eb..94de31d3e 100644 --- a/docs/libcurl.3 +++ b/docs/libcurl.3 @@ -53,11 +53,14 @@ portable environment variable reader .B curl_easy_getinfo() get information about a performed transfer .TP -.B curl_formparse() +.B curl_formadd() helps building a HTTP form POST .TP +.B curl_formparse() +helps building a HTTP form POST (deprecated since 7.9 use curl_formadd()!) +.TP .B curl_formfree() -free a list built with curl_formparse() +free a list built with curl_formparse()/curl_formadd() .TP .B curl_slist_append() builds a linked list |