mime: use in curl cli tool instead of form API.

Extended -F option syntax to support multipart mail messages. -F keyword headers= added to include custom headers in parts. Documentation upgraded.
kenh · Sep 2, 2017 · fec7a85 · fec7a85
1 parent ce0881e
commit fec7a85
Show file tree

Hide file tree

Showing 17 changed files with 768 additions and 456 deletions.
diff --git a/docs/cmdline-opts/form-string.d b/docs/cmdline-opts/form-string.d
@@ -1,6 +1,6 @@
 Long: form-string
-Help: Specify HTTP multipart POST data
-Protocols: HTTP
+Help: Specify multipart MIME data
+Protocols: HTTP SMTP IMAP
 Arg: <name=string>
 See-also: form
 ---

diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d
@@ -1,21 +1,26 @@
 Long: form
 Short: F
 Arg: <name=content>
-Help: Specify HTTP multipart POST data
-Protocols: HTTP
+Help: Specify multipart MIME data
+Protocols: HTTP SMTP IMAP
 Mutexed: data head upload
 ---
-This lets curl emulate a filled-in form in which a user has pressed the submit
-button. This causes curl to POST data using the Content-Type
-multipart/form-data according to RFC 2388. This enables uploading of binary
+For HTTP protocol family, this lets curl emulate a filled-in form in which a
+user has pressed the submit button. This causes curl to POST data using the
+Content-Type multipart/form-data according to RFC 2388.
+
+For SMTP and IMAP protocols, this is the mean to compose a multipart mail
+message to transmit.
+
+This enables uploading of binary
 files etc. To force the 'content' part to be a file, prefix the file name with
 an @ sign. To just get the content part from a file, prefix the file name with
 the symbol <. The difference between @ and < is then that @ makes a file get
 attached in the post as a file upload, while the < makes a text field and just
 get the contents for that text field from a file.
 
-Example: to send an image to a server, where \&'profile' is the name of the
-form-field to which portrait.jpg will be the input:
+Example: to send an image to an HTTP server, where \&'profile' is the name of
+the form-field to which portrait.jpg will be the input:
 
  curl -F profile=@portrait.jpg https://example.com/upload.cgi
 
@@ -49,6 +54,53 @@ or
 Note that if a filename/path is quoted by double-quotes, any double-quote
 or backslash within the filename must be escaped by backslash.
 
+You can add custom headers to the field by setting headers=, like
+
+  curl -F "submit=OK;headers=\\"X-submit-type: OK\\"" example.com
+
+or
+
+  curl -F "submit=OK;headers=@headerfile" example.com
+
+The headers= keyword may appear more that once and above notes about quoting
+apply. When headers are read from a file, Empty lines and lines starting
+with '#' are comments and ignored; each header can be folded by splitting
+between two words and starting the continuation line with a space; embedded
+carriage-returns and trailing spaces are stripped.
+Here is an example of a header file contents:
+
+  # This file contain two headers.
+.br
+  X-header-1: this is a header
+
+  # The following header is folded.
+.br
+  X-header-2: this is
+.br
+   another header
+
+
+To support sending multipart mail messages, the syntax is extended as follows:
+.br
+- name can be omitted: the equal sign is the first character of the argument,
+.br
+- if data starts with '(', this signals to start a new multipart: it can be
+followed by a content type specification.
+.br
+- a multipart can be terminated with a '=)' argument.
+
+Example: the following command sends an SMTP mime e-mail consisting in an
+inline part in two alternative formats: plain text and HTML. It attaches a
+text file:
+
+ curl -F '=(;type=multipart/alternative' \\
+.br
+         -F '=plain text message' \\
+.br
+         -F '= <body>HTML message</body>;type=text/html' \\
+.br
+      -F '=)' -F '=@textfile.txt' ...  smtp://example.com
+
 See further examples and details in the MANUAL.
 
 This option can be used multiple times.
diff --git a/src/Makefile.inc b/src/Makefile.inc
@@ -45,7 +45,6 @@ CURL_CFILES = \
 	tool_libinfo.c \
 	tool_main.c \
 	tool_metalink.c \
-	tool_mfiles.c \
 	tool_msgs.c \
 	tool_operate.c \
 	tool_operhlp.c \
@@ -86,7 +85,6 @@ CURL_HFILES = \
 	tool_libinfo.h \
 	tool_main.h \
 	tool_metalink.h \
-	tool_mfiles.h \
 	tool_msgs.h \
 	tool_operate.h \
 	tool_operhlp.h \

diff --git a/src/tool_cfgable.c b/src/tool_cfgable.c
@@ -140,11 +140,11 @@ static void free_config_fields(struct OperationConfig *config)
   curl_slist_free_all(config->headers);
   curl_slist_free_all(config->proxyheaders);
 
-  if(config->httppost) {
-    curl_formfree(config->httppost);
-    config->httppost = NULL;
+  if(config->mimepost) {
+    curl_mime_free(config->mimepost);
+    config->mimepost = NULL;
   }
-  config->last_post = NULL;
+  config->mimecurrent = NULL;
 
   curl_slist_free_all(config->telnet_options);
   curl_slist_free_all(config->resolve);

diff --git a/src/tool_cfgable.h b/src/tool_cfgable.h
@@ -170,8 +170,8 @@ struct OperationConfig {
   time_t condtime;
   struct curl_slist *headers;
   struct curl_slist *proxyheaders;
-  struct curl_httppost *httppost;
-  struct curl_httppost *last_post;
+  curl_mime *mimepost;
+  curl_mime *mimecurrent;
   struct curl_slist *telnet_options;
   struct curl_slist *resolve;
   struct curl_slist *connect_to;

diff --git a/src/tool_easysrc.c b/src/tool_easysrc.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
  *
  * This software is licensed as described in the file COPYING, which
  * you should have received as part of this distribution. The terms
@@ -42,7 +42,7 @@ struct slist_wc *easysrc_data = NULL; /* Build slists, forms etc. */
 struct slist_wc *easysrc_code = NULL; /* Setopt calls */
 struct slist_wc *easysrc_toohard = NULL; /* Unconvertible setopt */
 struct slist_wc *easysrc_clean = NULL;  /* Clean up allocated data */
-int easysrc_form_count = 0;
+int easysrc_mime_count = 0;
 int easysrc_slist_count = 0;
 
 static const char *const srchead[]={

diff --git a/src/tool_easysrc.h b/src/tool_easysrc.h
@@ -7,7 +7,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
  *
  * This software is licensed as described in the file COPYING, which
  * you should have received as part of this distribution. The terms
@@ -32,7 +32,7 @@ extern struct slist_wc *easysrc_code; /* Setopt calls etc. */
 extern struct slist_wc *easysrc_toohard; /* Unconvertible setopt */
 extern struct slist_wc *easysrc_clean;  /* Clean up (reverse order) */
 
-extern int easysrc_form_count;  /* Number of curl_httppost variables */
+extern int easysrc_mime_count;  /* Number of curl_mime variables */
 extern int easysrc_slist_count; /* Number of curl_slist variables */
 
 extern CURLcode easysrc_init(void);