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

basic_dgram_socket Class Template Reference

The basic_dgram_socket class template provides asynchronous and blocking datagram-oriented socket functionality. Most applications will use the dgram_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 dgram socket.

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


Public Member Functions

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

template<typename Address>  basic_dgram_socket (demuxer_type &d, const Address &address)
 Construct a basic_dgram_socket, opening it and binding it to the given local address.

 ~basic_dgram_socket ()
 Destructor.

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

template<typename Protocol> void open (const Protocol &protocol)
 Open the socket using the specified protocol.

template<typename Protocol, typename Error_Handler> void open (const Protocol &protocol, Error_Handler error_handler)
 Open the socket using the specified protocol.

template<typename Address> void bind (const Address &address)
 Bind the socket to the given local address.

template<typename Address, typename Error_Handler> void bind (const Address &address, Error_Handler error_handler)
 Bind the socket to the given local address.

void close ()
 Close the socket.

impl_type impl ()
 Get 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> size_t sendto (const void *data, size_t length, const Address &destination)
 Send a datagram to the specified address.

template<typename Address, typename Error_Handler> size_t sendto (const void *data, size_t length, const Address &destination, Error_Handler error_handler)
 Send a datagram to the specified address.

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

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

template<typename Address> size_t recvfrom (void *data, size_t max_length, Address &sender_address)
 Receive a datagram with the address of the sender.

template<typename Address, typename Error_Handler> size_t recvfrom (void *data, size_t max_length, Address &sender_address, Error_Handler error_handler)
 Receive a datagram with the address of the sender.

template<typename Address, typename Handler> void async_recvfrom (void *data, size_t max_length, Address &sender_address, Handler handler)
 Start an asynchronous receive.

template<typename Address, typename Handler, typename Completion_Context> void async_recvfrom (void *data, size_t max_length, Address &sender_address, 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_dgram_socket< Service >

The basic_dgram_socket class template provides asynchronous and blocking datagram-oriented socket functionality. Most applications will use the dgram_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 dgram socket.

typedef service_type::demuxer_type demuxer_type
 

The demuxer type for this asynchronous type.


Constructor & Destructor Documentation

basic_dgram_socket demuxer_type d  )  [explicit]
 

Construct a basic_dgram_socket without opening it.

This constructor creates a dgram socket without opening it. The open() function must be called before data can be sent or received on the socket.

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

basic_dgram_socket demuxer_type d,
const Address &  address
 

Construct a basic_dgram_socket, opening it and binding it to the given local address.

This constructor creates a dgram socket and automatically opens it bound to the specified address on the local machine. The protocol is determined automatically to be the default datagram protocol associated with the given address type.

Parameters:
d The demuxer object that the dgram socket will use to deliver completions for any asynchronous operations performed on the socket.
address An address on the local machine to which the dgram socket will be bound.
Exceptions:
socket_error Thrown on failure.

~basic_dgram_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 dgram socket uses to deliver completions for asynchronous operations.

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

void open const Protocol &  protocol  ) 
 

Open the socket using the specified protocol.

This function opens the dgram socket so that it will use the specified protocol.

Parameters:
protocol An object specifying which protocol is to be used.
Exceptions:
socket_error Thrown on failure.

void open const Protocol &  protocol,
Error_Handler  error_handler
 

Open the socket using the specified protocol.

This function opens the dgram socket so that it will use the specified protocol.

Parameters:
protocol An object specifying which protocol is to be used.
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 bind const Address &  address  ) 
 

Bind the socket to the given local address.

This function binds the dgram socket to the specified address on the local machine.

Parameters:
address An address on the local machine to which the dgram socket will be bound.
Exceptions:
socket_error Thrown on failure.

void bind const Address &  address,
Error_Handler  error_handler
 

Bind the socket to the given local address.

This function binds the dgram socket to the specified address on the local machine.

Parameters:
address An address on the local machine to which the dgram socket will be bound.
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 close  ) 
 

Close the socket.

