Boost C++ Libraries Home Libraries People FAQ More

Home | Reference | Tutorial | Examples | Design
Reference Index | Class Hierarchy | Class Index | Member Index

boost::asio::ssl::stream< Stream, Service > Class Template Reference

Inherits boost::asio::ssl::stream_base.

Inheritance diagram for boost::asio::ssl::stream< Stream, Service >:

Inheritance graph
List of all members.

Detailed Description

template<typename Stream, typename Service = stream_service>
class boost::asio::ssl::stream< Stream, Service >

Provides stream-oriented functionality using SSL.

The stream class template provides asynchronous and blocking stream-oriented functionality using SSL.

Thread Safety:
Distinct objects: Safe.
Shared objects: Unsafe.
Example:
To use the SSL stream template with a stream_socket, you would write:
Concepts:
Async_Object, Async_Read_Stream, Async_Write_Stream, Error_Source, Stream, Sync_Read_Stream, Sync_Write_Stream.


Public Types

typedef boost::remove_reference<
Stream >::type 
next_layer_type
 The type of the next layer.
typedef next_layer_type::lowest_layer_type lowest_layer_type
 The type of the lowest layer.
typedef next_layer_type::error_type error_type
 The type used for reporting errors.
typedef Service service_type
 The type of the service that will be used to provide stream operations.
typedef service_type::impl_type impl_type
 The native implementation type of the stream.
 client
 Perform handshaking as a client.
 server
 Perform handshaking as a server.
enum  handshake_type {
  client,
  server
}
 Different handshake types. More...

Public Member Functions

template<typename Arg, typename Context_Service>
 stream (Arg &arg, basic_context< Context_Service > &context)
 Construct a stream.
 ~stream ()
 Destructor.
boost::asio::io_serviceio_service ()
 Get the io_service associated with the object.
next_layer_typenext_layer ()
 Get a reference to the next layer.
lowest_layer_typelowest_layer ()
 Get a reference to the lowest layer.
impl_type impl ()
 Get the underlying implementation in the native type.
void handshake (handshake_type type)
 Perform SSL handshaking.
template<typename Error_Handler>
void handshake (handshake_type type, Error_Handler error_handler)
 Perform SSL handshaking.
template<typename Handler>
void async_handshake (handshake_type type, Handler handler)
 Start an asynchronous SSL handshake.
void shutdown ()
 Shut down SSL on the stream.
template<typename Error_Handler>
void shutdown (Error_Handler error_handler)
 Shut down SSL on the stream.
template<typename Handler>
void async_shutdown (Handler handler)
 Asynchronously shut down SSL on the stream.
template<typename Const_Buffers>
std::size_t write_some (const Const_Buffers &buffers)
 Write some data to the stream.
template<typename Const_Buffers, typename Error_Handler>
std::size_t write_some (const Const_Buffers &buffers, Error_Handler error_handler)
 Write some data to the stream.
template<typename Const_Buffers, typename Handler>
void async_write_some (const Const_Buffers &buffers, Handler handler)
 Start an asynchronous write.
template<typename Mutable_Buffers>
std::size_t read_some (const Mutable_Buffers &buffers)
 Read some data from the stream.
template<typename Mutable_Buffers, typename Error_Handler>
std::size_t read_some (const Mutable_Buffers &buffers, Error_Handler error_handler)
 Read some data from the stream.
template<typename Mutable_Buffers, typename Handler>
void async_read_some (const Mutable_Buffers &buffers, Handler handler)
 Start an asynchronous read.
template<typename Mutable_Buffers>
std::size_t peek (const Mutable_Buffers &buffers)
 Peek at the incoming data on the stream.
template<typename Mutable_Buffers, typename Error_Handler>
std::size_t peek (const Mutable_Buffers &buffers, Error_Handler error_handler)
 Peek at the incoming data on the stream.
std::size_t in_avail ()
 Determine the amount of data that may be read without blocking.
template<typename Error_Handler>
std::size_t in_avail (Error_Handler error_handler)
 Determine the amount of data that may be read without blocking.

Private Attributes

Stream next_layer_
 The next layer.
service_typeservice_
 The backend service implementation.
impl_type impl_
 The underlying native implementation.


Member Typedef Documentation

