From fec7a858b88c86e97e5dc96414a01feb21a2b661 Mon Sep 17 00:00:00 2001 From: Patrick Monnerat Date: Sat, 2 Sep 2017 18:17:33 +0100 Subject: 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. --- docs/cmdline-opts/form-string.d | 4 +-- docs/cmdline-opts/form.d | 66 ++++++++++++++++++++++++++++++++++++----- 2 files changed, 61 insertions(+), 9 deletions(-) (limited to 'docs/cmdline-opts') diff --git a/docs/cmdline-opts/form-string.d b/docs/cmdline-opts/form-string.d index 80790553c..49d0d44ef 100644 --- 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: See-also: form --- diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d index 87a7d0766..14261d3ad 100644 --- a/docs/cmdline-opts/form.d +++ b/docs/cmdline-opts/form.d @@ -1,21 +1,26 @@ Long: form Short: F Arg: -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 '= HTML message;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. -- cgit v1.2.3