Poco::Net

class HTTPClientSession

File Information

Library: Net
Package: HTTPClient
Header: Poco/Net/HTTPClientSession.h

Description

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.

Inheritance

Direct Base Classes: HTTPSession

All Base Classes: HTTPSession

Member Summary

Member Functions: bypassProxy, flushRequest, getGlobalProxyConfig, getHost, getKeepAliveTimeout, getPort, getProxyConfig, getProxyHost, getProxyPassword, getProxyPort, getProxyUsername, getSourceAddress, getSourceAddress4, getSourceAddress6, mustReconnect, peekResponse, proxyAuthenticate, proxyAuthenticateDigest, proxyAuthenticateImpl, proxyAuthenticateNTLM, proxyConnect, proxyRequestPrefix, proxyTunnel, receiveResponse, reconnect, reset, secure, sendChallengeRequest, sendRequest, sendRequestImpl, setGlobalProxyConfig, setHost, setKeepAliveTimeout, setPort, setProxy, setProxyConfig, setProxyCredentials, setProxyHost, setProxyPassword, setProxyPort, setProxyUsername, setSourceAddress, write

Inherited Functions: abort, attachSessionData, attachSocket, buffered, clearException, close, connect, connected, detachSocket, drainBuffer, get, getConnectTimeout, getKeepAlive, getReceiveTimeout, getSendTimeout, getTimeout, networkException, peek, read, receive, refill, requestTrailer, responseTrailer, sessionData, setConnectTimeout, setException, setKeepAlive, setReceiveTimeout, setSendTimeout, setTimeout, socket, write

Nested Classes

struct ProxyConfig

HTTP proxy server configuration. 

Enumerations

Anonymous protected

DEFAULT_KEEP_ALIVE_TIMEOUT = 8

ProxyAuthentication

PROXY_AUTH_NONE

No proxy authentication

PROXY_AUTH_HTTP_BASIC

HTTP Basic proxy authentication (default, if username and password are supplied)

PROXY_AUTH_HTTP_DIGEST

HTTP Digest proxy authentication

PROXY_AUTH_NTLM

NTLMv2 proxy authentication

Constructors

HTTPClientSession

HTTPClientSession();

Creates an unconnected HTTPClientSession.

HTTPClientSession

explicit 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

explicit HTTPClientSession(
    const SocketAddress & address
);

Creates a HTTPClientSession using the given address.

HTTPClientSession

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

Creates a HTTPClientSession using the given host and port.

HTTPClientSession

HTTPClientSession(
    const StreamSocket & socket,
    const ProxyConfig & proxyConfig
);

Creates a HTTPClientSession using the given socket and proxy configuration.

HTTPClientSession

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

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

Destructor

~HTTPClientSession virtual

virtual ~HTTPClientSession();

Destroys the HTTPClientSession and closes the underlying socket.

Member Functions

bypassProxy

bool bypassProxy() const;

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

flushRequest

void flushRequest();

Flushes the request stream.

Normally this method does not need to be called. It can be used to ensure the request has been fully sent if receiveResponse() is not called, e.g., because the underlying socket will be detached.

getGlobalProxyConfig static inline

static const ProxyConfig & getGlobalProxyConfig();

Returns the global proxy configuration.

getHost inline

const std::string & getHost() const;

Returns the host name of the target HTTP server.

getKeepAliveTimeout inline

const Poco::Timespan & getKeepAliveTimeout() const;

Returns the connection timeout for HTTP connections.

getPort inline

Poco::UInt16 getPort() const;

Returns the port number of the target HTTP server.

getProxyConfig inline

const ProxyConfig & getProxyConfig() const;

Returns the proxy configuration.

getProxyHost inline

const std::string & getProxyHost() const;

Returns the proxy host name.

getProxyPassword inline

const std::string & getProxyPassword() const;

Returns the password for proxy authentication.

getProxyPort inline

Poco::UInt16 getProxyPort() const;

Returns the proxy port number.

getProxyUsername inline

