pion::tcp::connection Class Reference

`#include <connection.hpp>`

Inherits enable_shared_from_this< connection >, and noncopyable.

## Classes

class | ssl_socket_type

## Public Types

enum | lifecycle_type { LIFECYCLE_CLOSE, LIFECYCLE_KEEPALIVE, LIFECYCLE_PIPELINED }
| data type for the connection's lifecycle state
enum | { READ_BUFFER_SIZE = 8192 }
| size of the read buffer
typedef boost::function1< void, boost::shared_ptr< connection > > | connection_handler
| data type for a function that handles TCP connection objects
typedef boost::array< char, READ_BUFFER_SIZE > | read_buffer_type
| data type for an I/O read buffer
typedef boost::asio::ip::tcp::socket | socket_type
| data type for a socket connection
typedef int | ssl_context_type

## Public Member Functions

| connection (boost::asio::io_service &io_service, const bool ssl_flag=false)
| connection (boost::asio::io_service &io_service, ssl_context_type &ssl_context)
bool | is_open (void) const
| returns true if the connection is currently open
void | close (void)
| closes the tcp socket and cancels any pending asynchronous operations
void | cancel (void)
virtual | ~connection ()
| virtual destructor
template<typename AcceptHandler >
void | async_accept (boost::asio::ip::tcp::acceptor &tcp_acceptor, AcceptHandler handler)
boost::system::error_code | accept (boost::asio::ip::tcp::acceptor &tcp_acceptor)
template<typename ConnectHandler >
void | async_connect (const boost::asio::ip::tcp::endpoint &tcp_endpoint, ConnectHandler handler)
template<typename ConnectHandler >
void | async_connect (const boost::asio::ip::address &remote_addr, const unsigned int remote_port, ConnectHandler handler)
boost::system::error_code | connect (boost::asio::ip::tcp::endpoint &tcp_endpoint)
boost::system::error_code | connect (const boost::asio::ip::address &remote_addr, const unsigned int remote_port)
boost::system::error_code | connect (const std::string &remote_server, const unsigned int remote_port)
template<typename SSLHandshakeHandler >
void | async_handshake_client (SSLHandshakeHandler handler)
template<typename SSLHandshakeHandler >
void | async_handshake_server (SSLHandshakeHandler handler)
boost::system::error_code | handshake_client (void)
boost::system::error_code | handshake_server (void)
template<typename ReadHandler >
void | async_read_some (ReadHandler handler)
template<typename ReadBufferType , typename ReadHandler >
void | async_read_some (ReadBufferType read_buffer, ReadHandler handler)
std::size_t | read_some (boost::system::error_code &ec)
template<typename ReadBufferType >
std::size_t | read_some (ReadBufferType read_buffer, boost::system::error_code &ec)
template<typename CompletionCondition , typename ReadHandler >
void | async_read (CompletionCondition completion_condition, ReadHandler handler)
template<typename MutableBufferSequence , typename CompletionCondition , typename ReadHandler >
void | async_read (const MutableBufferSequence &buffers, CompletionCondition completion_condition, ReadHandler handler)
template<typename CompletionCondition >
std::size_t | read (CompletionCondition completion_condition, boost::system::error_code &ec)
template<typename MutableBufferSequence , typename CompletionCondition >
std::size_t | read (const MutableBufferSequence &buffers, CompletionCondition completion_condition, boost::system::error_code &ec)
template<typename ConstBufferSequence , typename write_handler_t >
void | async_write (const ConstBufferSequence &buffers, write_handler_t handler)
template<typename ConstBufferSequence >
std::size_t | write (const ConstBufferSequence &buffers, boost::system::error_code &ec)
void | finish (void)
bool | get_ssl_flag (void) const
| returns true if the connection is encrypted using SSL
void | set_lifecycle (lifecycle_type t)
| sets the lifecycle type for the connection
lifecycle_type | get_lifecycle (void) const
| returns the lifecycle type for the connection
bool | get_keep_alive (void) const
| returns true if the connection should be kept alive
bool | get_pipelined (void) const
| returns true if the HTTP requests are pipelined
read_buffer_type & | get_read_buffer (void)
| returns the buffer used for reading data from the TCP connection
void | save_read_pos (const char *read_ptr, const char *read_end_ptr)
void | load_read_pos (const char *&read_ptr, const char *&read_end_ptr) const
boost::asio::ip::tcp::endpoint | get_remote_endpoint (void) const
| returns an ASIO endpoint for the client connection
boost::asio::ip::address | get_remote_ip (void) const
| returns the client's IP address
unsigned short | get_remote_port (void) const
| returns the client's port number
boost::asio::io_service & | get_io_service (void)
| returns reference to the io_service used for async operations
socket_type & | get_socket (void)
| returns non-const reference to underlying TCP socket object
ssl_socket_type & | get_ssl_socket (void)
| returns non-const reference to underlying SSL socket object
const socket_type & | get_socket (void) const
| returns const reference to underlying TCP socket object
const ssl_socket_type & | get_ssl_socket (void) const
| returns const reference to underlying SSL socket object

