post multipart

• command to provide the ability to post multipart data to a server
• new in 1.54

 post multipart contentToSend to URL serverURL

• In the example above, contentToSend can be a single text value or list of values to send including the contents of one or more files, or may be a property list or list of property lists to provide more control over the format in which the data is transmitted or supply additional information about the contents. The following example will upload a file to the server:

        post multipart (filename:"/tmp/xyz", body:file "/tmp/xyz" as data) to URL serverURL

    Specifying "as data" causes the file contents to be encoded in base64. Including the filename is optional, but recommended when sending a file.

• The full set of rules for the content being posted is as follows:

    • If the content value is a list, then each item in the list is treated as a separate part of the multipart content, with the rules below being applied to each part (the individual parts may not be lists -- subparts are not supported).

    • If the content value is a binary data value (typically achieved by using the "as data" operator), the body will automatically be encoded in base64, with appropriate Content-Type and Content-Transfer-Encoding header values supplied.

    • If the content value is not binary data and is not a property list, the string value of the content will be used as the body, with the "Content-Type: text/plain" header supplied.

    • If the content value is a property list, it provides both the body content plus optional header information. The following properties have special meaning:

        Body-- Required. Its value is the body content of this part, as either a data or text string value, or -- at the top level only -- as a list of content values, as described by these rules.

        Header-- A property list defining additional header fields. This is only required if headers with the same name as other keys in the content property list are needed. Otherwise, header key/value pairs can be included directly in the content property list.

        Disposition -- Used in forming the "Content-Disposition" header. Suitable values are "inline", "attachment", and so forth. If not given, "form-data" will be used.

        FieldName -- Used in forming the "Content-Disposition" header. If a form field name is not given, a name such as "field1", "field2", etc. will be generated automatically.

        FileName -- Used in forming the "Content-Disposition" header. If given, this is included as part of the Content-Disposition header. It is recommended that a FileName be included when uploading a file.

• Some special rules apply if a property list is used at the top level (not as a part within a list). The Body at this level may be a list. Also, the following additional properties are recognized:

        MultipartBoundary -- A text string used to separate the parts (if not given, a suitable string will be generated automatically). If a custom "Content-Type" header is supplied at the top level, it should include a boundary string, and MultipartBoundary must be included with that same boundary string as its value.

        TopHeader-- A property list defining additional header fields at the top level of the message. Alternatively, top level header fields can be given with the URL being posted to by specifying with headers headerFields after the URL. If a "MIME-Version" property is not given in TopHeader, it will automatically be included with a value of "1.0". If a "Content-Type" property is not included, one will automatically be generated which specifies a content type of "multipart/form-data" and a boundary string as defined by the MultipartBoundary property (or generated automatically it none is specified).

    Any additional properties in each part that don't have special meaning are treated as header fields for that part of the message. The following header fields are generated automatically if they are not included in either the content property list or in its Header property list:

        If a "Content-Disposition" property is not included, a Content-Disposition header is generated automatically using the values supplied for Disposition, FieldName, and FileName or their defaults, as described above for each of these properties.

        If a "Content-Type" property is not included, a Content-Type header is generated automatically.

• Related: post, post xmlrpc, url