Georg Huettenegger's patch curl-7.8.1-pre5-patch-20010819

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