ot::web
class HttpRequest

Member functions are provided to set the HTTP method employed, the URL of the resource to be accessed, the MIME-type headers, entity details, network timeouts and the version of the HTTP protocol to use.

Sending a HTTP request

This class is used to capture all the details of a HTTP request but it is unable to actually perform the request. The HttpClient class should be used in conjunction with this one in order to send requests to HTTP servers.

Including an entity with a HTTP request

An HTTP request may contain an entity to send to an origin server (usually via the POST or PUT methods). When the application wishes to send an entity, it does so by first making a call to setEntity() to specify how the entity should be sent.

The HttpRequest class (with support from HttpClient), provides applications with three alternative ways of sending an entity:-

1. by specifying a raw data buffer which is sent as part of the request.
2. by providing an InputStream from which the entity will be copied during the tranmission of the request.
3. by sending the request headers and returning an interim response object containing an OutputStream that should be used to stream the entity to the server, before retrieving the server's final response.

1. by providing a Content-Length entity header, or
2. by using the chunked transfer encoding, where the entity is split into blocks, with each block containing a length prefix. In either case, OpenTop applications do not need to explicitly set the entity headers, these will be set automatically by the HTTP framework classes.

See also:

HttpClient , HttpResponse

Since:

OpenTop 1.4

HttpRequest

 HttpRequest(const URL& url)

Constructs a new HttpRequest from a URL. The newly constructed HttpRequest will be set up to use GET as the HTTP access method, any available version of the HTTP protocol and no timeout on read requests from the peer network host.

See also:

setTimeout() , setMethod()

getConnectTimeout

size_t getConnectTimeout() const

Returns the timeout value (in milliseconds) used when establishing a new TCP/IP connection for this HttpRequest.

See also:

setConnectTimeout()

getEntityInputStream

RefPtr< InputStream > getEntityInputStream() const

Returns the application-supplied entity InputStream.

See also:

setEntity()

getEntityLength

size_t getEntityLength() const

Returns the length of the entity that will be sent with this HTTP request.

See also:

setEntity()

getEntityType

EntityType getEntityType() const

Returns the type of entity that will be sent with this HTTP request.

See also:

setEntity()

getMethod

const String& getMethod() const

Returns The HTTP method (e.g. GET or POST) for this HTTP request.

Returns:

The HTTP method for this HTTP request.

See also:

setMethod()

getMimeHeaders

RefPtr< MimeHeaderSequence > getMimeHeaders() const

Returns the sequence of MIME-type headers associated with this HttpRequest. When a HttpRequest is first constructed, its MIME header sequence is empty.

A non-const RefPtr is returned which can be used to manipulate the header sequence, either adding or removing headers as appropriate. When this request is sent to a server, the MIME header sequence is sent immediately after the request line. In some cases, the HTTP protocol demands certain headers are present with a particular value (e.g. the Host header). In these cases, the header values set by the application may be overridden.

getProtocolVersion

HttpProtocolVersion getProtocolVersion() const

Returns the version of the HTTP protocol to be used when processing this request.

See also:

setProtocolVersion()

getRawEntityData

const Byte* getRawEntityData() const

Returns a pointer to an application-supplied data buffer containing the entity to be sent with this request.

Note:

The application is responsible for allocating and freeing the data buffer, and must ensure that the buffer is valid before passing this HttpRequest object to the HttpClient::send() method.

See also:

setEntity()

getTimeout

size_t getTimeout() const

Returns the timeout value (in milliseconds) used for TCP/IP network send and receive operations for this HttpRequest.

See also:

setTimeout()

getURL

const URL& getURL() const

Returns the URL of the resource that will be accessed via this HttpRequest.

See also:

setURL()

hasEntity

bool hasEntity() const

Tests if this HttpRequest has an entity to send along with the request. @resturns true if this request includes an entity; false otherwise.

See also:

setEntity()

isIdempotent

bool isIdempotent() const

Tests if this HttpRequest has the property of Idempotence. The side effect of N > 0 identical idempotent requests is the same as for a single request.

The methods GET, HEAD, PUT, OPTIONS, TRACE and DELETE all share this property.

setConnectTimeout

void setConnectTimeout(size_t timeoutMS)

Sets the timeout value (in milliseconds) used when establishing a new TCP/IP connection for this HttpRequest.

