Library: Net
Package: HTTPClient
Header: Poco/Net/HTTPClientSession.h
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 sendRequst() 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.
Direct Base Classes: HTTPSession
All Base Classes: HTTPSession
Known Derived Classes: HTTPSClientSession
Member Functions: deleteRequestStream, deleteResponseStream, getExpectResponseBody, getHost, getKeepAliveTimeout, getPort, getProxyHost, getProxyPassword, getProxyPort, getProxyUsername, getRequestStream, getResponseStream, mustReconnect, proxyAuthenticate, proxyAuthenticateImpl, proxyRequestPrefix, receiveResponse, reconnect, reset, secure, sendRequest, setExpectResponseBody, setHost, setKeepAliveTimeout, setPort, setProxy, setProxyCredentials, setProxyHost, setProxyPassword, setProxyPort, setProxyUsername, setReconnect, setRequestStream, setResponseStream, write
Inherited Functions: abort, attachSessionData, attachSocket, buffered, close, connect, connected, detachSocket, get, getKeepAlive, getTimeout, networkException, peek, read, receive, refill, sessionData, setException, setKeepAlive, setTimeout, socket, write
DEFAULT_KEEP_ALIVE_TIMEOUT = 8
Creates an unconnected 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.
explicit 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.
virtual ~HTTPClientSession();
Destroys the HTTPClientSession and closes the underlying socket.
const std::string & getHost() const;
Returns the host name of the target HTTP server.
const Poco::Timespan & getKeepAliveTimeout() const;
Returns the connection timeout for HTTP connections.
Poco::UInt16 getPort() const;
Returns the port number of the target HTTP server.
const std::string & getProxyHost() const;
Returns the proxy host name.
const std::string & getProxyPassword() const;
Returns the password for proxy authentication.
Poco::UInt16 getProxyPort() const;
Returns the proxy port number.
const std::string & getProxyUsername() const;
Returns the username for proxy authentication.
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 if and only if the session uses SSL or TLS, or false otherwise.
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.
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.
void setKeepAliveTimeout(
const Poco::Timespan & timeout
);
Sets the connection timeout for HTTP connections.
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.
void setProxy(
const std::string & host,
Poco::UInt16 port = HTTPSession::HTTP_PORT
);
Sets the proxy host name and 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 setProxyHost(
const std::string & host
);
Sets the host name of the proxy server.
void setProxyPassword(
const std::string & password
);
Sets the password for proxy authentication. Only Basic authentication is supported.
void setProxyPort(
Poco::UInt16 port
);
Sets the port number of the proxy server.
void setProxyUsername(
const std::string & username
);
Sets the username for proxy authentication. Only Basic authentication is supported.
void deleteRequestStream();
Deletes the request stream and sets it to 0.
void deleteResponseStream();
Deletes the response stream and sets it to 0.
bool getExpectResponseBody() const;
Returns _expectResponseBody.
std::ostream * getRequestStream() const;
Returns the currently set request stream. Can return 0.
std::istream * getResponseStream() const;
Returns the currently set response stream. Can return 0.
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.
virtual std::string proxyRequestPrefix() const;
Returns the prefix prepended to the URI for proxy requests (e.g., "http://myhost.com").
void reconnect();
Connects the underlying socket to the HTTP server.
void setExpectResponseBody(
bool expect
);
Sets _expectResponseBody.
void setReconnect(
bool recon
);
Sets _reconnect.
void setRequestStream(
std::ostream * pRequestStream
);
Sets the request stream if and only if _pRequestStream is 0.
void setResponseStream(
std::istream * pRespStream
);
Sets the response stream if and only if _pResponseStream is 0.
int write(
const char * buffer,
std::streamsize length
);
Tries to re-connect if keep-alive is on.
See also: Poco::Net::HTTPSession::write()