Chris@16: // Chris@16: // ssl/old/stream.hpp Chris@16: // ~~~~~~~~~~~~~~~~~~ Chris@16: // Chris@16: // Copyright (c) 2005 Voipster / Indrek dot Juhani at voipster dot com Chris@101: // Copyright (c) 2005-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_OLD_STREAM_HPP Chris@16: #define BOOST_ASIO_SSL_OLD_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: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: Chris@16: #include Chris@16: Chris@16: namespace boost { Chris@16: namespace asio { Chris@16: namespace ssl { Chris@16: namespace old { 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. 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 context(io_service, boost::asio::ssl::context::sslv23); Chris@16: * boost::asio::ssl::stream sock(io_service, context); Chris@16: * @endcode Chris@16: * Chris@16: * @par Concepts: Chris@16: * AsyncReadStream, AsyncWriteStream, Stream, SyncRead_Stream, SyncWriteStream. Chris@16: */ Chris@16: template Chris@16: class stream Chris@16: : public stream_base, Chris@16: private boost::noncopyable Chris@16: { Chris@16: public: 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: /// The type of the service that will be used to provide stream operations. Chris@16: typedef Service service_type; Chris@16: Chris@16: /// The native implementation type of the stream. Chris@16: typedef typename service_type::impl_type impl_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 context The SSL context to be used for the stream. Chris@16: */ Chris@16: template Chris@16: explicit stream(Arg& arg, basic_context& context) Chris@16: : next_layer_(arg), Chris@16: service_(boost::asio::use_service(next_layer_.get_io_service())), Chris@16: impl_(service_.null()) Chris@16: { Chris@16: service_.create(impl_, next_layer_, context); Chris@16: } Chris@16: Chris@16: /// Destructor. Chris@16: ~stream() Chris@16: { Chris@16: service_.destroy(impl_, next_layer_); 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_.get_io_service(); 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 const reference to the lowest layer. Chris@16: /** Chris@16: * This function returns a const reference to the lowest layer in a stack of Chris@16: * stream layers. Chris@16: * Chris@16: * @return A const reference to the lowest layer in the stack of stream Chris@16: * layers. 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: /// 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 stream functionality that is Chris@16: * not otherwise provided. Chris@16: */ Chris@16: impl_type impl() Chris@16: { Chris@16: return impl_; 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: service_.handshake(impl_, next_layer_, type, ec); Chris@16: boost::asio::detail::throw_error(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 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: return service_.handshake(impl_, next_layer_, type, 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: void async_handshake(handshake_type type, HandshakeHandler handler) Chris@16: { Chris@16: service_.async_handshake(impl_, next_layer_, type, handler); 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: service_.shutdown(impl_, next_layer_, ec); Chris@16: boost::asio::detail::throw_error(ec); 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: return service_.shutdown(impl_, next_layer_, 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: void async_shutdown(ShutdownHandler handler) Chris@16: { Chris@16: service_.async_shutdown(impl_, next_layer_, handler); 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 s = service_.write_some(impl_, next_layer_, buffers, ec); Chris@16: boost::asio::detail::throw_error(ec); Chris@16: return s; 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 service_.write_some(impl_, next_layer_, 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: void async_write_some(const ConstBufferSequence& buffers, Chris@16: WriteHandler handler) Chris@16: { Chris@16: service_.async_write_some(impl_, next_layer_, buffers, handler); 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 s = service_.read_some(impl_, next_layer_, buffers, ec); Chris@16: boost::asio::detail::throw_error(ec); Chris@16: return s; 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 service_.read_some(impl_, next_layer_, 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: void async_read_some(const MutableBufferSequence& buffers, Chris@16: ReadHandler handler) Chris@16: { Chris@16: service_.async_read_some(impl_, next_layer_, buffers, handler); Chris@16: } Chris@16: Chris@16: /// Peek at the incoming data on the stream. Chris@16: /** Chris@16: * This function is used to peek at the incoming data on the stream, without Chris@16: * removing it from the input queue. The function call will block until data Chris@16: * has been read successfully or 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: template Chris@16: std::size_t peek(const MutableBufferSequence& buffers) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: std::size_t s = service_.peek(impl_, next_layer_, buffers, ec); Chris@16: boost::asio::detail::throw_error(ec); Chris@16: return s; Chris@16: } Chris@16: Chris@16: /// Peek at the incoming data on the stream. Chris@16: /** Chris@16: * This function is used to peek at the incoming data on the stream, withoutxi Chris@16: * removing it from the input queue. The function call will block until data Chris@16: * has been read successfully or 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: template Chris@16: std::size_t peek(const MutableBufferSequence& buffers, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: return service_.peek(impl_, next_layer_, buffers, ec); Chris@16: } Chris@16: Chris@16: /// Determine the amount of data that may be read without blocking. Chris@16: /** Chris@16: * This function is used to determine the amount of data, in bytes, that may Chris@16: * be read from the stream without blocking. Chris@16: * Chris@16: * @returns The number of bytes of data that can be read without blocking. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: std::size_t in_avail() Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: std::size_t s = service_.in_avail(impl_, next_layer_, ec); Chris@16: boost::asio::detail::throw_error(ec); Chris@16: return s; Chris@16: } Chris@16: Chris@16: /// Determine the amount of data that may be read without blocking. Chris@16: /** Chris@16: * This function is used to determine the amount of data, in bytes, that may Chris@16: * be read from the stream without blocking. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns The number of bytes of data that can be read without blocking. Chris@16: */ Chris@16: std::size_t in_avail(boost::system::error_code& ec) Chris@16: { Chris@16: return service_.in_avail(impl_, next_layer_, ec); Chris@16: } Chris@16: Chris@16: private: Chris@16: /// The next layer. Chris@16: Stream next_layer_; Chris@16: Chris@16: /// The backend service implementation. Chris@16: service_type& service_; Chris@16: Chris@16: /// The underlying native implementation. Chris@16: impl_type impl_; Chris@16: }; Chris@16: Chris@16: } // namespace old 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_OLD_STREAM_HPP