HttpFormData (class)
public HttpFormData {inherits {Array-of HttpFormParam}, HttpRequestData}
Import from: CURL.GUI.STANDARD. Defined in package CURL.IO.HTTP.

Class used to format data in the style of HTML forms submissions, as indicated in RFC 1867, RFC 2388, and the HTML 4.01 specification, including the older urlencoded style. Holds a set of HttpFormParams that represent the form data.

Notes

Implements HttpRequestData.request-data and provides a new method HttpFormData.request-data-urlencoded-string to be used to make a query string for a Url out of form data.

Example

|| make an HttpFormData, will default to multipart posting
let form-data:HttpFormData = {new HttpFormData}
|| add a string parameter
{form-data.append {new HttpFormStringParam, "field1", "value1"}}
let u:Url = {url "http://www.example.com/some-file.txt"}
|| add a files parameter, with one file in it
{form-data.append
    {new HttpFormFilesParam,
        "field2",
        u.filename,
        {read-bytes-from u}
    }
}

|| now send our 2 parameter form to a webserver
let post-url:Url = {url "http://www.example.com/cgi-bin/script"}
|| will throw an HttpException if it can't get to
|| post-url, or if it returns some failure status code
let tis:TextInputStream =
    {({post-url.instantiate-File} asa HttpFile).http-read-open
        request-method = HttpRequestMethod.post,
        request-data = form-data
    }
let buf:StringBuf = {new StringBuf}
|| read in the contents that the server sent back
{try
    {tis.read-one-string buf = buf}
 finally
    || close the stream, since we read everything in
    {tis.close}
}

Constructors
default:Create an HttpFormData.
constructor public {HttpFormData.default
mime-type:String = HttpFormData.multipart-mime-type,
default-character-encoding:CharEncoding = CharEncoding.ascii,
urlencoded-separator:String = "&",
multipart-boundary:#String = null
}

Properties
content-type:The content-type of the request data.
accessor public HttpFormData.content-type:#String
default-character-encoding:See HttpFormData.default's default-character-encoding parameter.
accessor public HttpFormData.default-character-encoding:CharEncoding
setter public HttpFormData.default-character-encoding:CharEncoding
mime-type:The mime-type to use to encode the data.
accessor public HttpFormData.mime-type:String
setter public HttpFormData.mime-type:String
multipart-boundary:See HttpFormData.default's multipart-boundary parameter.
accessor public HttpFormData.multipart-boundary:String
setter public HttpFormData.multipart-boundary:#String
urlencoded-separator:See HttpFormData.default's urlencoded-separator parameter.
field public constant HttpFormData.urlencoded-separator:String ="&"
Properties inherited from Array-of: efficient-size, for-loop-count, size, underlying-FastArray
Properties inherited from Association-of: empty?, key-type
Properties inherited from Aggregate-of: element-type

Class Variables and Constants
multipart-mime-type:The MIME type name for the newer style of encoding form data, as specified in RFC 1867 and RFC 2388. This style can handle any sort of data, but may not be used in a URL's query string. The data to be used for MIME type comes from HttpFormParam.request-data-multipart-bytes for each parameter in a HttpFormData.
public constant HttpFormData.multipart-mime-type:String ="multipart/form-data"
urlencoded-mime-type:The MIME type name for the older style of encoding form data. Note that this MIME type does not allow for flexible charset use, or for file uploads, but it can be used for the query string in a URL, as long as the amount of data is small. The data to be used for MIME type comes from HttpFormParam.request-data-urlencoded-bytes or HttpFormParam.request-data-urlencoded-string for each parameter in a HttpFormData.
public constant HttpFormData.urlencoded-mime-type:String ="application/x-www-form-urlencoded"

Methods
request-data:The data derived from the HttpFormParams in self, to be sent with HTTP request.
public {HttpFormData.request-data}:{Array-of byte}
request-data-urlencoded-string:The data derived from the HttpFormParams in self, formatted for "application/x-www-form-urlencoded" (aka HttpFormData.urlencoded-mime-type) style encoding. self.mime-type must be equal to HttpFormData.urlencoded-mime-type.
public {HttpFormData.request-data-urlencoded-string}:String
Methods inherited from Array-of: append, clear, clone, clone-range, concat, equal?, filter-clone, filter-keys-clone, get, get-if-exists, in-bounds?, insert, object-serialize, pop, push, remove, reverse, set, set-size, sort, splice, top-of-stack
Methods inherited from Sequence-of: filter, filter-keys, find, key-exists?, keys-to-Iterator, to-Iterator
Methods inherited from Association-of: get-key, get-key-if-exists
Methods inherited from Object: object-describe, object-describe-for-debugging



