class Poco::Net::HTTPClientSession

Overview

This class implements the client-side of a HTTP session. More…

#include <HTTPClientSession.h>

class HTTPClientSession: public Poco::Net::HTTPSession
{
public:
    // structs

    struct ProxyConfig;

    // construction

    HTTPClientSession();
    HTTPClientSession(const StreamSocket& socket);
    HTTPClientSession(const SocketAddress& address);

    HTTPClientSession(
        const std::string& host,
        Poco::UInt16 port = HTTPSession::HTTP_PORT
        );

    HTTPClientSession(
        const std::string& host,
        Poco::UInt16 port,
        const ProxyConfig& proxyConfig
        );

    // methods

    void
    setHost(const std::string& host);

    const std::string&
    getHost() const;

    void
    setPort(Poco::UInt16 port);

    Poco::UInt16
    getPort() const;

    void
    setProxy(
        const std::string& host,
        Poco::UInt16 port = HTTPSession::HTTP_PORT
        );

    void
    setProxyHost(const std::string& host);

    void
    setProxyPort(Poco::UInt16 port);

    const std::string&
    getProxyHost() const;

    Poco::UInt16
    getProxyPort() const;

    void
    setProxyCredentials(
        const std::string& username,
        const std::string& password
        );

    void
    setProxyUsername(const std::string& username);

    const std::string&
    getProxyUsername() const;

    void
    setProxyPassword(const std::string& password);

    const std::string&
    getProxyPassword() const;

    void
    setProxyConfig(const ProxyConfig& config);

    const ProxyConfig&
    getProxyConfig() const;

    void
    setKeepAliveTimeout(const Poco::Timespan& timeout);

    const Poco::Timespan&
    getKeepAliveTimeout() const;

    virtual
    std::ostream&
    sendRequest(HTTPRequest& request);

    virtual
    std::istream&
    receiveResponse(HTTPResponse& response);

    void
    reset();

    virtual
    bool
    secure() const;

    bool
    bypassProxy() const;

    static
    void
    setGlobalProxyConfig(const ProxyConfig& config);

    static
    const ProxyConfig&
    getGlobalProxyConfig();

protected:
    // enums

    enum
    {
        DEFAULT_KEEP_ALIVE_TIMEOUT = 8,
    };

    // methods

    void
    reconnect();

    virtual
    int
    write(
        const char* buffer,
        std::streamsize length
        );

    virtual
    std::string
    proxyRequestPrefix() const;

    virtual
    bool
    mustReconnect() const;

    virtual
    void
    proxyAuthenticate(HTTPRequest& request);

    void
    proxyAuthenticateImpl(HTTPRequest& request);

    StreamSocket
    proxyConnect();

    void
    proxyTunnel();
};

Inherited Members

public:
    // enums

    enum
    {
        HTTP_PORT = 80,
    };

    // methods

    void
    setKeepAlive(bool keepAlive);

    bool
    getKeepAlive() const;

    void
    setTimeout(const Poco::Timespan& timeout);

    Poco::Timespan
    getTimeout() const;

    bool
    connected() const;

    virtual
    void
    abort();

    const Poco::Exception*
    networkException() const;

    void
    attachSessionData(const Poco::Any& data);

    const Poco::Any&
    sessionData() const;

    StreamSocket
    detachSocket();

    StreamSocket&
    socket();

    void
    drainBuffer(Poco::Buffer<char>& buffer);

protected:
    // methods

    int
    get();

    int
    peek();

    virtual
    int
    read(
        char* buffer,
        std::streamsize length
        );

    virtual
    int
    write(
        const char* buffer,
        std::streamsize length
        );

    int
    receive(
        char* buffer,
        int length
        );

    int
    buffered() const;

    void
    refill();

    virtual
    void
    connect(const SocketAddress& address);

    void
    attachSocket(const StreamSocket& socket);

    void
    close();

    void
    setException(const Poco::Exception& exc);

    void
    clearException();

Detailed Documentation

This class implements the client-side of a HTTP session.

To send a HTTP request to a HTTP server, first instantiate a HTTPClientSession object and specify the server’s host name and port number.

Then create a HTTPRequest object, fill it accordingly, and pass it as argument to the sendRequest() method.

sendRequest() will return an output stream that can be used to send the request body, if there is any.

After you are done sending the request body, create a HTTPResponse object and pass it to receiveResponse().

This will return an input stream that can be used to read the response body.

See RFC 2616 http://www.faqs.org/rfcs/rfc2616.html for more information about the HTTP protocol.

Proxies and proxy authorization (only HTTP Basic Authorization) is supported. Use setProxy() and setProxyCredentials() to set up a session through a proxy.

Construction

HTTPClientSession()

Creates an unconnected HTTPClientSession.

HTTPClientSession(const StreamSocket& socket)

Creates a HTTPClientSession using the given socket.

The socket must not be connected. The session takes ownership of the socket.

HTTPClientSession(const SocketAddress& address)

Creates a HTTPClientSession using the given address.

HTTPClientSession(
    const std::string& host,
    Poco::UInt16 port = HTTPSession::HTTP_PORT
    )