const std::string & getProxyUsername() const;

Returns the username for proxy authentication.

getSourceAddress

const SocketAddress & getSourceAddress();

Returns the last source address set with setSourceAddress

getSourceAddress4

const SocketAddress & getSourceAddress4();

Returns the last IPv4 source address set with setSourceAddress

getSourceAddress6

const SocketAddress & getSourceAddress6();

Returns the last IPV6 source address set with setSourceAddress

peekResponse virtual

virtual bool peekResponse(
    HTTPResponse & response
);

If the request contains a "Expect: 100-continue" header, (see HTTPRequest::setExpectContinue()) this method can be used to check whether the server has sent a 100 Continue response before continuing with the request, i.e. sending the request body, after calling sendRequest().

Returns true if the server has responded with 100 Continue, otherwise false. The HTTPResponse object contains the response sent by the server.

In any case, receiveResponse() must be called afterwards as well in order to complete the request. The same HTTPResponse object passed to peekResponse() must also be passed to receiveResponse().

This method should only be called if the request contains a "Expect: 100-continue" header.

receiveResponse virtual

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.

reset

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).

secure virtual

virtual bool secure() const;

Return true if and only if the session uses SSL or TLS, or false otherwise.

sendRequest virtual

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.

setGlobalProxyConfig static

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.

setHost

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.

setKeepAliveTimeout

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

Sets the connection timeout for HTTP connections.

setPort

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.

setProxy

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

Sets the proxy host name and port number.

setProxyConfig

void setProxyConfig(
    const ProxyConfig & config
);

Sets the proxy configuration.

setProxyCredentials

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

Sets the username and password for proxy authentication. Only Basic authentication is supported.

setProxyHost

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

Sets the host name of the proxy server.

setProxyPassword

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

Sets the password for proxy authentication. Only Basic authentication is supported.

setProxyPort

void setProxyPort(
    Poco::UInt16 port
);

Sets the port number of the proxy server.

setProxyUsername

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

Sets the username for proxy authentication. Only Basic authentication is supported.

setSourceAddress

void setSourceAddress(
    const SocketAddress & address
);

Sets the source IP address and source port for the HTTPClientSession socket.

Function can be called repeatedly to set one source address value for IPv4 and one for IPv6, in the case where it is not known ahead of time which type of address family the target host is part of.

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

Note: Both the source IP address and source port can be set using this function, but the typical client use is to set the source IP address only and the source port portion would normally be passed as 0 meaning that any port value can be used on the source side of the socket.

mustReconnect protected virtual

virtual bool mustReconnect() const;

Checks if we can reuse a persistent connection.

proxyAuthenticate protected virtual

virtual void proxyAuthenticate(
    HTTPRequest & request
);

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

proxyAuthenticateDigest protected

void proxyAuthenticateDigest(
    HTTPRequest & request
);

Initiates a HTTP Digest authentication handshake with the proxy.

proxyAuthenticateImpl protected

void proxyAuthenticateImpl(
    HTTPRequest & request,
    const ProxyConfig & proxyConfig
);

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

proxyAuthenticateNTLM protected

void proxyAuthenticateNTLM(
    HTTPRequest & request
);

Initiates a HTTP NTLM authentication handshake with the proxy.

proxyConnect protected

StreamSocket proxyConnect();

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

proxyRequestPrefix protected virtual

virtual std::string proxyRequestPrefix() const;

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

proxyTunnel protected

void proxyTunnel();

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

reconnect protected

void reconnect();

Connects the underlying socket to the HTTP server.

sendChallengeRequest protected

void sendChallengeRequest(
    const HTTPRequest & request,
    HTTPResponse & response
);

Sends a probe request for Digest and NTLM authentication to obtain the server challenge.

sendRequestImpl protected

std::ostream & sendRequestImpl(
    const HTTPRequest & request
);

Sends the given HTTPRequest over an existing connection.

write protected virtual

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

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

See also: Poco::Net::HTTPSession::write()