template<typename Stream, typename Service = stream_service>
typedef boost::remove_reference<Stream>::type boost::asio::ssl::stream< Stream, Service >::next_layer_type

The type of the next layer.

template<typename Stream, typename Service = stream_service>
typedef next_layer_type::lowest_layer_type boost::asio::ssl::stream< Stream, Service >::lowest_layer_type

The type of the lowest layer.

template<typename Stream, typename Service = stream_service>
typedef next_layer_type::error_type boost::asio::ssl::stream< Stream, Service >::error_type

The type used for reporting errors.

template<typename Stream, typename Service = stream_service>
typedef Service boost::asio::ssl::stream< Stream, Service >::service_type

The type of the service that will be used to provide stream operations.

template<typename Stream, typename Service = stream_service>
typedef service_type::impl_type boost::asio::ssl::stream< Stream, Service >::impl_type

The native implementation type of the stream.


Member Enumeration Documentation

enum boost::asio::ssl::stream_base::handshake_type [inherited]

Different handshake types.

Enumerator:
client  Perform handshaking as a client.
server  Perform handshaking as a server.


Constructor & Destructor Documentation

template<typename Stream, typename Service = stream_service>
template<typename Arg, typename Context_Service>
boost::asio::ssl::stream< Stream, Service >::stream ( Arg &  arg,
basic_context< Context_Service > &  context 
) [explicit]

Construct a stream.

This constructor creates a stream and initialises the underlying stream object.

Parameters:
arg The argument to be passed to initialise the underlying stream.
context The SSL context to be used for the stream.

template<typename Stream, typename Service = stream_service>
boost::asio::ssl::stream< Stream, Service >::~stream (  ) 

Destructor.


Member Function Documentation

template<typename Stream, typename Service = stream_service>
boost::asio::io_service& boost::asio::ssl::stream< Stream, Service >::io_service (  ) 

Get the io_service associated with the object.

This function may be used to obtain the io_service object that the stream uses to dispatch handlers for asynchronous operations.

Returns:
A reference to the io_service object that stream will use to dispatch handlers. Ownership is not transferred to the caller.

template<typename Stream, typename Service = stream_service>
next_layer_type& boost::asio::ssl::stream< Stream, Service >::next_layer (  ) 

Get a reference to the next layer.

This function returns a reference to the next layer in a stack of stream layers.

Returns:
A reference to the next layer in the stack of stream layers. Ownership is not transferred to the caller.

template<typename Stream, typename Service = stream_service>
lowest_layer_type& boost::asio::ssl::stream< Stream, Service >::lowest_layer (  ) 

Get a reference to the lowest layer.

This function returns a reference to the lowest layer in a stack of stream layers.

Returns:
A reference to the lowest layer in the stack of stream layers. Ownership is not transferred to the caller.

template<typename Stream, typename Service = stream_service>
impl_type boost::asio::ssl::stream< Stream, Service >::impl (  ) 

Get the underlying implementation in the native type.

This function may be used to obtain the underlying implementation of the context. This is intended to allow access to stream functionality that is not otherwise provided.

template<typename Stream, typename Service = stream_service>
void boost::asio::ssl::stream< Stream, Service >::handshake ( handshake_type  type  ) 

Perform SSL handshaking.

This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs.

Parameters:
type The type of handshaking to be performed, i.e. as a client or as a server.
Exceptions:
boost::asio::error Thrown on failure.

template<typename Stream, typename Service = stream_service>
template<typename Error_Handler>
void boost::asio::ssl::stream< Stream, Service >::handshake ( handshake_type  type,
Error_Handler  error_handler 
)

Perform SSL handshaking.

This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs.

Parameters:
type The type of handshaking to be performed, i.e. as a client or as a server.
error_handler A handler to be called when the operation completes, to indicate whether or not an error has occurred. Copies will be made of the handler as required. The function signature of the handler must be:
 void error_handler(
   const boost::asio::error& error // Result of operation
 ); 

template<typename Stream, typename Service = stream_service>
template<typename Handler>
void boost::asio::ssl::stream< Stream, Service >::async_handshake ( handshake_type  type,
Handler  handler 
)

Start an asynchronous SSL handshake.

This function is used to asynchronously perform an SSL handshake on the stream. This function call always returns immediately.

