ot::web
class URLEncodedFormEmulator

application/x-www-form-urlencoded is defined in the HTML 4.0 Recommendation, but even though HTML is designed to be transmitted over an 8-bit protocol (HTTP), URLs are designed to be sent over protocols which only permit 7-bit byte values. They are also designed to be parsed quite simply, with the first whitespace character indicating the end of a URL. To accommodate these two requirements, certain control characters and non-ascii characters are encoded using an escape sequence.

Specifically, Unicode strings are application/x-www-form-urlencoded by first converting each Unicode character into a sequence of bytes using a specified transport encoding (the default is UTF-8). The resulting byte sequence is then transformed once more to replace non-ascii byte values with a %HH escape mechanism (where HH is the hexadecimal value of the byte it replaces). The equal sign and ampersand have special meaning so they are escaped when they appear in field names and values. As whitespace is not permitted within the entity, the space character is replaced with a '+'.

    using namespace ot;
    using namespace ot::web;

    RefPtr<InputStream> searchGoogle(const String& keywords)
    {
        // create a form emulator for application/x-www-form-urlencoded
        // to help construct the request URL
        RefPtr<FormEmulator> rpForm(new URLEncodedForEmulator);

        // populate the form...
        rpForm->addField(OT_T("q"), keywords);
        // ask Google to return a French results page
        rpForm->addField(OT_T("hl"), OT_T("fr"));

        // create a URL to perform the Google search
        String google = OT_T("http://www.google.com/search?");
        URL googleSearchURL(google + rpForm->getEntityAsString());

        // perform a HTTP GET request...
        HttpRequest request(googleSearchURL);
        HttpClient http;
        HttpResponse response = http.sendRequest(request);

        // ... and return the server's response
        if(response.getResponseCode() == 200)
            return response.getInputStream();
        else
            throw IOException(response.getResponseLine());
    }

Note:

Filename fields are not supported by this class. Use the MultipartFormEmulator class if you wish to include file data within a form entity.

See also:

FormEmulator , MultipartFormEmulator , HttpClient , HttpResponse

Since:

OpenTop 1.5

URLEncodedFormEmulator

 URLEncodedFormEmulator()

Default constructor. A default UTF-8 Unicode encoder will be used when formatting field names and values before they are HH escaped. If the server application is expecting a different encoding, use the overloaded constructor which takes an encoding name as its parameter.

URLEncodedFormEmulator

 URLEncodedFormEmulator(const String& encoding)

Constructs a URLEncodedFormEmulator with a specified Unicode encoding name. The encoding parameter specifies the Unicode character encoding used for formatting field names and values before they are HH escaped..

Exceptions:

UnsupportedEncodingException - if encoding is not a supported character encoding.

addField

virtual void addField(const String& name,
                      const String& value)

Inserts a name/value pair field to the end of the sequence of fields contained by this form. The fieldName and value parameters are converted from Unicode strings into byte strings using the configured transport encoding.

Parameters:

fieldName - the name of the field.
value - a Unicode string containing the value of the field.

addFilenameField

virtual void addFilenameField(const String& fieldName,
                              const File& file,
                              const String& filename,
                              const String& encoding,
                              const String& mimeType)

Inserts a filename field to the end of the sequence of fields contained by this form. File contents cannot be transmitted using the application/x-www-form-urlencoded encoding, so this method throws an UnsupportedOperationException.

Exceptions:

UnsupportedOperationException - because this class does not support file transfer operations.

addFilenameField

virtual void addFilenameField(const String& fieldName,
                              InputStream* pStream,
                              const String& filename,
                              const String& encoding,
                              Int64Type fileLength,
                              const String& mimeType)

Inserts a filename field to the end of the sequence of fields contained by this form. Filename fields differ from other fields in that they cause the contents of the specified file to be transmitted as part of the form entity. In this function the file's contents are represented by an InputStream. The provided stream will not be read until the form entity is transmitted, but it should be noted that this can only be performed once; forms containing InputStream filename fields can only be transmitted once, whereas those containing filename fields constructed from a File object can be transmitted multiple times because a fresh InputStream is opened on each occasion.

Parameters:

fieldName - the name of the field.
pStream - the contents of the file represented as an InputStream.
filename - the name for the file. If this is not specified an IllegalArgumentException is thrown.
encoding - the name of the byte encoding of the file (if any). The encoding name is not used locally to decipher the file but is passed as a hint to the receiving host.
mimeType - the MIME type of the file. If not specified, a MIME type of application/octet-stream is assumed.

Exceptions:

UnsupportedOperationException - if the implementation does not support file transfer operations. The MultipartFormEmulator class is one known implementation of this interface which does offer file transfer support.
IllegalArgumentException - if filename is an empty String.

clear

virtual void clear()

Clears all the fields, returning the form to its newly constructed state.

getContentTypeHeader

virtual String getContentTypeHeader() const

Returns a Content-Type header value describing the MIME type of the form entity. The returned header value will depend on the encoding provided by the implementation class.

It is advisable to use this method when constructing a HTTP request rather than assuming a constant value for the Content-Type header. One important reason for this is that the Content-Type header contains a variable separator parameter when describing the multipart/form-data encoding.

Returns:

a String value such as application/x-www-form-urlencoded or multipart/form-data; separator=xxxx.

getEntity

virtual RefPtr< InputStream > getEntity() const

Returns an InputStream which provides a contiguous stream of bytes constituting the form entity. This entity is formatted for transmission as the POST data of a HTTP request.

This function can be called repeatedly, with each invocation returning a RefPtr to a new InputStream. In most cases the returned InputStream can be read without affecting the internal state of this form because it is generated from the form's field without altering their state. The notable exception to this case is when a filename field has been added using the overloaded method which takes an InputStream parameter. In this case the filename field's InputStream is returned as part of a SequenceInputStream, and this stream can be read only once. In this case, subsequent calls to this function will result in an IOException.

Returns:

a RefPtr to an InputStream representing the form entity.

Exceptions:

IOException - if an error occurs while creating the InputStream or if this function is called more than once on a form containing an InputStream filename field.

getEntityAsString

String getEntityAsString() const

Returns the entity for this form as a String. This function may be useful when this form is being used to construct the query part of a URL.

getEntityLength

virtual Int64Type getEntityLength() const

Returns the length of the form entity. In cases where the length of the entity cannot be determined (i.e. when a filename field of unknown length has been inserted), a value of -1 is returned.

Returns:

the length of the form entity or -1 if the length cannot be determined.

writeEntity

void writeEntity(OutputStream* pOutputStream) const

Writes the form entity to the supplied OutputStream. This function can normally be called repeatedly, with each invocation writing the form entity to the supplied stream. The notable exception to this case is when a filename field has been added using the InputStream overloaded method. In this case the filename field's InputStream is copied to the OutputStream before being closed. Further attempts to read the closed stream will result in an IOException.

Parameters:

pStream - the OutputStream to write to.

Exceptions:

IOException - if an error occurs writing to the OutputStream or reading from a filename field's InputStream.
NullPointerException - if pStream is null.