AuroraMiddleware/asio
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Added doxygen documentation for the send and recv helper functions.

Browse Source
This commit is contained in:
chris 2003-11-03 02:07:56 +00:00
parent 49195522c9
commit 64efa607dc
3 changed files with 344 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
asio/include/asio/basic_stream_socket.hpp
View File

@ -142,6 +142,10 @@ public:
* cleanly.
*
* @throws 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)
{
@ -166,6 +170,10 @@ public:
* const asio::socket_error& error, // Result of operation
* size_t bytes_sent // Number of bytes sent
* ); @endcode
*
* @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.
*/
template <typename Handler>
void async_send(const void* data, size_t length, Handler handler)
@ -197,6 +205,10 @@ public:
* concurrent invocations of handlers that may be made. Ownership of the
* object is retained by the caller, which must guarantee that it is valid
* until after the handler has been called.
*
* @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.
*/
template <typename Handler, typename Completion_Context>
void async_send(const void* data, size_t length, Handler handler,
@ -219,6 +231,11 @@ public:
* cleanly.
*
* @throws 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)
{
@ -243,6 +260,11 @@ public:
* const asio::socket_error& error, // Result of operation
* size_t bytes_received // Number of bytes received
* ); @endcode
*
* @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.
*/
template <typename Handler>
void async_recv(void* data, size_t max_length, Handler handler)
@ -274,6 +296,11 @@ public:
* concurrent invocations of handlers that may be made. Ownership of the
* object is retained by the caller, which must guarantee that it is valid
* until after the handler has been called.
*
* @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.
*/
template <typename Handler, typename Completion_Context>
void async_recv(void* data, size_t max_length, Handler handler,

174
asio/include/asio/recv.hpp
View File

@ -21,24 +21,101 @@
namespace asio {
/// Read some data from a stream. Returns the number of bytes received or 0 if
/// end-of-file or connection closed. Throws an exception on failure.
/// Read some data from a stream.
/**
* This function is used to receive data on a stream. The function call will
* block until data has received successfully or an error occurs.
*
* @param s The stream on which the data is to be received.
*
* @param data The buffer into which the received data will be written.
*
* @param max_length The maximum size of the data to be received, in bytes.
*
* @returns The number of bytes received, or 0 if end-of-file was reached or
* the connection was closed cleanly.
*
* @note Throws an exception on failure. The type of the exception depends
* on the underlying stream's recv operation.
*
* @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.
*/
template <typename Stream>
size_t recv(Stream& s, void* data, size_t max_length)
{
return s.recv(data, max_length);
}
/// Start an asynchronous receive. The buffer for the data being received must
/// be valid for the lifetime of the asynchronous operation.
/// Start an asynchronous receive.
/**
* This function is used to asynchronously receive data on a stream. The
* function call always returns immediately.
*
* @param s The stream on which the data is to be received.
*
* @param 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.
*
* @param max_length The maximum size of the data to be received, in bytes.
*
* @param 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:
* @code template <typename Error>
* void handler(
* const Error& error, // Result of operation (the actual type is dependent
* // on the underlying stream's send operation)
* size_t bytes_received // Number of bytes received
* ); @endcode
*
* @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.
*/
template <typename Stream, typename Handler>
void async_recv(Stream& s, void* data, size_t max_length, Handler handler)
{
s.async_recv(data, max_length, handler);
}
/// Start an asynchronous receive. The buffer for the data being received must
/// be valid for the lifetime of the asynchronous operation.
/// Start an asynchronous receive.
/**
* This function is used to asynchronously receive data on a stream. The
* function call always returns immediately.
*
* @param s The stream on which the data is to be received.
*
* @param 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.
*
* @param max_length The maximum size of the data to be received, in bytes.
*
* @param 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:
* @code template <typename Error>
* void handler(
* const Error& error, // Result of operation (the actual type is dependent
* // on the underlying stream's send operation)
* size_t bytes_received // Number of bytes received
* ); @endcode
*
* @param context The completion context which controls the number of
* concurrent invocations of handlers that may be made. Ownership of the
* object is retained by the caller, which must guarantee that it is valid
* until after the handler has been called.
*
* @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.
*/
template <typename Stream, typename Handler, typename Completion_Context>
void async_recv(Stream& s, void* data, size_t max_length, Handler handler,
Completion_Context& context)
@ -46,9 +123,27 @@ void async_recv(Stream& s, void* data, size_t max_length, Handler handler,
s.async_recv(data, max_length, handler, context);
}
/// Read the specified amount of data from the stream before returning. Returns
/// the number of bytes received on the last recv operation or 0 if end-of-file
/// or connection closed. Throws an exception on failure.
/// Read the specified amount of data from the stream before returning.
/**
* This function is used to receive an exact number of bytes of data on a
* stream. The function call will block until the specified number of bytes has
* been received successfully or an error occurs.
*
* @param s The stream on which the data is to be received.
*
* @param data The buffer into which the received data will be written.
*
* @param length The size of the data to be received, in bytes.
*
* @param total_bytes_recvd An optional output parameter that receives the
* total number of bytes actually received.
*
* @returns The number of bytes received on the last send, or 0 if end-of-file
* was reached or the connection was closed cleanly.
*
* @note Throws an exception on failure. The type of the exception depends
* on the underlying stream's recv operation.
*/
template <typename Stream>
size_t recv_n(Stream& s, void* data, size_t length,
size_t* total_bytes_recvd = 0)
@ -127,8 +222,32 @@ namespace detail
} // namespace detail
/// Start an asynchronous receive that will not complete until the specified
/// amount of data has been received. The target buffer for the data being
/// received must be valid for the lifetime of the asynchronous operation.
/// amount of data has been received.
/**
* This function is used to asynchronously receive an exact number of bytes of
* data on a stream. The function call always returns immediately.
*
* @param s The stream on which the data is to be received.
*
* @param 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.
*
* @param length The size of the data to be received, in bytes.
*
* @param 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:
* @code template <typename Error>
* void handler(
* const Error& error, // Result of operation (the actual type is
* // dependent on the underlying stream's recv
* // operation)
* size_t total_bytes_recvd, // Total number of bytes successfully received
* size_t last_bytes_recvd // Number of bytes received on last recv
* // operation
* ); @endcode
*/
template <typename Stream, typename Handler>
void async_recv_n(Stream& s, void* data, size_t length, Handler handler)
{
@ -138,8 +257,37 @@ void async_recv_n(Stream& s, void* data, size_t length, Handler handler)
}
/// Start an asynchronous receive that will not complete until the specified
/// amount of data has been received. The target buffer for the data being
/// received must be valid for the lifetime of the asynchronous operation.
/// amount of data has been received.
/**
* This function is used to asynchronously receive an exact number of bytes of
* data on a stream. The function call always returns immediately.
*
* @param s The stream on which the data is to be received.
*
* @param 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.
*
* @param length The size of the data to be received, in bytes.
*
* @param 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:
* @code template <typename Error>
* void handler(
* const Error& error, // Result of operation (the actual type is
* // dependent on the underlying stream's recv
* // operation)
* size_t total_bytes_recvd, // Total number of bytes successfully received
* size_t last_bytes_recvd // Number of bytes received on last recv
* // operation
* ); @endcode
*
* @param context The completion context which controls the number of
* concurrent invocations of handlers that may be made. Ownership of the
* object is retained by the caller, which must guarantee that it is valid
* until after the handler has been called.
*/
template <typename Stream, typename Handler, typename Completion_Context>
void async_recv_n(Stream& s, void* data, size_t length, Handler handler,
Completion_Context& context)

169
asio/include/asio/send.hpp
View File

@ -21,24 +21,98 @@
namespace asio {
/// Write some data to a stream. Returns the number of bytes sent or 0 if
/// end-of-file or connection closed. Throws an exception on failure.
/// Write some data to a stream.
/**
* This function is used to send data on a stream. The function call will block
* until the data has been sent successfully or an error occurs.
*
* @param s The stream on which the data is to be sent.
*
* @param data The data to be sent on the stream.
*
* @param length The size of the data to be sent, in bytes.
*
* @returns The number of bytes sent, or 0 if end-of-file was reached or the
* connection was closed cleanly.
*
* @note Throws an exception on failure. The type of the exception depends
* on the underlying stream's send operation.
*
* @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.
*/
template <typename Stream>
size_t send(Stream& s, const void* data, size_t length)
{
return s.send(data, length);
}
/// Start an asynchronous send. The buffer containing the data being sent
/// must be valid for the lifetime of the asynchronous operation.
/// Start an asynchronous send.
/**
* This function is used to asynchronously send data on a stream. The function
* call always returns immediately.
*
* @param s The stream on which the data is to be sent.
*
* @param data The data to be sent on the stream. Ownership of the data is
* retained by the caller, which must guarantee that it is valid until the
* handler is called.
*
* @param length The size of the data to be sent, in bytes.
*
* @param 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:
* @code template <typename Error>
* void handler(
* const Error& error, // Result of operation (the actual type is dependent
* // on the underlying stream's send operation)
* size_t bytes_sent // Number of bytes sent
* ); @endcode
*
* @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.
*/
template <typename Stream, typename Handler>
void async_send(Stream& s, const void* data, size_t length, Handler handler)
{
s.async_send(data, length, handler);
}
/// Start an asynchronous send. The buffer containing the data being sent
/// must be valid for the lifetime of the asynchronous operation.
/// Start an asynchronous send.
/**
* This function is used to asynchronously send data on a stream. The function
* call always returns immediately.
*
* @param s The stream on which the data is to be sent.
*
* @param data The data to be sent on the stream. Ownership of the data is
* retained by the caller, which must guarantee that it is valid until the
* handler is called.
*
* @param length The size of the data to be sent, in bytes.
*
* @param 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:
* @code template <typename Error>
* void handler(
* const Error& error, // Result of operation (the actual type is dependent
* // on the underlying stream's send operation)
* size_t bytes_sent // Number of bytes sent
* ); @endcode
*
* @param context The completion context which controls the number of
* concurrent invocations of handlers that may be made. Ownership of the
* object is retained by the caller, which must guarantee that it is valid
* until after the handler has been called.
*
* @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.
*/
template <typename Stream, typename Handler, typename Completion_Context>
void async_send(Stream& s, const void* data, size_t length, Handler handler,
Completion_Context& context)
@ -46,9 +120,27 @@ void async_send(Stream& s, const void* data, size_t length, Handler handler,
s.async_send(data, length, handler, context);
}
/// Write all of the given data to the stream before returning. Returns the
/// number of bytes sent on the last send or 0 if end-of-file or connection
/// closed. Throws an exception on failure.
/// Write all of the given data to the stream before returning.
/**
* This function is used to send an exact number of bytes of data on a stream.
* The function call will block until the specified number of bytes has been
* sent successfully or an error occurs.
*
* @param s The stream on which the data is to be sent.
*
* @param data The data to be sent on the stream.
*
* @param length The size of the data to be sent, in bytes.
*
* @param total_bytes_sent An optional output parameter that receives the
* total number of bytes actually sent.
*
* @returns The number of bytes sent on the last send, or 0 if end-of-file was
* reached or the connection was closed cleanly.
*
* @note Throws an exception on failure. The type of the exception depends
* on the underlying stream's send operation.
*/
template <typename Stream>
size_t send_n(Stream& s, const void* data, size_t length,
size_t* total_bytes_sent = 0)
@ -127,8 +219,31 @@ namespace detail
} // namespace detail
/// Start an asynchronous send that will not complete until the specified
/// amount of data has been sent. The buffer containing the data being sent
/// must be valid for the lifetime of the asynchronous operation.
/// amount of data has been sent.
/**
* This function is used to asynchronously send an exact number of bytes of
* data on a stream. The function call always returns immediately.
*
* @param s The stream on which the data is to be sent.
*
* @param data The data to be sent on the stream. Ownership of the data is
* retained by the caller, which must guarantee that it is valid until the
* handler is called.
*
* @param length The size of the data to be sent, in bytes.
*
* @param 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:
* @code template <typename Error>
* void handler(
* const Error& error, // Result of operation (the actual type is
* // dependent on the underlying stream's send
* // operation)
* size_t total_bytes_sent, // Total number of bytes successfully sent
* size_t last_bytes_sent // Number of bytes sent on last send operation
* ); @endcode
*/
template <typename Stream, typename Handler>
void async_send_n(Stream& s, const void* data, size_t length, Handler handler)
{
@ -138,8 +253,36 @@ void async_send_n(Stream& s, const void* data, size_t length, Handler handler)
}
/// Start an asynchronous send that will not complete until the specified
/// amount of data has been sent. The buffer containing the data being sent
/// must be valid for the lifetime of the asynchronous operation.
/// amount of data has been sent.
/**
* This function is used to asynchronously send an exact number of bytes of
* data on a stream. The function call always returns immediately.
*
* @param s The stream on which the data is to be sent.
*
* @param data The data to be sent on the stream. Ownership of the data is
* retained by the caller, which must guarantee that it is valid until the
* handler is called.
*
* @param length The size of the data to be sent, in bytes.
*
* @param 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:
* @code template <typename Error>
* void handler(
* const Error& error, // Result of operation (the actual type is
* // dependent on the underlying stream's send
* // operation)
* size_t total_bytes_sent, // Total number of bytes successfully sent
* size_t last_bytes_sent // Number of bytes sent on last send operation
* ); @endcode
*
* @param context The completion context which controls the number of
* concurrent invocations of handlers that may be made. Ownership of the
* object is retained by the caller, which must guarantee that it is valid
* until after the handler has been called.
*/
template <typename Stream, typename Handler, typename Completion_Context>
void async_send_n(Stream& s, const void* data, size_t length, Handler handler,
Completion_Context& context)