asio 0.1.5 Main Page | Class Index | Member Index | Tutorial

basic_stream_socket Class Template Reference

The basic_stream_socket class template provides asynchronous and blocking stream-oriented socket functionality. Most applications will use the stream_socket typedef. More...

List of all members.

Public Types

typedef Service service_type
 The type of the service that will be used to provide socket operations.

typedef service_type::impl_type impl_type
 The native implementation type of the stream socket.

typedef service_type::demuxer_type demuxer_type
 The demuxer type for this asynchronous type.

typedef basic_stream_socket<
service_type
lowest_layer_type
 A basic_stream_socket is always the lowest layer.


Public Member Functions

 basic_stream_socket (demuxer_type &d)
 Construct a basic_stream_socket without opening it.

 ~basic_stream_socket ()
 Destructor.

demuxer_typedemuxer ()
 Get the demuxer associated with the asynchronous object.

void close ()
 Close the socket.

lowest_layer_typelowest_layer ()
 Get a reference to the lowest layer.

impl_type impl ()
 Get the underlying implementation in the native type.

void set_impl (impl_type new_impl)
 Set the underlying implementation in the native type.

template<typename Option> void set_option (const Option &option)
 Set an option on the socket.

template<typename Option, typename Error_Handler> void set_option (const Option &option, Error_Handler error_handler)
 Set an option on the socket.

template<typename Option> void get_option (Option &option)
 Get an option from the socket.

template<typename Option, typename Error_Handler> void get_option (Option &option, Error_Handler error_handler)
 Get an option from the socket.

template<typename Address> void get_local_address (Address &address)
 Get the local address of the socket.

template<typename Address, typename Error_Handler> void get_local_address (Address &address, Error_Handler error_handler)
 Get the local address of the socket.

template<typename Address> void get_remote_address (Address &address)
 Get the remote address of the socket.

template<typename Address, typename Error_Handler> void get_remote_address (Address &address, Error_Handler error_handler)
 Get the remote address of the socket.

size_t send (const void *data, size_t length)
 Send the given data to the peer.

template<typename Error_Handler> size_t send (const void *data, size_t length, Error_Handler error_handler)
 Send the given data to the peer.

template<typename Handler> void async_send (const void *data, size_t length, Handler handler)
 Start an asynchronous send.

template<typename Handler, typename Completion_Context> void async_send (const void *data, size_t length, Handler handler, Completion_Context context)
 Start an asynchronous send.

size_t recv (void *data, size_t max_length)
 Receive some data from the peer.

template<typename Error_Handler> size_t recv (void *data, size_t max_length, Error_Handler error_handler)
 Receive some data from the peer.

template<typename Handler> void async_recv (void *data, size_t max_length, Handler handler)
 Start an asynchronous receive.

template<typename Handler, typename Completion_Context> void async_recv (void *data, size_t max_length, Handler handler, Completion_Context context)
 Start an asynchronous receive.


Private Attributes

service_typeservice_
 The backend service implementation.

impl_type impl_
 The underlying native implementation.


Detailed Description

template<typename Service>
class asio::basic_stream_socket< Service >

The basic_stream_socket class template provides asynchronous and blocking stream-oriented socket functionality. Most applications will use the stream_socket typedef.


Member Typedef Documentation

typedef Service service_type
 

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

typedef service_type::impl_type impl_type
 

The native implementation type of the stream socket.

typedef service_type::demuxer_type demuxer_type
 

The demuxer type for this asynchronous type.

typedef basic_stream_socket<service_type> lowest_layer_type
 

A basic_stream_socket is always the lowest layer.


Constructor & Destructor Documentation

basic_stream_socket demuxer_type d  )  [explicit]
 

Construct a basic_stream_socket without opening it.

This constructor creates a stream socket without connecting it to a remote peer. The socket needs to be connected or accepted before data can be sent or received on it.

Parameters:
d The demuxer object that the stream socket will use to deliver completions for any asynchronous operations performed on the socket.

~basic_stream_socket  ) 
 

Destructor.


Member Function Documentation

demuxer_type& demuxer  ) 
 

Get the demuxer associated with the asynchronous object.

This function may be used to obtain the demuxer object that the stream socket uses to deliver completions for asynchronous operations.

Returns:
A reference to the demuxer object that stream socket will use to deliver completion notifications. Ownership is not transferred to the caller.