## Static Public Member Functions

static boost::shared_ptr< connection > | create (boost::asio::io_service &io_service, ssl_context_type &ssl_context, const bool ssl_flag, connection_handler finished_handler)

## Protected Member Functions

| connection (boost::asio::io_service &io_service, ssl_context_type &ssl_context, const bool ssl_flag, connection_handler finished_handler)

## Detailed Description

connection: represents a single tcp connection

Definition at line 40 of file connection.hpp.

## Constructor & Destructor Documentation

## connection() [1/3]

pion::tcp::connection::connection | ( | boost::asio::io_service & | io_service,
|  | const bool | ssl_flag = `false`
| ) |  |

inline explicit

creates a new connection object

Parameters

  io_service | asio service associated with the connection
  ssl_flag | if true then the connection will be encrypted using SSL

Definition at line 109 of file connection.hpp.

References save_read_pos().

Referenced by create().

## connection() [2/3]

pion::tcp::connection::connection | ( | boost::asio::io_service & | io_service,
|  | ssl_context_type & | ssl_context
| ) |  |

inline

creates a new connection object for SSL

Parameters

  io_service | asio service associated with the connection
  ssl_context | asio ssl context associated with the connection

Definition at line 131 of file connection.hpp.

References save_read_pos().

## connection() [3/3]

pion::tcp::connection::connection | ( | boost::asio::io_service & | io_service,
|  | ssl_context_type & | ssl_context,
|  | const bool | ssl_flag,
|  | connection_handler | finished_handler
| ) |  |

inline protected

protected constructor restricts creation of objects (use create())

Parameters

  io_service | asio service associated with the connection
  ssl_context | asio ssl context associated with the connection
  ssl_flag | if true then the connection will be encrypted using SSL
  finished_handler | function called when a server has finished handling the connection

Definition at line 689 of file connection.hpp.

References save_read_pos().

## Member Function Documentation

## accept()

boost::system::error_code pion::tcp::connection::accept | ( | boost::asio::ip::tcp::acceptor & | tcp_acceptor | ) |

inline

accepts a new tcp connection (blocks until established)

Parameters

  tcp_acceptor | object used to accept new connections

Returns
  boost::system::error_code contains error code if the connection fails

See also
  boost::asio::basic_socket_acceptor::accept()

Definition at line 209 of file connection.hpp.

## async_accept()

template<typename AcceptHandler >

void pion::tcp::connection::async_accept | ( | boost::asio::ip::tcp::acceptor & | tcp_acceptor,
|  | AcceptHandler | handler
| ) |  |

inline

asynchronously accepts a new tcp connection

Parameters

  tcp_acceptor | object used to accept new connections
  handler | called after a new connection has been accepted

See also
  boost::asio::basic_socket_acceptor::async_accept()

Definition at line 195 of file connection.hpp.

## async_connect() [1/2]

template<typename ConnectHandler >

void pion::tcp::connection::async_connect | ( | const boost::asio::ip::tcp::endpoint & | tcp_endpoint,
|  | ConnectHandler | handler
| ) |  |

