ot::web
class FormEmulator  (abstract)

This class defines a simple yet flexible interface which allows an application to construct an entity (a sequence of bytes) by specifying the name and value for one or more form fields. When all the desired fields have been added, the entity may be extracted and submitted to a Web server via a HTTP POST request. The Emulator part of the name alludes to the fact that there is no actual form (or any HTML) involved in the process, but the entity that is sent to the server is constructed just as it would be if a HTML form was sent from a Web browser.

The HTML 4.0 Recommendation defines two encoding methods which can be used for transporting form data: application/x-www-form-urlencoded and multipart/form-data. OpenTop provides implementations for both of these encodings via the URLEncodedFormEmulator and MultipartFormEmulator classes.

    using namespace ot;
    using namespace ot::web;

    void uploadFile(const URL& url, const File& file)
    {
        // create a form emulator for multipart/form-data
        RefPtr<FormEmulator> rpForm(new MultipartForEmulator);
        
        // populate the form...
        rpForm->addFilenameField(OT_T("theFile"), file);

        // construct an HTTP request from the form data...
        HttpRequest request(url);
        request.setEntity(HttpRequest::InputStreamEntity,
                          rpForm->getEntityLength(), 0,
                          rpForm->getEntity(), rpForm->getContentTypeHeader());

        // and finally send the request complete with form entity
        HttpClient http;
        HttpResponse response = http.sendRequest(request);
        if(response.getResponseCode() != 200)
        {
            throw IOException(response.getResponseLine());
        }
    }

Since:

OpenTop 1.5

addField

virtual void addField(const String& fieldName,
                      const String& value)=0

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)=0

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. The file is not opened until an entity is requested via getEntity() or writeEntity().

Parameters:

fieldName - the name of the field.
file - the abstract filename of the local file to transmit as part of the form entity.
filename - an optional name for the file. If this is not specified, the filename will be taken from the file parameter.
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.

addFilenameField

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

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()=0

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

getContentTypeHeader

virtual String getContentTypeHeader() const=0

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=0

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.

getEntityLength

virtual Int64Type getEntityLength() const=0

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

virtual void writeEntity(OutputStream* pStream) const=0

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.