Parameters:
type The type of handshaking to be performed, i.e. as a client or as a server.
handler The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void handler(
   const boost::asio::error& error,     // Result of operation
 ); 

template<typename Stream, typename Service = stream_service>
void boost::asio::ssl::stream< Stream, Service >::shutdown (  ) 

Shut down SSL on the stream.

This function is used to shut down SSL on the stream. The function call will block until SSL has been shut down or an error occurs.

Exceptions:
boost::asio::error Thrown on failure.

template<typename Stream, typename Service = stream_service>
template<typename Error_Handler>
void boost::asio::ssl::stream< Stream, Service >::shutdown ( Error_Handler  error_handler  ) 

Shut down SSL on the stream.

This function is used to shut down SSL on the stream. The function call will block until SSL has been shut down or an error occurs.

Parameters:
error_handler A handler to be called when the operation completes, to indicate whether or not an error has occurred. Copies will be made of the handler as required. The function signature of the handler must be:
 void error_handler(
   const boost::asio::error& error // Result of operation
 ); 

template<typename Stream, typename Service = stream_service>
template<typename Handler>
void boost::asio::ssl::stream< Stream, Service >::async_shutdown ( Handler  handler  ) 

Asynchronously shut down SSL on the stream.

This function is used to asynchronously shut down SSL on the stream. This function call always returns immediately.

Parameters:
handler The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void handler(
   const boost::asio::error& error,     // Result of operation
 ); 

template<typename Stream, typename Service = stream_service>
template<typename Const_Buffers>
std::size_t boost::asio::ssl::stream< Stream, Service >::write_some ( const Const_Buffers buffers  ) 

Write some data to the stream.

This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs.

Parameters:
buffers The data to be written.
Returns:
The number of bytes written.
Exceptions:
boost::asio::error Thrown on failure.
Note:
The write_some operation may not transmit all of the data to the peer. Consider using the boost::asio::write function if you need to ensure that all data is written before the blocking operation completes.

template<typename Stream, typename Service = stream_service>
template<typename Const_Buffers, typename Error_Handler>
std::size_t boost::asio::ssl::stream< Stream, Service >::write_some ( const Const_Buffers buffers,
Error_Handler  error_handler 
)

Write some data to the stream.

This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs.

Parameters:
buffers The data to be written to the stream.
error_handler A handler to be called when the operation completes, to indicate whether or not an error has occurred. Copies will be made of the handler as required. The function signature of the handler must be:
 void error_handler(
   const boost::asio::error& error // Result of operation.
 ); 
Returns:
The number of bytes written. Returns 0 if an error occurred and the error handler did not throw an exception.
Note:
The write_some operation may not transmit all of the data to the peer. Consider using the boost::asio::write function if you need to ensure that all data is written before the blocking operation completes.

template<typename Stream, typename Service = stream_service>
template<typename Const_Buffers, typename Handler>
void boost::asio::ssl::stream< Stream, Service >::async_write_some ( const Const_Buffers buffers,
Handler  handler 
)

Start an asynchronous write.

This function is used to asynchronously write one or more bytes of data to the stream. The function call always returns immediately.

Parameters:
buffers The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler The handler to be called when the write operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void handler(
   const boost::asio::error& error,     // Result of operation.
   std::size_t bytes_transferred // Number of bytes written.
 ); 
Note:
The async_write_some operation may not transmit all of the data to the peer. Consider using the boost::asio::async_write function if you need to ensure that all data is written before the blocking operation completes.

template<typename Stream, typename Service = stream_service>
template<typename Mutable_Buffers>
std::size_t boost::asio::ssl::stream< Stream, Service >::read_some ( const Mutable_Buffers buffers  ) 

Read some data from the stream.

This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Parameters:
buffers The buffers into which the data will be read.
Returns:
The number of bytes read.
Exceptions:
boost::asio::error Thrown on failure.
Note:
The read_some operation may not read all of the requested number of bytes. Consider using the boost::asio::read function if you need to ensure that the requested amount of data is read before the blocking operation completes.

template<typename Stream, typename Service = stream_service>
template<typename Mutable_Buffers, typename Error_Handler>
std::size_t boost::asio::ssl::stream< Stream, Service >::read_some ( const Mutable_Buffers buffers,
Error_Handler  error_handler 
)