Constructor Details
default (constructor)
public {HttpFormData.default
mime-type:String = HttpFormData.multipart-mime-type,
default-character-encoding:CharEncoding = CharEncoding.ascii,
urlencoded-separator:String = "&",
multipart-boundary:#String = null
}

Create an HttpFormData.

mime-type: Format that the data should be encoded in. Must be equal to HttpFormData.urlencoded-mime-type or HttpFormData.multipart-mime-type.
default-character-encoding: Default character-encoding to use when handling string data contained within HttpFormParams. This parameter is used only for the string data in a HttpFormStringParam if the HttpFormStringParam does not specify a character-encoding. This parameter also specifies the character-encoding used to convert the MIME related header and separator strings into bytes. Should be a CharEncoding that has CharEncoding.ascii as a subset. Normally, you should just use CharEncoding.ascii unless you need to use an encoding that does not have CharEncoding.ascii as a subset for HttpFormData.urlencoded-mime-type format data. Then this parameter needs to be compatible with or the same as the encoding being used for that.
urlencoded-separator: String used to separate parameters when mime-type is HttpFormData.urlencoded-mime-type. The standard value is "&".
multipart-boundary: String used to separate parameters when mime-type is HttpFormData.multipart-mime-type. If this parameter is null, a random value will be generated as needed. Note that the boundary must be a unique string not occurring in the data being sent.


Property Details
content-type (accessor)
accessor public HttpFormData.content-type:#String

The content-type of the request data.

Description

The string will be put in the request header as a value of "Content-Type"

Notes

This will be HttpFormData.mime-type plus possibly a charset parameter based on HttpFormData.default-character-encoding if appropriate.

default-character-encoding (accessor)
accessor public HttpFormData.default-character-encoding:CharEncoding
setter public HttpFormData.default-character-encoding:CharEncoding

See HttpFormData.default's default-character-encoding parameter.


mime-type (accessor)
accessor public HttpFormData.mime-type:String
setter public HttpFormData.mime-type:String

The mime-type to use to encode the data.

Description

The string will also be used as part of the "Content-Type" header that HttpFormData.content-type supplies.

Notes

Must be equal to HttpFormData.urlencoded-mime-type or HttpFormData.multipart-mime-type.

multipart-boundary (accessor)
accessor public HttpFormData.multipart-boundary:String
setter public HttpFormData.multipart-boundary:#String

See HttpFormData.default's multipart-boundary parameter.


urlencoded-separator (field)
public constant HttpFormData.urlencoded-separator:String ="&"

See HttpFormData.default's urlencoded-separator parameter.



Class Variable and Constant Details
multipart-mime-type (class constant)
public constant HttpFormData.multipart-mime-type:String ="multipart/form-data"

The MIME type name for the newer style of encoding form data, as specified in RFC 1867 and RFC 2388. This style can handle any sort of data, but may not be used in a URL's query string. The data to be used for MIME type comes from HttpFormParam.request-data-multipart-bytes for each parameter in a HttpFormData.


urlencoded-mime-type (class constant)
public constant HttpFormData.urlencoded-mime-type:String ="application/x-www-form-urlencoded"

The MIME type name for the older style of encoding form data. Note that this MIME type does not allow for flexible charset use, or for file uploads, but it can be used for the query string in a URL, as long as the amount of data is small. The data to be used for MIME type comes from HttpFormParam.request-data-urlencoded-bytes or HttpFormParam.request-data-urlencoded-string for each parameter in a HttpFormData.




Method Details
request-data (method)
public {HttpFormData.request-data}:{Array-of byte}

The data derived from the HttpFormParams in self, to be sent with HTTP request.

Notes

The format of this data will vary depending on the HttpFormData.mime-type.

request-data-urlencoded-string (method)
public {HttpFormData.request-data-urlencoded-string}:String

The data derived from the HttpFormParams in self, formatted for "application/x-www-form-urlencoded" (aka HttpFormData.urlencoded-mime-type) style encoding. self.mime-type must be equal to HttpFormData.urlencoded-mime-type.

Notes

This is intended only for use as the query string on a Url, for doing a GET style HTTP request with the form data.