Chris@16: // Chris@16: // ssl/stream.hpp Chris@16: // ~~~~~~~~~~~~~~ Chris@16: // Chris@101: // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) Chris@16: // Chris@16: // Distributed under the Boost Software License, Version 1.0. (See accompanying Chris@16: // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Chris@16: // Chris@16: Chris@16: #ifndef BOOST_ASIO_SSL_STREAM_HPP Chris@16: #define BOOST_ASIO_SSL_STREAM_HPP Chris@16: Chris@16: #if defined(_MSC_VER) && (_MSC_VER >= 1200) Chris@16: # pragma once Chris@16: #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) Chris@16: Chris@16: #include Chris@16: Chris@16: #if defined(BOOST_ASIO_ENABLE_OLD_SSL) Chris@16: # include Chris@16: #else // defined(BOOST_ASIO_ENABLE_OLD_SSL) Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: # include Chris@16: #endif // defined(BOOST_ASIO_ENABLE_OLD_SSL) Chris@16: Chris@16: #include Chris@16: Chris@16: namespace boost { Chris@16: namespace asio { Chris@16: namespace ssl { Chris@16: Chris@16: #if defined(BOOST_ASIO_ENABLE_OLD_SSL) Chris@16: Chris@16: using boost::asio::ssl::old::stream; Chris@16: Chris@16: #else // defined(BOOST_ASIO_ENABLE_OLD_SSL) Chris@16: Chris@16: /// Provides stream-oriented functionality using SSL. Chris@16: /** Chris@16: * The stream class template provides asynchronous and blocking stream-oriented Chris@16: * functionality using SSL. Chris@16: * Chris@16: * @par Thread Safety Chris@16: * @e Distinct @e objects: Safe.@n Chris@16: * @e Shared @e objects: Unsafe. The application must also ensure that all Chris@16: * asynchronous operations are performed within the same implicit or explicit Chris@16: * strand. Chris@16: * Chris@16: * @par Example Chris@16: * To use the SSL stream template with an ip::tcp::socket, you would write: Chris@16: * @code Chris@16: * boost::asio::io_service io_service; Chris@16: * boost::asio::ssl::context ctx(boost::asio::ssl::context::sslv23); Chris@16: * boost::asio::ssl::stream sock(io_service, ctx); Chris@16: * @endcode Chris@16: * Chris@16: * @par Concepts: Chris@16: * AsyncReadStream, AsyncWriteStream, Stream, SyncReadStream, SyncWriteStream. Chris@16: */ Chris@16: template Chris@16: class stream : Chris@16: public stream_base, Chris@16: private noncopyable Chris@16: { Chris@16: public: Chris@16: /// The native handle type of the SSL stream. Chris@16: typedef SSL* native_handle_type; Chris@16: Chris@16: /// Structure for use with deprecated impl_type. Chris@16: struct impl_struct Chris@16: { Chris@16: SSL* ssl; Chris@16: }; Chris@16: Chris@16: /// (Deprecated: Use native_handle_type.) The underlying implementation type. Chris@16: typedef impl_struct* impl_type; Chris@16: Chris@16: /// The type of the next layer. Chris@16: typedef typename remove_reference::type next_layer_type; Chris@16: Chris@16: /// The type of the lowest layer. Chris@16: typedef typename next_layer_type::lowest_layer_type lowest_layer_type; Chris@16: Chris@16: /// Construct a stream. Chris@16: /** Chris@16: * This constructor creates a stream and initialises the underlying stream Chris@16: * object. Chris@16: * Chris@16: * @param arg The argument to be passed to initialise the underlying stream. Chris@16: * Chris@16: * @param ctx The SSL context to be used for the stream. Chris@16: */ Chris@16: template Chris@16: stream(Arg& arg, context& ctx) Chris@16: : next_layer_(arg), Chris@16: core_(ctx.native_handle(), next_layer_.lowest_layer().get_io_service()) Chris@16: { Chris@16: backwards_compatible_impl_.ssl = core_.engine_.native_handle(); Chris@16: } Chris@16: Chris@16: /// Destructor. Chris@16: ~stream() Chris@16: { Chris@16: } Chris@16: Chris@16: /// Get the io_service associated with the object. Chris@16: /** Chris@16: * This function may be used to obtain the io_service object that the stream Chris@16: * uses to dispatch handlers for asynchronous operations. Chris@16: * Chris@16: * @return A reference to the io_service object that stream will use to Chris@16: * dispatch handlers. Ownership is not transferred to the caller. Chris@16: */ Chris@16: boost::asio::io_service& get_io_service() Chris@16: { Chris@16: return next_layer_.lowest_layer().get_io_service(); Chris@16: } Chris@16: Chris@16: /// Get the underlying implementation in the native type. Chris@16: /** Chris@16: * This function may be used to obtain the underlying implementation of the Chris@16: * context. This is intended to allow access to context functionality that is Chris@16: * not otherwise provided. Chris@16: * Chris@16: * @par Example Chris@16: * The native_handle() function returns a pointer of type @c SSL* that is Chris@16: * suitable for passing to functions such as @c SSL_get_verify_result and Chris@16: * @c SSL_get_peer_certificate: Chris@16: * @code Chris@16: * boost::asio::ssl::stream sock(io_service, ctx); Chris@16: * Chris@16: * // ... establish connection and perform handshake ... Chris@16: * Chris@16: * if (X509* cert = SSL_get_peer_certificate(sock.native_handle())) Chris@16: * { Chris@16: * if (SSL_get_verify_result(sock.native_handle()) == X509_V_OK) Chris@16: * { Chris@16: * // ... Chris@16: * } Chris@16: * } Chris@16: * @endcode Chris@16: */ Chris@16: native_handle_type native_handle() Chris@16: { Chris@16: return core_.engine_.native_handle(); Chris@16: } Chris@16: Chris@16: /// (Deprecated: Use native_handle().) Get the underlying implementation in Chris@16: /// the native type. Chris@16: /** Chris@16: * This function may be used to obtain the underlying implementation of the Chris@16: * context. This is intended to allow access to stream functionality that is Chris@16: * not otherwise provided. Chris@16: */ Chris@16: impl_type impl() Chris@16: { Chris@16: return &backwards_compatible_impl_; Chris@16: } Chris@16: Chris@16: /// Get a reference to the next layer. Chris@16: /** Chris@16: * This function returns a reference to the next layer in a stack of stream Chris@16: * layers. Chris@16: * Chris@16: * @return A reference to the next layer in the stack of stream layers. Chris@16: * Ownership is not transferred to the caller. Chris@16: */ Chris@16: const next_layer_type& next_layer() const Chris@16: { Chris@16: return next_layer_; Chris@16: } Chris@16: Chris@16: /// Get a reference to the next layer. Chris@16: /** Chris@16: * This function returns a reference to the next layer in a stack of stream Chris@16: * layers. Chris@16: * Chris@16: * @return A reference to the next layer in the stack of stream layers. Chris@16: * Ownership is not transferred to the caller. Chris@16: */ Chris@16: next_layer_type& next_layer() Chris@16: { Chris@16: return next_layer_; Chris@16: } Chris@16: Chris@16: /// Get a reference to the lowest layer. Chris@16: /** Chris@16: * This function returns a reference to the lowest layer in a stack of Chris@16: * stream layers. Chris@16: * Chris@16: * @return A reference to the lowest layer in the stack of stream layers. Chris@16: * Ownership is not transferred to the caller. Chris@16: */ Chris@16: lowest_layer_type& lowest_layer() Chris@16: { Chris@16: return next_layer_.lowest_layer(); Chris@16: } Chris@16: Chris@16: /// Get a reference to the lowest layer. Chris@16: /** Chris@16: * This function returns a reference to the lowest layer in a stack of Chris@16: * stream layers. Chris@16: * Chris@16: * @return A reference to the lowest layer in the stack of stream layers. Chris@16: * Ownership is not transferred to the caller. Chris@16: */ Chris@16: const lowest_layer_type& lowest_layer() const Chris@16: { Chris@16: return next_layer_.lowest_layer(); Chris@16: } Chris@16: Chris@16: /// Set the peer verification mode. Chris@16: /** Chris@16: * This function may be used to configure the peer verification mode used by Chris@16: * the stream. The new mode will override the mode inherited from the context. Chris@16: * Chris@16: * @param v A bitmask of peer verification modes. See @ref verify_mode for Chris@16: * available values. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note Calls @c SSL_set_verify. Chris@16: */ Chris@16: void set_verify_mode(verify_mode v) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: set_verify_mode(v, ec); Chris@16: boost::asio::detail::throw_error(ec, "set_verify_mode"); Chris@16: } Chris@16: Chris@16: /// Set the peer verification mode. Chris@16: /** Chris@16: * This function may be used to configure the peer verification mode used by Chris@16: * the stream. The new mode will override the mode inherited from the context. Chris@16: * Chris@16: * @param v A bitmask of peer verification modes. See @ref verify_mode for Chris@16: * available values. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @note Calls @c SSL_set_verify. Chris@16: */ Chris@16: boost::system::error_code set_verify_mode( Chris@16: verify_mode v, boost::system::error_code& ec) Chris@16: { Chris@16: return core_.engine_.set_verify_mode(v, ec); Chris@16: } Chris@16: Chris@16: /// Set the peer verification depth. Chris@16: /** Chris@16: * This function may be used to configure the maximum verification depth Chris@16: * allowed by the stream. Chris@16: * Chris@16: * @param depth Maximum depth for the certificate chain verification that Chris@16: * shall be allowed. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note Calls @c SSL_set_verify_depth. Chris@16: */ Chris@16: void set_verify_depth(int depth) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: set_verify_depth(depth, ec); Chris@16: boost::asio::detail::throw_error(ec, "set_verify_depth"); Chris@16: } Chris@16: Chris@16: /// Set the peer verification depth. Chris@16: /** Chris@16: * This function may be used to configure the maximum verification depth Chris@16: * allowed by the stream. Chris@16: * Chris@16: * @param depth Maximum depth for the certificate chain verification that Chris@16: * shall be allowed. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @note Calls @c SSL_set_verify_depth. Chris@16: */ Chris@16: boost::system::error_code set_verify_depth( Chris@16: int depth, boost::system::error_code& ec) Chris@16: { Chris@16: return core_.engine_.set_verify_depth(depth, ec); Chris@16: } Chris@16: Chris@16: /// Set the callback used to verify peer certificates. Chris@16: /** Chris@16: * This function is used to specify a callback function that will be called Chris@16: * by the implementation when it needs to verify a peer certificate. Chris@16: * Chris@16: * @param callback The function object to be used for verifying a certificate. Chris@16: * The function signature of the handler must be: Chris@16: * @code bool verify_callback( Chris@16: * bool preverified, // True if the certificate passed pre-verification. Chris@16: * verify_context& ctx // The peer certificate and other context. Chris@16: * ); @endcode Chris@16: * The return value of the callback is true if the certificate has passed Chris@16: * verification, false otherwise. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note Calls @c SSL_set_verify. Chris@16: */ Chris@16: template Chris@16: void set_verify_callback(VerifyCallback callback) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->set_verify_callback(callback, ec); Chris@16: boost::asio::detail::throw_error(ec, "set_verify_callback"); Chris@16: } Chris@16: Chris@16: /// Set the callback used to verify peer certificates. Chris@16: /** Chris@16: * This function is used to specify a callback function that will be called Chris@16: * by the implementation when it needs to verify a peer certificate. Chris@16: * Chris@16: * @param callback The function object to be used for verifying a certificate. Chris@16: * The function signature of the handler must be: Chris@16: * @code bool verify_callback( Chris@16: * bool preverified, // True if the certificate passed pre-verification. Chris@16: * verify_context& ctx // The peer certificate and other context. Chris@16: * ); @endcode Chris@16: * The return value of the callback is true if the certificate has passed Chris@16: * verification, false otherwise. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @note Calls @c SSL_set_verify. Chris@16: */ Chris@16: template Chris@16: boost::system::error_code set_verify_callback(VerifyCallback callback, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: return core_.engine_.set_verify_callback( Chris@16: new detail::verify_callback(callback), ec); Chris@16: } Chris@16: Chris@16: /// Perform SSL handshaking. Chris@16: /** Chris@16: * This function is used to perform SSL handshaking on the stream. The Chris@16: * function call will block until handshaking is complete or an error occurs. Chris@16: * Chris@16: * @param type The type of handshaking to be performed, i.e. as a client or as Chris@16: * a server. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: void handshake(handshake_type type) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: handshake(type, ec); Chris@16: boost::asio::detail::throw_error(ec, "handshake"); Chris@16: } Chris@16: Chris@16: /// Perform SSL handshaking. Chris@16: /** Chris@16: * This function is used to perform SSL handshaking on the stream. The Chris@16: * function call will block until handshaking is complete or an error occurs. Chris@16: * Chris@16: * @param type The type of handshaking to be performed, i.e. as a client or as Chris@16: * a server. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: */ Chris@16: boost::system::error_code handshake(handshake_type type, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: detail::io(next_layer_, core_, detail::handshake_op(type), ec); Chris@16: return ec; Chris@16: } Chris@16: Chris@16: /// Perform SSL handshaking. Chris@16: /** Chris@16: * This function is used to perform SSL handshaking on the stream. The Chris@16: * function call will block until handshaking is complete or an error occurs. Chris@16: * Chris@16: * @param type The type of handshaking to be performed, i.e. as a client or as Chris@16: * a server. Chris@16: * Chris@16: * @param buffers The buffered data to be reused for the handshake. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: template Chris@16: void handshake(handshake_type type, const ConstBufferSequence& buffers) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: handshake(type, buffers, ec); Chris@16: boost::asio::detail::throw_error(ec, "handshake"); Chris@16: } Chris@16: Chris@16: /// Perform SSL handshaking. Chris@16: /** Chris@16: * This function is used to perform SSL handshaking on the stream. The Chris@16: * function call will block until handshaking is complete or an error occurs. Chris@16: * Chris@16: * @param type The type of handshaking to be performed, i.e. as a client or as Chris@16: * a server. Chris@16: * Chris@16: * @param buffers The buffered data to be reused for the handshake. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: */ Chris@16: template Chris@16: boost::system::error_code handshake(handshake_type type, Chris@16: const ConstBufferSequence& buffers, boost::system::error_code& ec) Chris@16: { Chris@16: detail::io(next_layer_, core_, Chris@16: detail::buffered_handshake_op(type, buffers), ec); Chris@16: return ec; Chris@16: } Chris@16: Chris@16: /// Start an asynchronous SSL handshake. Chris@16: /** Chris@16: * This function is used to asynchronously perform an SSL handshake on the Chris@16: * stream. This function call always returns immediately. Chris@16: * Chris@16: * @param type The type of handshaking to be performed, i.e. as a client or as Chris@16: * a server. Chris@16: * Chris@16: * @param handler The handler to be called when the handshake operation Chris@16: * completes. Copies will be made of the handler as required. The equivalent Chris@16: * function signature of the handler must be: Chris@16: * @code void handler( Chris@16: * const boost::system::error_code& error // Result of operation. Chris@16: * ); @endcode Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(HandshakeHandler, Chris@16: void (boost::system::error_code)) Chris@16: async_handshake(handshake_type type, Chris@16: BOOST_ASIO_MOVE_ARG(HandshakeHandler) handler) Chris@16: { Chris@16: // If you get an error on the following line it means that your handler does Chris@16: // not meet the documented type requirements for a HandshakeHandler. Chris@16: BOOST_ASIO_HANDSHAKE_HANDLER_CHECK(HandshakeHandler, handler) type_check; Chris@16: Chris@16: boost::asio::detail::async_result_init< Chris@16: HandshakeHandler, void (boost::system::error_code)> init( Chris@16: BOOST_ASIO_MOVE_CAST(HandshakeHandler)(handler)); Chris@16: Chris@16: detail::async_io(next_layer_, core_, Chris@16: detail::handshake_op(type), init.handler); Chris@16: Chris@16: return init.result.get(); Chris@16: } Chris@16: Chris@16: /// Start an asynchronous SSL handshake. Chris@16: /** Chris@16: * This function is used to asynchronously perform an SSL handshake on the Chris@16: * stream. This function call always returns immediately. Chris@16: * Chris@16: * @param type The type of handshaking to be performed, i.e. as a client or as Chris@16: * a server. Chris@16: * Chris@16: * @param buffers The buffered data to be reused for the handshake. Although Chris@16: * the buffers object may be copied as necessary, ownership of the underlying Chris@16: * buffers is retained by the caller, which must guarantee that they remain Chris@16: * valid until the handler is called. Chris@16: * Chris@16: * @param handler The handler to be called when the handshake operation Chris@16: * completes. Copies will be made of the handler as required. The equivalent Chris@16: * function signature of the handler must be: Chris@16: * @code void handler( Chris@16: * const boost::system::error_code& error, // Result of operation. Chris@16: * std::size_t bytes_transferred // Amount of buffers used in handshake. Chris@16: * ); @endcode Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(BufferedHandshakeHandler, Chris@16: void (boost::system::error_code, std::size_t)) Chris@16: async_handshake(handshake_type type, const ConstBufferSequence& buffers, Chris@16: BOOST_ASIO_MOVE_ARG(BufferedHandshakeHandler) handler) Chris@16: { Chris@16: // If you get an error on the following line it means that your handler does Chris@16: // not meet the documented type requirements for a BufferedHandshakeHandler. Chris@16: BOOST_ASIO_BUFFERED_HANDSHAKE_HANDLER_CHECK( Chris@16: BufferedHandshakeHandler, handler) type_check; Chris@16: Chris@16: boost::asio::detail::async_result_init init( Chris@16: BOOST_ASIO_MOVE_CAST(BufferedHandshakeHandler)(handler)); Chris@16: Chris@16: detail::async_io(next_layer_, core_, Chris@16: detail::buffered_handshake_op(type, buffers), Chris@16: init.handler); Chris@16: Chris@16: return init.result.get(); Chris@16: } Chris@16: Chris@16: /// Shut down SSL on the stream. Chris@16: /** Chris@16: * This function is used to shut down SSL on the stream. The function call Chris@16: * will block until SSL has been shut down or an error occurs. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: void shutdown() Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: shutdown(ec); Chris@16: boost::asio::detail::throw_error(ec, "shutdown"); Chris@16: } Chris@16: Chris@16: /// Shut down SSL on the stream. Chris@16: /** Chris@16: * This function is used to shut down SSL on the stream. The function call Chris@16: * will block until SSL has been shut down or an error occurs. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: */ Chris@16: boost::system::error_code shutdown(boost::system::error_code& ec) Chris@16: { Chris@16: detail::io(next_layer_, core_, detail::shutdown_op(), ec); Chris@16: return ec; Chris@16: } Chris@16: Chris@16: /// Asynchronously shut down SSL on the stream. Chris@16: /** Chris@16: * This function is used to asynchronously shut down SSL on the stream. This Chris@16: * function call always returns immediately. Chris@16: * Chris@16: * @param handler The handler to be called when the handshake operation Chris@16: * completes. Copies will be made of the handler as required. The equivalent Chris@16: * function signature of the handler must be: Chris@16: * @code void handler( Chris@16: * const boost::system::error_code& error // Result of operation. Chris@16: * ); @endcode Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ShutdownHandler, Chris@16: void (boost::system::error_code)) Chris@16: async_shutdown(BOOST_ASIO_MOVE_ARG(ShutdownHandler) handler) Chris@16: { Chris@16: // If you get an error on the following line it means that your handler does Chris@16: // not meet the documented type requirements for a ShutdownHandler. Chris@16: BOOST_ASIO_SHUTDOWN_HANDLER_CHECK(ShutdownHandler, handler) type_check; Chris@16: Chris@16: boost::asio::detail::async_result_init< Chris@16: ShutdownHandler, void (boost::system::error_code)> init( Chris@16: BOOST_ASIO_MOVE_CAST(ShutdownHandler)(handler)); Chris@16: Chris@16: detail::async_io(next_layer_, core_, detail::shutdown_op(), init.handler); Chris@16: Chris@16: return init.result.get(); Chris@16: } Chris@16: Chris@16: /// Write some data to the stream. Chris@16: /** Chris@16: * This function is used to write data on the stream. The function call will Chris@16: * block until one or more bytes of data has been written successfully, or Chris@16: * until an error occurs. Chris@16: * Chris@16: * @param buffers The data to be written. Chris@16: * Chris@16: * @returns The number of bytes written. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note The write_some operation may not transmit all of the data to the Chris@16: * peer. Consider using the @ref write function if you need to ensure that all Chris@16: * data is written before the blocking operation completes. Chris@16: */ Chris@16: template Chris@16: std::size_t write_some(const ConstBufferSequence& buffers) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: std::size_t n = write_some(buffers, ec); Chris@16: boost::asio::detail::throw_error(ec, "write_some"); Chris@16: return n; Chris@16: } Chris@16: Chris@16: /// Write some data to the stream. Chris@16: /** Chris@16: * This function is used to write data on the stream. The function call will Chris@16: * block until one or more bytes of data has been written successfully, or Chris@16: * until an error occurs. Chris@16: * Chris@16: * @param buffers The data to be written to the stream. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns The number of bytes written. Returns 0 if an error occurred. Chris@16: * Chris@16: * @note The write_some operation may not transmit all of the data to the Chris@16: * peer. Consider using the @ref write function if you need to ensure that all Chris@16: * data is written before the blocking operation completes. Chris@16: */ Chris@16: template Chris@16: std::size_t write_some(const ConstBufferSequence& buffers, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: return detail::io(next_layer_, core_, Chris@16: detail::write_op(buffers), ec); Chris@16: } Chris@16: Chris@16: /// Start an asynchronous write. Chris@16: /** Chris@16: * This function is used to asynchronously write one or more bytes of data to Chris@16: * the stream. The function call always returns immediately. Chris@16: * Chris@16: * @param buffers The data to be written to the stream. Although the buffers Chris@16: * object may be copied as necessary, ownership of the underlying buffers is Chris@16: * retained by the caller, which must guarantee that they remain valid until Chris@16: * the handler is called. Chris@16: * Chris@16: * @param handler The handler to be called when the write operation completes. Chris@16: * Copies will be made of the handler as required. The equivalent function Chris@16: * signature of the handler must be: Chris@16: * @code void handler( Chris@16: * const boost::system::error_code& error, // Result of operation. Chris@16: * std::size_t bytes_transferred // Number of bytes written. Chris@16: * ); @endcode Chris@16: * Chris@16: * @note The async_write_some operation may not transmit all of the data to Chris@16: * the peer. Consider using the @ref async_write function if you need to Chris@16: * ensure that all data is written before the blocking operation completes. Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, Chris@16: void (boost::system::error_code, std::size_t)) Chris@16: async_write_some(const ConstBufferSequence& buffers, Chris@16: BOOST_ASIO_MOVE_ARG(WriteHandler) handler) Chris@16: { Chris@16: // If you get an error on the following line it means that your handler does Chris@16: // not meet the documented type requirements for a WriteHandler. Chris@16: BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check; Chris@16: Chris@16: boost::asio::detail::async_result_init< Chris@16: WriteHandler, void (boost::system::error_code, std::size_t)> init( Chris@16: BOOST_ASIO_MOVE_CAST(WriteHandler)(handler)); Chris@16: Chris@16: detail::async_io(next_layer_, core_, Chris@16: detail::write_op(buffers), init.handler); Chris@16: Chris@16: return init.result.get(); Chris@16: } Chris@16: Chris@16: /// Read some data from the stream. Chris@16: /** Chris@16: * This function is used to read data from the stream. The function call will Chris@16: * block until one or more bytes of data has been read successfully, or until Chris@16: * an error occurs. Chris@16: * Chris@16: * @param buffers The buffers into which the data will be read. Chris@16: * Chris@16: * @returns The number of bytes read. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note The read_some operation may not read all of the requested number of Chris@16: * bytes. Consider using the @ref read function if you need to ensure that the Chris@16: * requested amount of data is read before the blocking operation completes. Chris@16: */ Chris@16: template Chris@16: std::size_t read_some(const MutableBufferSequence& buffers) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: std::size_t n = read_some(buffers, ec); Chris@16: boost::asio::detail::throw_error(ec, "read_some"); Chris@16: return n; Chris@16: } Chris@16: Chris@16: /// Read some data from the stream. Chris@16: /** Chris@16: * This function is used to read data from the stream. The function call will Chris@16: * block until one or more bytes of data has been read successfully, or until Chris@16: * an error occurs. Chris@16: * Chris@16: * @param buffers The buffers into which the data will be read. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns The number of bytes read. Returns 0 if an error occurred. Chris@16: * Chris@16: * @note The read_some operation may not read all of the requested number of Chris@16: * bytes. Consider using the @ref read function if you need to ensure that the Chris@16: * requested amount of data is read before the blocking operation completes. Chris@16: */ Chris@16: template Chris@16: std::size_t read_some(const MutableBufferSequence& buffers, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: return detail::io(next_layer_, core_, Chris@16: detail::read_op(buffers), ec); Chris@16: } Chris@16: Chris@16: /// Start an asynchronous read. Chris@16: /** Chris@16: * This function is used to asynchronously read one or more bytes of data from Chris@16: * the stream. The function call always returns immediately. Chris@16: * Chris@16: * @param buffers The buffers into which the data will be read. Although the Chris@16: * buffers object may be copied as necessary, ownership of the underlying Chris@16: * buffers is retained by the caller, which must guarantee that they remain Chris@16: * valid until the handler is called. Chris@16: * Chris@16: * @param handler The handler to be called when the read operation completes. Chris@16: * Copies will be made of the handler as required. The equivalent function Chris@16: * signature of the handler must be: Chris@16: * @code void handler( Chris@16: * const boost::system::error_code& error, // Result of operation. Chris@16: * std::size_t bytes_transferred // Number of bytes read. Chris@16: * ); @endcode Chris@16: * Chris@16: * @note The async_read_some operation may not read all of the requested Chris@16: * number of bytes. Consider using the @ref async_read function if you need to Chris@16: * ensure that the requested amount of data is read before the asynchronous Chris@16: * operation completes. Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, Chris@16: void (boost::system::error_code, std::size_t)) Chris@16: async_read_some(const MutableBufferSequence& buffers, Chris@16: BOOST_ASIO_MOVE_ARG(ReadHandler) handler) Chris@16: { Chris@16: // If you get an error on the following line it means that your handler does Chris@16: // not meet the documented type requirements for a ReadHandler. Chris@16: BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check; Chris@16: Chris@16: boost::asio::detail::async_result_init< Chris@16: ReadHandler, void (boost::system::error_code, std::size_t)> init( Chris@16: BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); Chris@16: Chris@16: detail::async_io(next_layer_, core_, Chris@16: detail::read_op(buffers), init.handler); Chris@16: Chris@16: return init.result.get(); Chris@16: } Chris@16: Chris@16: private: Chris@16: Stream next_layer_; Chris@16: detail::stream_core core_; Chris@16: impl_struct backwards_compatible_impl_; Chris@16: }; Chris@16: Chris@16: #endif // defined(BOOST_ASIO_ENABLE_OLD_SSL) Chris@16: Chris@16: } // namespace ssl Chris@16: } // namespace asio Chris@16: } // namespace boost Chris@16: Chris@16: #include Chris@16: Chris@16: #endif // BOOST_ASIO_SSL_STREAM_HPP