See also:

getConnectTimout()

setEntity

void setEntity(EntityType type,
               size_t length,
               const Byte* pRawData,
               InputStream* pInoutStream,
               const String& mimeType)

Specifies details of the entity to be transmitted along with this HTTP request. This function is used to specify:-

• The entity type, which is used to control when and how the entity is sent. If the entity type is set to either RawEntity or InputStreamEntity, the entity is transmitted at the same time as the request. Alternatively, a value of OutputStreamEntity causes an OutputStream object to be made available for the application to stream the entity body to the remote server after the request headers have been transmitted. A value of NoEntity causes no entity to be transmitted.
• The entity length, which the application can provide if the length of the entity is known before the request is initiated. The length is mandatory (but may be zero) for the RawEntity type and is optional for the two stream enity types. For the stream entity types, a length of zero indicates that the end of the entity will be signalled by an EndOfFile marker indicator (InputStreamEntity) or the stream's closure (OutputStreamEntity). For the RawEntity type a length of zero indicates a zero-length (i.e. empty) entity, which is subtely different to a type of NoEntity.
• The address of a byte buffer containing the entity. This must be provided when the entity type is RawEntity and must be null for all other entity types.
• An InputStream which must be provided when the entity type is InputStreamEntity and must be null for all other entity types. When an InputStream is provided, bytes are copied directly from the InputStream to the HTTP connection immediately after the request header has been sent. If an entity length is provided, exactly that number of bytes will be read from the InputStream otherwise the stream will be read until EndOfFile is reached.

When very large entities are going to be sent, it is more memory-efficient to use the streamed entity types as these do not require additional buffering. However, the RawEntity type is often more appropriate when the entity is small as this often involves a little less work for the application programmer.

If a length is specified, OpenTop will use this value to generate a Content-Length header field. Where no length is provided, the protocol version of this request must be set to HTTP/1.1 or above in order to allow the use of the chunked transfer encoding. It it worth noting that many HTTP/1.1 servers do not accept chunked entities because security flaws have been discovered in both the Apache and IIS implementations.

The mimeType argument describes the MIME type of the entity and is used to generate a Content-Type header field unless the application has already provided one. When mimeType is an empty string, a MIME type of application/x-www-form-urlencoded is assumed as this is often specified when sending FORM data to a HTTP server. Further information about MIME types and form processing is described in the documentation for the OpenTop FormEmulator interface.

For convenience, the method field of this HttpRequest is changed from the default value of 'GET' to 'POST' if an entity type other than NoEntity is specified.

See the class description (above) for general information about sending entities.

Parameters:

type - the entity type.
length - the length of the entity (if known).
pRawData - a pointer to a block of memory containing the entity to send. This argument may only be provided for the RawEntity type, and the length must be specified also. The memory for the supplied buffer is managed by the application and must remain allocated until after this request has been transmitted.
pInputStream - a pointer to an InputStream containing the entity to send. This argument may only be provided for the InputStreamEntity type.
mimeType - the MIME type of the entity.

Exceptions:

IllegalArgumentException - if inconsistent arguments are passed, e.g. specifying the RawEntity type without a data pointer.

See also:

FormEmulator

setMethod

void setMethod(const String& method)

Sets the HTTP method to be used when sending this HttpRequest to a server. The default method is GET, but other methods may be configured by calling this member function before the request is sent.

setProtocolVersion

void setProtocolVersion(HttpProtocolVersion version)

Sets the version of the HTTP protocol to be used when processing this request.

Note:

The protocol version is used when allocating a TCP/IP connection for a request. If an existing persistent connection with a server exists, but does not support the protocol version being requested, a new connection will be allocated.

See also:

getProtocolVersion()

setTimeout

void setTimeout(size_t timeoutMS)

Sets the timeout value (in milliseconds) used for TCP/IP network send and receive operations for this HttpRequest. When a TCP/IP connection is allocated to a HttpRequest, the SO_TIMEOUT value of the underlying socket is configured to use the value set by this method.

See also:

getTimout()

setURL

void setURL(const URL& url)

Sets the URL of the resource that will be accessed via this HttpRequest. The URL is used when sending a HTTP request to a server, and is used to identify a resource on an origin server.

Parameters:

url - the URL to use.