# Poco::Net

# class HTTPSession

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

## Description

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.

## Inheritance

Known Derived Classes: HTTPClientSession, HTTPReactorServerSession, HTTPServerSession, HTTPSClientSession

## Member Summary

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

## Enumerations

### Anonymous

HTTP_PORT = 80

## Constructors

### HTTPSession

HTTPSession();

Creates a HTTP session using an unconnected stream socket.

### HTTPSession

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

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.

## Destructor

### ~HTTPSession

virtual ~HTTPSession();

Destroys the HTTPSession and closes the underlying socket.

## Member Functions

### abort

virtual void abort();

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

### attachSessionData

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

### clientAddress

virtual SocketAddress clientAddress() = 0;

### connected

bool connected() const;

Returns true if the underlying socket is connected.

### detachSocket

StreamSocket detachSocket();

Detaches the socket from the session.

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

### drainBuffer

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.

### getConnectTimeout

Poco::Timespan getConnectTimeout() const;

Gets the connect timeout.

### getKeepAlive

bool getKeepAlive() const;

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

### getReceiveTimeout

Poco::Timespan getReceiveTimeout() const;

Gets the receive timeout.

### getSendTimeout

Poco::Timespan getSendTimeout() const;

Gets the send timeout.

### getTimeout

Poco::Timespan getTimeout() const;

Returns the timeout for the HTTP session.

### networkException

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.

### requestTrailer

const MessageHeader & requestTrailer() const;

Returns the trailer for a request sent using chunked transfer encoding. This method must be called after the entire content of the message has been read.

### requestTrailer

MessageHeader & requestTrailer();

Returns the trailer for a request sent using chunked transfer encoding. The trailer fields to be sent must be set before the request body has been fully written.

### responseTrailer

const MessageHeader & responseTrailer() const;

Returns the trailer for a response sent using chunked transfer encoding. This method must be called after the entire content of the message has been read.

### responseTrailer

MessageHeader & responseTrailer();

Returns the trailer for a response sent using chunked transfer encoding. The trailer fields to be sent must be set before the response body has been fully written.

### serverAddress

virtual SocketAddress serverAddress() = 0;

### sessionData

const Poco::Any & sessionData() const;

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

### setConnectTimeout

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

Sets the connect timeout.

### setKeepAlive

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.

### setReceiveTimeout

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

Sets the receive timeout.

### setSendTimeout

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

Sets the send timeout.

### setTimeout

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

Sets the timeout for the HTTP session.

### setTimeout

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

Sets different timeouts for the HTTP session.

### socket

StreamSocket & socket();

Returns a reference to the underlying socket.

### attachSocket

void attachSocket(
const StreamSocket & socket
);

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

### buffered

int buffered() const;

Returns the number of bytes in the buffer.

### clearException

void clearException();

Clears the stored exception.

### close

void close();

Closes the underlying socket.

### connect

virtual void connect(
const SocketAddress & address
);

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

### connect

void connect(
const SocketAddress & targetAddress,
const SocketAddress & sourceAddress
);

Binds the underlying socket to the source address and connects to the targetAddress.

### get

virtual 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

virtual 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

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

int receive(
char * buffer,
int length
);

Reads up to length bytes.

### refill

void refill();

Refills the internal buffer.

### setException

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

Stores a clone of the exception.

### write

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

Writes data to the socket.