inline

asynchronously connects to a remote endpoint

Parameters

  tcp_endpoint | remote endpoint to connect to
  handler | called after a new connection has been established

See also
  boost::asio::basic_socket_acceptor::async_connect()

Definition at line 225 of file connection.hpp.

Referenced by async_connect().

## async_connect() [2/2]

template<typename ConnectHandler >

void pion::tcp::connection::async_connect | ( | const boost::asio::ip::address & | remote_addr,
|  | const unsigned int | remote_port,
|  | ConnectHandler | handler
| ) |  |

inline

asynchronously connects to a (IPv4) remote endpoint

Parameters

  remote_addr | remote IP address (v4) to connect to
  remote_port | remote port number to connect to
  handler | called after a new connection has been established

See also
  boost::asio::basic_socket_acceptor::async_connect()

Definition at line 241 of file connection.hpp.

References async_connect().

## async_handshake_client()

template<typename SSLHandshakeHandler >

void pion::tcp::connection::async_handshake_client | ( | SSLHandshakeHandler | handler | ) |

inline

asynchronously performs client-side SSL handshake for a new connection

Parameters

  handler | called after the ssl handshake has completed

See also
  boost::asio::ssl::stream::async_handshake()

Definition at line 324 of file connection.hpp.

## async_handshake_server()

template<typename SSLHandshakeHandler >

void pion::tcp::connection::async_handshake_server | ( | SSLHandshakeHandler | handler | ) |

inline

asynchronously performs server-side SSL handshake for a new connection

Parameters

  handler | called after the ssl handshake has completed

See also
  boost::asio::ssl::stream::async_handshake()

Definition at line 339 of file connection.hpp.

## async_read() [1/2]

template<typename CompletionCondition , typename ReadHandler >

void pion::tcp::connection::async_read | ( | CompletionCondition | completion_condition,
|  | ReadHandler | handler
| ) |  |

inline

asynchronously reads data into the connection's read buffer until completion_condition is met

Parameters

  completion_condition | determines if the read operation is complete
  handler | called after the read operation has completed

See also
  boost::asio::async_read()

Definition at line 464 of file connection.hpp.

References get_ssl_flag().

## async_read() [2/2]

template<typename MutableBufferSequence , typename CompletionCondition , typename ReadHandler >

void pion::tcp::connection::async_read | ( | const MutableBufferSequence & | buffers,
|  | CompletionCondition | completion_condition,
|  | ReadHandler | handler
| ) |  |

inline

asynchronously reads data from the connection until completion_condition is met

Parameters

  buffers | one or more buffers into which the data will be read
  completion_condition | determines if the read operation is complete
  handler | called after the read operation has completed

See also
  boost::asio::async_read()

Definition at line 488 of file connection.hpp.

References get_ssl_flag().

## async_read_some() [1/2]

template<typename ReadHandler >

void pion::tcp::connection::async_read_some | ( | ReadHandler | handler | ) |

inline

asynchronously reads some data into the connection's read buffer

Parameters

  handler | called after the read operation has completed

See also
  boost::asio::basic_stream_socket::async_read_some()

Definition at line 386 of file connection.hpp.

References get_ssl_flag().

## async_read_some() [2/2]

template<typename ReadBufferType , typename ReadHandler >

void pion::tcp::connection::async_read_some | ( | ReadBufferType | read_buffer,
|  | ReadHandler | handler
| ) |  |

inline

asynchronously reads some data into the connection's read buffer

Parameters

  read_buffer | the buffer to read data into
  handler | called after the read operation has completed

See also
  boost::asio::basic_stream_socket::async_read_some()

Definition at line 406 of file connection.hpp.

References get_ssl_flag().

## async_write()

template<typename ConstBufferSequence , typename write_handler_t >

void pion::tcp::connection::async_write | ( | const ConstBufferSequence & | buffers,
|  | write_handler_t | handler
| ) |  |

inline

asynchronously writes data to the connection