Creates a HTTPClientSession using the given host and port.

HTTPClientSession(
    const std::string& host,
    Poco::UInt16 port,
    const ProxyConfig& proxyConfig
    )

Creates a HTTPClientSession using the given host, port and proxy configuration.

Methods

void
setHost(const std::string& host)

Sets the host name of the target HTTP server.

The host must not be changed once there is an open connection to the server.

const std::string&
getHost() const

Returns the host name of the target HTTP server.

void
setPort(Poco::UInt16 port)

Sets the port number of the target HTTP server.

The port number must not be changed once there is an open connection to the server.

Poco::UInt16
getPort() const

Returns the port number of the target HTTP server.

void
setProxy(
    const std::string& host,
    Poco::UInt16 port = HTTPSession::HTTP_PORT
    )

Sets the proxy host name and port number.

void
setProxyHost(const std::string& host)

Sets the host name of the proxy server.

void
setProxyPort(Poco::UInt16 port)

Sets the port number of the proxy server.

const std::string&
getProxyHost() const

Returns the proxy host name.

Poco::UInt16
getProxyPort() const

Returns the proxy port number.

void
setProxyCredentials(
    const std::string& username,
    const std::string& password
    )

Sets the username and password for proxy authentication.

Only Basic authentication is supported.

void
setProxyUsername(const std::string& username)

Sets the username for proxy authentication.

Only Basic authentication is supported.

const std::string&
getProxyUsername() const

Returns the username for proxy authentication.

void
setProxyPassword(const std::string& password)

Sets the password for proxy authentication.

Only Basic authentication is supported.

const std::string&
getProxyPassword() const

Returns the password for proxy authentication.

void
setProxyConfig(const ProxyConfig& config)

Sets the proxy configuration.

const ProxyConfig&
getProxyConfig() const

Returns the proxy configuration.

void
setKeepAliveTimeout(const Poco::Timespan& timeout)

Sets the connection timeout for HTTP connections.

const Poco::Timespan&
getKeepAliveTimeout() const

Returns the connection timeout for HTTP connections.

virtual
std::ostream&
sendRequest(HTTPRequest& request)

Sends the header for the given HTTP request to the server.

The HTTPClientSession will set the request’s Host and Keep-Alive headers accordingly.

The returned output stream can be used to write the request body. The stream is valid until receiveResponse() is called or the session is destroyed.

In case a network or server failure happens while writing the request body to the returned stream, the stream state will change to bad or fail. In this case, reset() should be called if the session will be reused and persistent connections are enabled to ensure a new connection will be set up for the next request.

virtual
std::istream&
receiveResponse(HTTPResponse& response)

Receives the header for the response to the previous HTTP request.

The returned input stream can be used to read the response body. The stream is valid until sendRequest() is called or the session is destroyed.

It must be ensured that the response stream is fully consumed before sending a new request and persistent connections are enabled. Otherwise, the unread part of the response body may be treated as part of the next request’s response header, resulting in a Poco::Net::MessageException being thrown.

In case a network or server failure happens while reading the response body from the returned stream, the stream state will change to bad or fail. In this case, reset() should be called if the session will be reused and persistent connections are enabled to ensure a new connection will be set up for the next request.

void
reset()

Resets the session and closes the socket.

The next request will initiate a new connection, even if persistent connections are enabled.

This should be called whenever something went wrong when sending a request (e.g., sendRequest() or receiveResponse() throws an exception, or the request or response stream changes into fail or bad state, but not eof state).

virtual
bool
secure() const

Return true iff the session uses SSL or TLS, or false otherwise.

bool
bypassProxy() const

Returns true if the proxy should be bypassed for the current host.

static
void
setGlobalProxyConfig(const ProxyConfig& config)

Sets the global proxy configuration.

The global proxy configuration is used by all HTTPClientSession instances, unless a different proxy configuration is explicitly set.

Warning: Setting the global proxy configuration is not thread safe. The global proxy configuration should be set at start up, before the first HTTPClientSession instance is created.

static
const ProxyConfig&
getGlobalProxyConfig()

Returns the global proxy configuration.

void
reconnect()

Connects the underlying socket to the HTTP server.

virtual
int
write(
    const char* buffer,
    std::streamsize length
    )

Tries to re-connect if keep-alive is on.

virtual
std::string
proxyRequestPrefix() const

Returns the prefix prepended to the URI for proxy requests (e.g., “http://myhost.com”).

virtual
bool
mustReconnect() const

Checks if we can reuse a persistent connection.

virtual
void
proxyAuthenticate(HTTPRequest& request)

Sets the proxy credentials (Proxy-Authorization header), if proxy username and password have been set.

void
proxyAuthenticateImpl(HTTPRequest& request)

Sets the proxy credentials (Proxy-Authorization header), if proxy username and password have been set.

StreamSocket
proxyConnect()

Sends a CONNECT request to the proxy server and returns a StreamSocket for the resulting connection.

void
proxyTunnel()

Calls proxyConnect() and attaches the resulting StreamSocket to the HTTPClientSession.