void close  ) 
 

Close the socket.

This function is used to close the stream socket. Any asynchronous send or recv operations will be cancelled immediately.

lowest_layer_type& lowest_layer  ) 
 

Get a reference to the lowest layer.

This function returns a reference to the lowest layer in a stack of stream layers. Since a basic_stream_socket cannot contain any further stream layers, it simply returns a reference to itself.

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

impl_type impl  ) 
 

Get the underlying implementation in the native type.

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

void set_impl impl_type  new_impl  ) 
 

Set the underlying implementation in the native type.

This function is used by the acceptor and connector implementations to set the underlying implementation associated with the stream socket.

Parameters:
new_impl The new underlying socket implementation.

void set_option const Option &  option  ) 
 

Set an option on the socket.

This function is used to set an option on the socket.

Parameters:
option The new option value to be set on the socket.
Exceptions:
socket_error Thrown on failure.

void set_option const Option &  option,
Error_Handler  error_handler
 

Set an option on the socket.

This function is used to set an option on the socket.

Parameters:
option The new option value to be set on the socket.
error_handler The handler to be called when an error occurs. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void error_handler(
   const asio::socket_error& error // Result of operation
 ); 

void get_option Option &  option  ) 
 

Get an option from the socket.

This function is used to get the current value of an option on the socket.

Parameters:
option The option value to be obtained from the socket.
Exceptions:
socket_error Thrown on failure.

void get_option Option &  option,
Error_Handler  error_handler
 

Get an option from the socket.

This function is used to get the current value of an option on the socket.

Parameters:
option The option value to be obtained from the socket.
error_handler The handler to be called when an error occurs. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void error_handler(
   const asio::socket_error& error // Result of operation
 ); 

void get_local_address Address &  address  ) 
 

Get the local address of the socket.

This function is used to obtain the locally bound address of the socket.

Parameters:
address An address object that receives the local address of the socket.
Exceptions:
socket_error Thrown on failure.

void get_local_address Address &  address,
Error_Handler  error_handler
 

Get the local address of the socket.

This function is used to obtain the locally bound address of the socket.

Parameters:
address An address object that receives the local address of the socket.
error_handler The handler to be called when an error occurs. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void error_handler(
   const asio::socket_error& error // Result of operation
 ); 

void get_remote_address Address &  address  ) 
 

Get the remote address of the socket.

This function is used to obtain the remote address of the socket.

Parameters:
address An address object that receives the remote address of the socket.
Exceptions:
socket_error Thrown on failure.

void get_remote_address Address &  address,
Error_Handler  error_handler
 

Get the remote address of the socket.

This function is used to obtain the remote address of the socket.

Parameters:
address An address object that receives the remote address of the socket.
error_handler The handler to be called when an error occurs. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void error_handler(
   const asio::socket_error& error // Result of operation
 ); 

size_t send const void *  data,
size_t  length
 

Send the given data to the peer.

This function is used to send data to the stream socket's peer. The function call will block until the data has been sent successfully or an error occurs.

Parameters:
data The data to be sent to remote peer.
length The size of the data to be sent, in bytes.
Returns:
The number of bytes sent or 0 if the connection was closed cleanly.
Exceptions:
socket_error Thrown on failure.
Note:
The send operation may not transmit all of the data to the peer. Consider using the asio::send_n() function if you need to ensure that all data is sent before the blocking operation completes.

size_t send const void *  data,
size_t  length,
Error_Handler  error_handler
 

Send the given data to the peer.

This function is used to send data to the stream socket's peer. The function call will block until the data has been sent successfully or an error occurs.

Parameters:
data The data to be sent to remote peer.
length The size of the data to be sent, in bytes.
error_handler The handler to be called when an error occurs. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void error_handler(
   const asio::socket_error& error // Result of operation
 ); 
Returns:
The number of bytes sent or 0 if the connection was closed cleanly.
Note:
The send operation may not transmit all of the data to the peer. Consider using the asio::send_n() function if you need to ensure that all data is sent before the blocking operation completes.

void async_send const void *  data,
size_t  length,
Handler  handler
 

Start an asynchronous send.

This function is used to asynchronously send data to the stream socket's peer. The function call always returns immediately.