Parameters

  buffers | one or more buffers containing the data to be written
  handler | called after the data has been written

See also
  boost::asio::async_write()

Definition at line 561 of file connection.hpp.

References get_ssl_flag().

## cancel()

void pion::tcp::connection::cancel | ( | void |  | ) |

inline

cancels any asynchronous operations pending on the socket. there is no good way to do this on windows until vista or later (0x0600) see http://www.boost.org/doc/libs/1_53_0/doc/html/boost_asio/reference/basic_stream_socket/cancel/overload2.html note that the asio docs are misleading because close() is not thread-safe, and the suggested #define statements cause WAY too much trouble and heartache

Definition at line 176 of file connection.hpp.

## connect() [1/3]

boost::system::error_code pion::tcp::connection::connect | ( | boost::asio::ip::tcp::endpoint & | tcp_endpoint | ) |

inline

connects to a remote endpoint (blocks until established)

Parameters

  tcp_endpoint | remote endpoint to connect to

Returns
  boost::system::error_code contains error code if the connection fails

See also
  boost::asio::basic_socket_acceptor::connect()

Definition at line 257 of file connection.hpp.

Referenced by connect().

## connect() [2/3]

boost::system::error_code pion::tcp::connection::connect | ( | const boost::asio::ip::address & | remote_addr,
|  | const unsigned int | remote_port
| ) |  |

inline

connects to a (IPv4) remote endpoint (blocks until established)

Parameters

  remote_addr | remote IP address (v4) to connect to
  remote_port | remote port number to connect to

Returns
  boost::system::error_code contains error code if the connection fails

See also
  boost::asio::basic_socket_acceptor::connect()

Definition at line 273 of file connection.hpp.

References connect().

## connect() [3/3]

boost::system::error_code pion::tcp::connection::connect | ( | const std::string & | remote_server,
|  | const unsigned int | remote_port
| ) |  |

inline

connects to a remote endpoint with hostname lookup

Parameters

  remote_server | hostname of the remote server to connect to
  remote_port | remote port number to connect to

Returns
  boost::system::error_code contains error code if the connection fails

See also
  boost::asio::basic_socket_acceptor::connect()

Definition at line 289 of file connection.hpp.

References close(), and connect().

## create()

static boost::shared_ptr<connection> pion::tcp::connection::create | ( | boost::asio::io_service & | io_service,
|  | ssl_context_type & | ssl_context,
|  | const bool | ssl_flag,
|  | connection_handler | finished_handler
| ) |  |

inline static

creates new shared connection objects

Parameters

  io_service | asio service associated with the connection
  ssl_context | asio ssl context associated with the connection
  ssl_flag | if true then the connection will be encrypted using SSL
  finished_handler | function called when a server has finished handling the connection

Definition at line 94 of file connection.hpp.

References connection().

Referenced by pion::tcp::server::set_ssl_key_file().

## finish()

void pion::tcp::connection::finish | ( | void |  | ) |

inline

This function should be called when a server has finished handling the connection

Definition at line 596 of file connection.hpp.

Referenced by pion::http::server::handle_bad_request(), HelloServer::handle_connection(), pion::http::server::handle_forbidden_request(), pion::http::server::handle_method_not_allowed(), pion::http::server::handle_not_found_request(), pion::http::cookie_auth::handle_ok(), pion::http::cookie_auth::handle_redirection(), pion::http::server::handle_server_error(), pion::http::basic_auth::handle_unauthorized(), pion::http::cookie_auth::handle_unauthorized(), pion::plugins::EchoService::operator()(), pion::plugins::CookieService::operator()(), pion::plugins::HelloService::operator()(), pion::plugins::AllowNothingService::operator()(), pion::plugins::LogService::operator()(), and pion::plugins::FileService::operator()().

## handshake_client()

boost::system::error_code pion::tcp::connection::handshake_client | ( | void |  | ) |

inline

performs client-side SSL handshake for a new connection (blocks until finished)

Returns
  boost::system::error_code contains error code if the connection fails

See also
  boost::asio::ssl::stream::handshake()