This function is used to close the dgram socket. Any asynchronous sendto or recvfrom operations will be cancelled immediately.

A subsequent call to open() is required before the socket can again be used to again perform send and receive operations.

impl_type impl  ) 
 

Get the underlying implementation in the native type.

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

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

size_t sendto const void *  data,
size_t  length,
const Address &  destination
 

Send a datagram to the specified address.

This function is used to send a datagram to the specified remote address. 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 address.
length The size of the data to be sent, in bytes.
destination The remote address to which the data will be sent.
Returns:
The number of bytes sent.
Exceptions:
socket_error Thrown on failure.

size_t sendto const void *  data,
size_t  length,
const Address &  destination,
Error_Handler  error_handler
 

Send a datagram to the specified address.

This function is used to send a datagram to the specified remote address. 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 address.
length The size of the data to be sent, in bytes.
destination The remote address to which the data will be sent.
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.

void async_sendto const void *  data,
size_t  length,
const Address &  destination,
Handler  handler
 

Start an asynchronous send.

This function is used to asynchronously send a datagram to the specified remote address. The function call always returns immediately.

Parameters:
data The data to be sent to the remote address. 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.
destination The remote address to which the data will be sent. Copies will be made of the address as required.
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
 ); 

void async_sendto const void *  data,
size_t  length,
const Address &  destination,
Handler  handler,
Completion_Context  context
 

Start an asynchronous send.

This function is used to asynchronously send a datagram to the specified remote address. The function call always returns immediately.

Parameters:
data The data to be sent to the remote address. 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.
destination The remote address to which the data will be sent. Copies will be made of the address as required.
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 socket_error& error, size_t bytes_sent).
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.

size_t recvfrom void *  data,
size_t  max_length,
Address &  sender_address
 

Receive a datagram with the address of the sender.

This function is used to receive a datagram. The function call will block until data has been received successfully or an error occurs.

Parameters:
data The data buffer into which the received datagram will be written.
max_length The maximum length, in bytes, of data that can be held in the supplied buffer.
sender_address An address object that receives the address of the remote sender of the datagram.
Returns:
The number of bytes received.
Exceptions:
socket_error Thrown on failure.

size_t recvfrom void *  data,
size_t  max_length,
Address &  sender_address,
Error_Handler  error_handler
 

Receive a datagram with the address of the sender.

This function is used to receive a datagram. The function call will block until data has been received successfully or an error occurs.

Parameters:
data The data buffer into which the received datagram will be written.
max_length The maximum length, in bytes, of data that can be held in the supplied buffer.
sender_address An address object that receives the address of the remote sender of the datagram.
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.

void async_recvfrom void *  data,
size_t  max_length,
Address &  sender_address,
Handler  handler
 

Start an asynchronous receive.

This function is used to asynchronously receive a datagram. The function call always returns immediately.

Parameters:
data The data buffer into which the received datagram will be written. Ownership of the data buffer is retained by the caller, which must guarantee that it is valid until the handler is called.
max_length The maximum length, in bytes, of data that can be held in the supplied buffer.
sender_address An address object that receives the address of the remote sender of the datagram. Ownership of the sender_address object is retained by the caller, which must guarantee that it is valid until the handler is called.
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
 ); 

void async_recvfrom void *  data,
size_t  max_length,
Address &  sender_address,
Handler  handler,
Completion_Context  context
 

Start an asynchronous receive.

This function is used to asynchronously receive a datagram. The function call always returns immediately.

Parameters:
data The data buffer into which the received datagram will be written. Ownership of the data buffer is retained by the caller, which must guarantee that it is valid until the handler is called.
max_length The maximum length, in bytes, of data that can be held in the supplied buffer.
sender_address An address object that receives the address of the remote sender of the datagram. Ownership of the sender_address object is retained by the caller, which must guarantee that it is valid until the handler is called.
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.


Member Data Documentation

service_type& service_ [private]
 

The backend service implementation.

impl_type impl_ [private]
 

The underlying native implementation.