ot::web
class HttpClient

The HttpClient class has been extensively improved in OpenTop 1.4 and now allows applications to:-

• use and manage persistent HTTP connections
• transparently support secure (HTTPS) connections using SSL/TLS
• handle proxy and origin server authorization
• communicate via configurable HTTP proxy servers including SSL proxy tunnelling
• use RFC-compliant HTTP/1.0 and HTTP/1.1
• use memory-efficient streaming of both input and output (POST) data
• modify and extend the HTTP request processing through the use of customized request handlers

Steps involved in performing an HTTP request

• Create a URL representing the resource
• Create a HttpRequest from the URL, customizing it as required
• Create an instance of an HttpClient class to handle the request
• Send the request using the sendRequest() method and interrogate the returned HttpResponse. In so doing, a TCP/IP socket connection will be established with the remote server. This class employs a HttpClientConnectionManager to make use of persistent HTTP connections and manage the network resources associated with them.
• If appropriate, read the returned entity contained within the HttpResponse

The sending of entities is described in detail within the sendRequest() and HttpRequest documentation but, in summary, it can be performed synchronously as part of the request or asynchronously, with the application streaming the data to the server before using this class again to retrieve the final result.

HTTP Authorization

Customizing and enhancing HTTP request handling

The HttpClient class has the capability to handle most HTTP requests without the need for modification. However, if custom processing is required, applications can easily modify the behaviour to fit their needs.

The way HTTP requests are handled can be modified in two ways:-

1. by enabling/disabling features
2. by registering an appropriate request handler

1. Initialization/preparation, where HttpRequestHandler::newRequest() is called on each handler to prepare them for the request.
2. Pre-processing, where HttpRequestHandler::handleRequest() is called on each handler to give them the opportunity to modify or handle the request entirely.
3. If the request is to be sent over the network, The HttpClientConnectionManager is asked for a suitable connection to the remote host. The connection manager provides either a new connection or re-uses an idle persistent connection if one is available. The request is then written on the output stream. Assuming the application will not be streaming an entity following the request, the following stages are performed...
4. The server's response is parsed into an HttpResponse object, and passed to each handler's HttpRequestHandler::handleResponseHeaders() method, where the handler has another opportunity to modify or replace the request with a new sub-request.
5. Finally, if no more modifications to the request are needed, customized processing of the response body can be performed by the handlers' HttpRequestHandler::handleResponseBody() method.

An example

    #include "ot/web/HttpRequest.h"
    #include "ot/web/HttpResponse.h"
    #include "ot/web/HttpClient.h"
    #include "ot/auxil/MemCheckSystemMonitor.h"

    #include <iostream>

    using namespace ot;
    using namespace ot::io;
    using namespace ot::web;
    using namespace std;

    void echoToStdout(InputStream* pStream)
    {
        Byte buffer[256];
        long bytesRead;
        while( (bytesRead=pStream->read(buffer, sizeof(buffer)))!=InputStream::EndOfFile)
            cout.write((char*)buffer, bytesRead);
    }

    int main(int argc, char* argv[])
    {
        auxil::MemCheckSystemMonitor monitor;
        try
        {
            URL url(OT_T("http://www.acme.org/search.php"));
            const char* search="q=OpenTop"; 
            HttpClient http;
            HttpRequest req(url);
            req.setConnectTimeout(5000); // timeout after 5 seconds 
            req.setEntity(HttpRequest::RawEntity, strlen(search), (const Byte*)search);
            req.getMimeHeaders()->setHeaderExclusive(OT_T("Content-Type"),OT_T("application/x-www-form-urlencoded"));
            
            HttpResponse resp = http.sendRequest(req);
            
            if(resp.getResponseCode() < 300)
            {
                echoToStdout(resp.getInputStream().get());
            }
        }
        catch(Exception& e)
        {
            cout << e.toString() << endl;
        }
        return 0;
    }

See also:

HttpRequest , HttpRequestHandler , HttpResponse , HttpClientConnection , HttpClientConnectionManager

Since:

OpenTop 1.4

HttpClient

 HttpClient()

Default constructor. The default constructor configures the HttpClient to support a set of standard features, and employs the global HttpClientConnectionManager for connection management.

HttpClient

 HttpClient(HttpClientConnectionManager* pMgr)

Constructor. This constructor configures the HttpClient to support a set of standard features, and employs the supplied HttpClientConnectionManager for connection management.

Parameters:

pMgr - a pointer to an instance of HttpClientConnectionManager which will be used to create and manage connections to HTTP servers.

Exceptions:

NullPointerException - if pMgr is null

getConnectionManager

RefPtr< HttpClientConnectionManager > getConnectionManager() const

Returns the connection manager employed by this HttpClient instance to create and manage TCP/IP socket connections with HTTP servers.

getFeatureFlags

long getFeatureFlags() const

Returns a bitfield containing all the features which are currently enabled for this HttpClient.

getFinalResponse

HttpResponse getFinalResponse(HttpResponse& interimResponse)

Called by the application to obtain the response to a HTTP request which included a streamed entity sent to the server. This method may only be called by passing an interim HttpResponse which resulted from a request that contained a streamed entity, and should be called when the application has finished streaming the entity to the remote server.

Exceptions:

IOException - if an I/O error occurs reading the response.
InterruptedIOException - if a socket timeout occurs.
IllegalArgumentException - if the interimResponse argument is not an interim response. This can be determined by first calling HttpResponse::isRequestInProgress().

See also:

HttpRequest::setTimeout()

registerHandler

void registerHandler(HttpRequestHandler* pHandler)

Registers an application-supplied HttpRequestHandler with this HttpClient.

Parameters:

pHandler - a pointer to the handler to register. This class will store the pointer within a RefPtr<> list, thereby increasing the reference-count for the duration that it is required.

Exceptions:

NullPointerException - if pHandler is null.

sendRequest

HttpResponse sendRequest(const HttpRequest& request)

Sends a request to the HTTP server specified by the URL contained within the passed request. See steps involved in sending a HTTP request for a detailed description of the process involved.

Parameters:

request - the HTTP request.

Returns:

either an interim or a final response. An interim response is returned if the request contains a streamed entity which the caller must write to the OutputStream contained in the returned HttpResponse; otherwise a final response is returned.

Exceptions:

IOException - if an error occurs processing the request.
InterruptedIOException - if either of the timeout values contained within the request triggers a network timeout.

Note:

Exceptions are thrown if I/O errors occur, but errors returned from the HTTP server can only be determined by interrogating the response code within the returned HttpResponse.

setConnectionManager

void setConnectionManager(HttpClientConnectionManager* pConnectionManager)

Sets the connection manager to be employed by this HttpClient instance.

Parameters:

pConnectionManager - a pointer to the HttpClientConnectionManager instance.

Exceptions:

NullPointerException - if pConnectionManager is null.

setFeatureFlags

void setFeatureFlags(int flags)

Sets a bitfield representing all the features which are enabled for this HttpClient. All the available features are described by bit values in the HttpClient::FeatureFlags enumeration. If a bit in the bitfield is switched on (a value of 1), then the corresponding feature is enabled, otherwise it is disabled and the logic associated with it will not be performed.

unregisterHandler

void unregisterHandler(HttpRequestHandler* pHandler)

Unregisters an application-supplied HttpRequestHandler from this HttpClient.

Parameters:

pHandler - a pointer to the handler to unregister.

Exceptions:

NullPointerException - if pHandler is null.