From 64efa607dc6bc3b77169f0094cf3582e6aa74347 Mon Sep 17 00:00:00 2001 From: chris Date: Mon, 3 Nov 2003 02:07:56 +0000 Subject: [PATCH] Added doxygen documentation for the send and recv helper functions. --- asio/include/asio/basic_stream_socket.hpp | 27 ++++ asio/include/asio/recv.hpp | 174 ++++++++++++++++++++-- asio/include/asio/send.hpp | 169 +++++++++++++++++++-- 3 files changed, 344 insertions(+), 26 deletions(-) diff --git a/asio/include/asio/basic_stream_socket.hpp b/asio/include/asio/basic_stream_socket.hpp index 24b0d796..1e546f68 100644 --- a/asio/include/asio/basic_stream_socket.hpp +++ b/asio/include/asio/basic_stream_socket.hpp @@ -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 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 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 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 void async_recv(void* data, size_t max_length, Handler handler, diff --git a/asio/include/asio/recv.hpp b/asio/include/asio/recv.hpp index 5c90ff99..91231c3c 100644 --- a/asio/include/asio/recv.hpp +++ b/asio/include/asio/recv.hpp @@ -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 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 + * 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 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 + * 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 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 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 + * 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 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 + * 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 void async_recv_n(Stream& s, void* data, size_t length, Handler handler, Completion_Context& context) diff --git a/asio/include/asio/send.hpp b/asio/include/asio/send.hpp index 7f24f2bf..a79a52c6 100644 --- a/asio/include/asio/send.hpp +++ b/asio/include/asio/send.hpp @@ -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 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 + * 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 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 + * 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 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 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 + * 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 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 + * 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 void async_send_n(Stream& s, const void* data, size_t length, Handler handler, Completion_Context& context)