Read some data from the stream.

This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Parameters:
buffers The buffers into which the data will be read.
error_handler A handler to be called when the operation completes, to indicate whether or not an error has occurred. Copies will be made of the handler as required. The function signature of the handler must be:
 void error_handler(
   const boost::asio::error& error // Result of operation.
 ); 
Returns:
The number of bytes read. Returns 0 if an error occurred and the error handler did not throw an exception.
Note:
The read_some operation may not read all of the requested number of bytes. Consider using the boost::asio::read function if you need to ensure that the requested amount of data is read before the blocking operation completes.

template<typename Stream, typename Service = stream_service>
template<typename Mutable_Buffers, typename Handler>
void boost::asio::ssl::stream< Stream, Service >::async_read_some ( const Mutable_Buffers buffers,
Handler  handler 
)

Start an asynchronous read.

This function is used to asynchronously read one or more bytes of data from the stream. The function call always returns immediately.

Parameters:
buffers The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler The handler to be called when the read operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void handler(
   const boost::asio::error& error,     // Result of operation.
   std::size_t bytes_transferred // Number of bytes read.
 ); 
Note:
The async_read_some operation may not read all of the requested number of bytes. Consider using the boost::asio::async_read function if you need to ensure that the requested amount of data is read before the asynchronous operation completes.

template<typename Stream, typename Service = stream_service>
template<typename Mutable_Buffers>
std::size_t boost::asio::ssl::stream< Stream, Service >::peek ( const Mutable_Buffers buffers  ) 

Peek at the incoming data on the stream.

This function is used to peek at the incoming data on the stream, without removing it from the input queue. The function call will block until data has been read successfully or an error occurs.

Parameters:
buffers The buffers into which the data will be read.
Returns:
The number of bytes read.
Exceptions:
boost::asio::error Thrown on failure.

template<typename Stream, typename Service = stream_service>
template<typename Mutable_Buffers, typename Error_Handler>
std::size_t boost::asio::ssl::stream< Stream, Service >::peek ( const Mutable_Buffers buffers,
Error_Handler  error_handler 
)

Peek at the incoming data on the stream.

This function is used to peek at the incoming data on the stream, withoutxi removing it from the input queue. The function call will block until data has been read successfully or an error occurs.

Parameters:
buffers The buffers into which the data will be read.
error_handler A handler to be called when the operation completes, to indicate whether or not an error has occurred. Copies will be made of the handler as required. The function signature of the handler must be:
 void error_handler(
   const boost::asio::error& error // Result of operation.
 ); 
Returns:
The number of bytes read. Returns 0 if an error occurred and the error handler did not throw an exception.

template<typename Stream, typename Service = stream_service>
std::size_t boost::asio::ssl::stream< Stream, Service >::in_avail (  ) 

Determine the amount of data that may be read without blocking.

This function is used to determine the amount of data, in bytes, that may be read from the stream without blocking.

Returns:
The number of bytes of data that can be read without blocking.
Exceptions:
boost::asio::error Thrown on failure.

template<typename Stream, typename Service = stream_service>
template<typename Error_Handler>
std::size_t boost::asio::ssl::stream< Stream, Service >::in_avail ( Error_Handler  error_handler  ) 

Determine the amount of data that may be read without blocking.

This function is used to determine the amount of data, in bytes, that may be read from the stream without blocking.

Parameters:
error_handler A handler to be called when the operation completes, to indicate whether or not an error has occurred. Copies will be made of the handler as required. The function signature of the handler must be:
 void error_handler(
   const boost::asio::error& error // Result of operation
 ); 
Returns:
The number of bytes of data that can be read without blocking.


Member Data Documentation

template<typename Stream, typename Service = stream_service>
Stream boost::asio::ssl::stream< Stream, Service >::next_layer_ [private]

The next layer.

template<typename Stream, typename Service = stream_service>
service_type& boost::asio::ssl::stream< Stream, Service >::service_ [private]

The backend service implementation.

template<typename Stream, typename Service = stream_service>
impl_type boost::asio::ssl::stream< Stream, Service >::impl_ [private]

The underlying native implementation.

Copyright © 2003 - 2006 Christopher M. Kohlhoff


Home | Reference | Tutorial | Examples | Design