class HTTPSession

Library: Net
Package: HTTP
Header: Poco/Net/HTTPSession.h


HTTPSession implements basic HTTP session management for both HTTP clients and HTTP servers.

HTTPSession implements buffering for HTTP connections, as well as specific support for the various HTTP stream classes.

This class can not be instantiated. HTTPClientSession or HTTPServerSession must be used instead.


Known Derived Classes: HTTPClientSession, HTTPServerSession, HTTPSClientSession

Member Summary

Member Functions: abort, attachSessionData, attachSocket, buffered, clearException, close, connect, connected, detachSocket, drainBuffer, get, getKeepAlive, getTimeout, networkException, peek, read, receive, refill, sessionData, setException, setKeepAlive, setTimeout, socket, write





HTTPSession protected


Creates a HTTP session using an unconnected stream socket.

HTTPSession protected

    const StreamSocket & socket

Creates a HTTP session using the given socket. The session takes ownership of the socket and closes it when it's no longer used.

HTTPSession protected

    const StreamSocket & socket,
    bool keepAlive

Creates a HTTP session using the given socket. The session takes ownership of the socket and closes it when it's no longer used.


~HTTPSession protected virtual

virtual ~HTTPSession();

Destroys the HTTPSession and closes the underlying socket.

Member Functions

abort virtual

virtual void abort();

Aborts a session in progress by shutting down and closing the underlying socket.


void attachSessionData(
    const Poco::Any & data

Allows to attach an application-specific data item to the session.

On the server side, this can be used to manage data that must be maintained over the entire lifetime of a persistent connection (that is, multiple requests sent over the same connection).


bool connected() const;

Returns true if the underlying socket is connected.


StreamSocket detachSocket();

Detaches the socket from the session.

The socket is returned, and a new, uninitialized socket is attached to the session.


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

Copies all bytes remaining in the internal buffer to the given Poco::Buffer, resizing it as necessary.

This is usually used together with detachSocket() to obtain any data already read from the socket, but not yet processed.

getKeepAlive inline

bool getKeepAlive() const;

Returns the value of the keep-alive flag for this session.

getTimeout inline

Poco::Timespan getTimeout() const;

Returns the timeout for the HTTP session.

networkException inline

const Poco::Exception * networkException() const;

If sending or receiving data over the underlying socket connection resulted in an exception, a pointer to this exception is returned.

Otherwise, NULL is returned.

sessionData inline

const Poco::Any & sessionData() const;

Returns the data attached with attachSessionData(), or an empty Poco::Any if no user data has been attached.


void setKeepAlive(
    bool keepAlive

Sets the keep-alive flag for this session.

If the keep-alive flag is enabled, persistent HTTP/1.1 connections are supported.


void setTimeout(
    const Poco::Timespan & timeout

Sets the timeout for the HTTP session.


void setTimeout(
    const Poco::Timespan & connectionTimeout,
    const Poco::Timespan & sendTimeout,
    const Poco::Timespan & receiveTimeout

Sets different timeouts for the HTTP session.

socket inline

StreamSocket & socket();

Returns a reference to the underlying socket.

attachSocket protected

void attachSocket(
    const StreamSocket & socket

Attaches a socket to the session, replacing the previously attached socket.

buffered protected inline

int buffered() const;

Returns the number of bytes in the buffer.

clearException protected

void clearException();

Clears the stored exception.

close protected

void close();

Closes the underlying socket.

connect protected virtual

virtual void connect(
    const SocketAddress & address

Connects the underlying socket to the given address and sets the socket's receive timeout.

get protected

int get();

Returns the next byte in the buffer. Reads more data from the socket if there are no bytes left in the buffer.

peek protected

int peek();

Peeks at the next character in the buffer. Reads more data from the socket if there are no bytes left in the buffer.

read protected virtual

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

Reads up to length bytes.

If there is data in the buffer, this data is returned. Otherwise, data is read from the socket to avoid unnecessary buffering.

receive protected

int receive(
    char * buffer,
    int length

Reads up to length bytes.

refill protected

void refill();

Refills the internal buffer.

setException protected

void setException(
    const Poco::Exception & exc

Stores a clone of the exception.

write protected virtual

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

Writes data to the socket.