class Poco::Net::HTTPSession

Overview

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

#include <HTTPSession.h>

class HTTPSession
{
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:
    // construction

    HTTPSession();
    HTTPSession(const StreamSocket& socket);

    HTTPSession(
        const StreamSocket& socket,
        bool keepAlive
        );

    // 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();
};

// direct descendants

class HTTPClientSession;
class HTTPServerSession;

Detailed Documentation

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.

Construction

HTTPSession()

Creates a HTTP session using an unconnected stream socket.

HTTPSession(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(
    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.

Methods

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.

bool
getKeepAlive() const

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

void
setTimeout(const Poco::Timespan& timeout)

Sets the timeout for the HTTP session.

Poco::Timespan
getTimeout() const

Returns the timeout for the HTTP session.

bool
connected() const

Returns true if the underlying socket is connected.

virtual
void
abort()

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

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.

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

const Poco::Any&
sessionData() const

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

StreamSocket
detachSocket()

Detaches the socket from the session.

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

StreamSocket&
socket()

Returns a reference to the underlying socket.

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.

int
get()

Returns the next byte in the buffer.

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

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.

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.

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

Writes data to the socket.

int
receive(
    char* buffer,
    int length
    )

Reads up to length bytes.

int
buffered() const

Returns the number of bytes in the buffer.

void
refill()

Refills the internal buffer.

virtual
void
connect(const SocketAddress& address)

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

void
attachSocket(const StreamSocket& socket)

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

void
close()

Closes the underlying socket.

void
setException(const Poco::Exception& exc)

Stores a clone of the exception.

void
clearException()

Clears the stored exception.