Parameters:
data The data to be sent to the remote peer. Ownership of the data is retained by the caller, which must guarantee that it is valid until the handler is called.
length The size of the data to be sent, in bytes.
handler The completion handler to be called when the send operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void handler(
   const asio::socket_error& error, // Result of operation
   size_t bytes_sent                // Number of bytes sent
 ); 
Note:
The send operation may not transmit all of the data to the peer. Consider using the asio::async_send_n() function if you need to ensure that all data is sent before the asynchronous operation completes.

void async_send const void *  data,
size_t  length,
Handler  handler,
Completion_Context  context
 

Start an asynchronous send.

This function is used to asynchronously send data to the stream socket's peer. The function call always returns immediately.

Parameters:
data The data to be sent to the remote peer. Ownership of the data is retained by the caller, which must guarantee that it is valid until the handler is called.
length The size of the data to be sent, in bytes.
handler The completion handler to be called when the send operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void handler(
   const asio::socket_error& error, // Result of operation
   size_t bytes_sent                // Number of bytes sent
 ); 
context The completion context which controls the number of concurrent invocations of handlers that may be made. Copies will be made of the context object as required, however all copies are equivalent.
Note:
The send operation may not transmit all of the data to the peer. Consider using the asio::async_send_n() function if you need to ensure that all data is sent before the asynchronous operation completes.

size_t recv void *  data,
size_t  max_length
 

Receive some data from the peer.

This function is used to receive data from the stream socket's peer. The function call will block until data has received successfully or an error occurs.

Parameters:
data The buffer into which the received data will be written.
max_length The maximum size of the data to be received, in bytes.
Returns:
The number of bytes received or 0 if the connection was closed cleanly.
Exceptions:
socket_error Thrown on failure.
Note:
The recv operation may not receive all of the requested number of bytes. Consider using the asio::recv_n() function if you need to ensure that the requested amount of data is received before the blocking operation completes.

size_t recv void *  data,
size_t  max_length,
Error_Handler  error_handler
 

Receive some data from the peer.

This function is used to receive data from the stream socket's peer. The function call will block until data has received successfully or an error occurs.

Parameters:
data The buffer into which the received data will be written.
max_length The maximum size of the data to be received, in bytes.
error_handler The handler to be called when an error occurs. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void error_handler(
   const asio::socket_error& error // Result of operation
 ); 
Returns:
The number of bytes received or 0 if the connection was closed cleanly.
Note:
The recv operation may not receive all of the requested number of bytes. Consider using the asio::recv_n() function if you need to ensure that the requested amount of data is received before the blocking operation completes.

void async_recv void *  data,
size_t  max_length,
Handler  handler
 

Start an asynchronous receive.

This function is used to asynchronously receive data from the stream socket's peer. The function call always returns immediately.

Parameters:
data The buffer into which the received data will be written. Ownership of the buffer is retained by the caller, which must guarantee that it is valid until the handler is called.
max_length The maximum size of the data to be received, in bytes.
handler The completion handler to be called when the receive operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void handler(
   const asio::socket_error& error, // Result of operation
   size_t bytes_received            // Number of bytes received
 ); 
Note:
The recv operation may not receive all of the requested number of bytes. Consider using the asio::async_recv_n() function if you need to ensure that the requested amount of data is received before the asynchronous operation completes.

void async_recv void *  data,
size_t  max_length,
Handler  handler,
Completion_Context  context
 

Start an asynchronous receive.

This function is used to asynchronously receive data from the stream socket's peer. The function call always returns immediately.

Parameters:
data The buffer into which the received data will be written. Ownership of the buffer is retained by the caller, which must guarantee that it is valid until the handler is called.
max_length The maximum size of the data to be received, in bytes.
handler The completion handler to be called when the receive operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
 void handler(
   const asio::socket_error& error, // Result of operation
   size_t bytes_received            // Number of bytes received
 ); 
context The completion context which controls the number of concurrent invocations of handlers that may be made. Copies will be made of the context object as required, however all copies are equivalent.
Note:
The recv operation may not receive all of the requested number of bytes. Consider using the asio::async_recv_n() function if you need to ensure that the requested amount of data is received before the asynchronous operation completes.


Member Data Documentation

service_type& service_ [private]
 

The backend service implementation.

impl_type impl_ [private]
 

The underlying native implementation.