Definition at line 353 of file connection.hpp.

## handshake_server()

boost::system::error_code pion::tcp::connection::handshake_server | ( | void |  | ) |

inline

performs server-side SSL handshake for a new connection (blocks until finished)

Returns
  boost::system::error_code contains error code if the connection fails

See also
  boost::asio::ssl::stream::handshake()

Definition at line 369 of file connection.hpp.

## load_read_pos()

void pion::tcp::connection::load_read_pos | ( | const char *& | read_ptr,
|  | const char *& | read_end_ptr
| ) |  | const

inline

loads a read position bookmark

Parameters

  read_ptr | points to the next character to be consumed in the read_buffer
  read_end_ptr | points to the end of the read_buffer (last byte + 1)

Definition at line 633 of file connection.hpp.

Referenced by pion::http::message::receive().

## read() [1/2]

template<typename CompletionCondition >

std::size_t pion::tcp::connection::read | ( | CompletionCondition | completion_condition,
|  | boost::system::error_code & | ec
| ) |  |

inline

reads data into the connection's read buffer until completion_condition is met (blocks until finished)

Parameters

  completion_condition | determines if the read operation is complete
  ec | contains error code if the read fails

Returns
  std::size_t number of bytes read

See also
  boost::asio::read()

Definition at line 513 of file connection.hpp.

References get_ssl_flag().

## read() [2/2]

template<typename MutableBufferSequence , typename CompletionCondition >

std::size_t pion::tcp::connection::read | ( | const MutableBufferSequence & | buffers,
|  | CompletionCondition | completion_condition,
|  | boost::system::error_code & | ec
| ) |  |

inline

reads data from the connection until completion_condition is met (blocks until finished)

Parameters

  buffers | one or more buffers into which the data will be read
  completion_condition | determines if the read operation is complete
  ec | contains error code if the read fails

Returns
  std::size_t number of bytes read

See also
  boost::asio::read()

Definition at line 538 of file connection.hpp.

References get_ssl_flag().

## read_some() [1/2]

std::size_t pion::tcp::connection::read_some | ( | boost::system::error_code & | ec | ) |

inline

reads some data into the connection's read buffer (blocks until finished)

Parameters

  ec | contains error code if the read fails

Returns
  std::size_t number of bytes read

See also
  boost::asio::basic_stream_socket::read_some()

Definition at line 424 of file connection.hpp.

References get_ssl_flag().

Referenced by pion::http::message::receive().

## read_some() [2/2]

template<typename ReadBufferType >

std::size_t pion::tcp::connection::read_some | ( | ReadBufferType | read_buffer,
|  | boost::system::error_code & | ec
| ) |  |

inline

reads some data into the connection's read buffer (blocks until finished)

Parameters

  read_buffer | the buffer to read data into
  ec | contains error code if the read fails

Returns
  std::size_t number of bytes read

See also
  boost::asio::basic_stream_socket::read_some()

Definition at line 443 of file connection.hpp.

References get_ssl_flag().

## save_read_pos()

void pion::tcp::connection::save_read_pos | ( | const char * | read_ptr,
|  | const char * | read_end_ptr
| ) |  |

inline

saves a read position bookmark

Parameters

  read_ptr | points to the next character to be consumed in the read_buffer
  read_end_ptr | points to the end of the read_buffer (last byte + 1)

Definition at line 622 of file connection.hpp.

Referenced by connection(), and pion::http::message::receive().

## write()

template<typename ConstBufferSequence >

std::size_t pion::tcp::connection::write | ( | const ConstBufferSequence & | buffers,
|  | boost::system::error_code & | ec
| ) |  |

inline

writes data to the connection (blocks until finished)

Parameters

  buffers | one or more buffers containing the data to be written
  ec | contains error code if the write fails

Returns
  std::size_t number of bytes written

See also
  boost::asio::write()

Definition at line 580 of file connection.hpp.

References get_ssl_flag().

Referenced by pion::http::message::send().

The documentation for this class was generated from the following file:

- include/pion/tcp/connection.hpp