5 // Copyright (c) 2005 Voipster / Indrek dot Juhani at voipster dot com
6 // Copyright (c) 2005-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
8 // Distributed under the Boost Software License, Version 1.0. (See accompanying
9 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
12 #ifndef BOOST_ASIO_SSL_OLD_STREAM_HPP
13 #define BOOST_ASIO_SSL_OLD_STREAM_HPP
15 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
17 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
19 #include <boost/asio/detail/config.hpp>
21 #include <boost/noncopyable.hpp>
22 #include <boost/asio/detail/throw_error.hpp>
23 #include <boost/asio/detail/type_traits.hpp>
24 #include <boost/asio/error.hpp>
25 #include <boost/asio/ssl/basic_context.hpp>
26 #include <boost/asio/ssl/stream_base.hpp>
27 #include <boost/asio/ssl/stream_service.hpp>
29 #include <boost/asio/detail/push_options.hpp>
36 /// Provides stream-oriented functionality using SSL.
38 * The stream class template provides asynchronous and blocking stream-oriented
39 * functionality using SSL.
42 * @e Distinct @e objects: Safe.@n
43 * @e Shared @e objects: Unsafe.
46 * To use the SSL stream template with an ip::tcp::socket, you would write:
48 * boost::asio::io_service io_service;
49 * boost::asio::ssl::context context(io_service, boost::asio::ssl::context::sslv23);
50 * boost::asio::ssl::stream<boost::asio::ip::tcp::socket> sock(io_service, context);
54 * AsyncReadStream, AsyncWriteStream, Stream, SyncRead_Stream, SyncWriteStream.
56 template <typename Stream, typename Service = old::stream_service>
59 private boost::noncopyable
62 /// The type of the next layer.
63 typedef typename remove_reference<Stream>::type next_layer_type;
65 /// The type of the lowest layer.
66 typedef typename next_layer_type::lowest_layer_type lowest_layer_type;
68 /// The type of the service that will be used to provide stream operations.
69 typedef Service service_type;
71 /// The native implementation type of the stream.
72 typedef typename service_type::impl_type impl_type;
74 /// Construct a stream.
76 * This constructor creates a stream and initialises the underlying stream
79 * @param arg The argument to be passed to initialise the underlying stream.
81 * @param context The SSL context to be used for the stream.
83 template <typename Arg, typename Context_Service>
84 explicit stream(Arg& arg, basic_context<Context_Service>& context)
86 service_(boost::asio::use_service<Service>(next_layer_.get_io_service())),
87 impl_(service_.null())
89 service_.create(impl_, next_layer_, context);
95 service_.destroy(impl_, next_layer_);
98 /// Get the io_service associated with the object.
100 * This function may be used to obtain the io_service object that the stream
101 * uses to dispatch handlers for asynchronous operations.
103 * @return A reference to the io_service object that stream will use to
104 * dispatch handlers. Ownership is not transferred to the caller.
106 boost::asio::io_service& get_io_service()
108 return next_layer_.get_io_service();
111 /// Get a reference to the next layer.
113 * This function returns a reference to the next layer in a stack of stream
116 * @return A reference to the next layer in the stack of stream layers.
117 * Ownership is not transferred to the caller.
119 next_layer_type& next_layer()
124 /// Get a reference to the lowest layer.
126 * This function returns a reference to the lowest layer in a stack of
129 * @return A reference to the lowest layer in the stack of stream layers.
130 * Ownership is not transferred to the caller.
132 lowest_layer_type& lowest_layer()
134 return next_layer_.lowest_layer();
137 /// Get a const reference to the lowest layer.
139 * This function returns a const reference to the lowest layer in a stack of
142 * @return A const reference to the lowest layer in the stack of stream
143 * layers. Ownership is not transferred to the caller.
145 const lowest_layer_type& lowest_layer() const
147 return next_layer_.lowest_layer();
150 /// Get the underlying implementation in the native type.
152 * This function may be used to obtain the underlying implementation of the
153 * context. This is intended to allow access to stream functionality that is
154 * not otherwise provided.
161 /// Perform SSL handshaking.
163 * This function is used to perform SSL handshaking on the stream. The
164 * function call will block until handshaking is complete or an error occurs.
166 * @param type The type of handshaking to be performed, i.e. as a client or as
169 * @throws boost::system::system_error Thrown on failure.
171 void handshake(handshake_type type)
173 boost::system::error_code ec;
174 service_.handshake(impl_, next_layer_, type, ec);
175 boost::asio::detail::throw_error(ec);
178 /// Perform SSL handshaking.
180 * This function is used to perform SSL handshaking on the stream. The
181 * function call will block until handshaking is complete or an error occurs.
183 * @param type The type of handshaking to be performed, i.e. as a client or as
186 * @param ec Set to indicate what error occurred, if any.
188 boost::system::error_code handshake(handshake_type type,
189 boost::system::error_code& ec)
191 return service_.handshake(impl_, next_layer_, type, ec);
194 /// Start an asynchronous SSL handshake.
196 * This function is used to asynchronously perform an SSL handshake on the
197 * stream. This function call always returns immediately.
199 * @param type The type of handshaking to be performed, i.e. as a client or as
202 * @param handler The handler to be called when the handshake operation
203 * completes. Copies will be made of the handler as required. The equivalent
204 * function signature of the handler must be:
205 * @code void handler(
206 * const boost::system::error_code& error // Result of operation.
209 template <typename HandshakeHandler>
210 void async_handshake(handshake_type type, HandshakeHandler handler)
212 service_.async_handshake(impl_, next_layer_, type, handler);
215 /// Shut down SSL on the stream.
217 * This function is used to shut down SSL on the stream. The function call
218 * will block until SSL has been shut down or an error occurs.
220 * @throws boost::system::system_error Thrown on failure.
224 boost::system::error_code ec;
225 service_.shutdown(impl_, next_layer_, ec);
226 boost::asio::detail::throw_error(ec);
229 /// Shut down SSL on the stream.
231 * This function is used to shut down SSL on the stream. The function call
232 * will block until SSL has been shut down or an error occurs.
234 * @param ec Set to indicate what error occurred, if any.
236 boost::system::error_code shutdown(boost::system::error_code& ec)
238 return service_.shutdown(impl_, next_layer_, ec);
241 /// Asynchronously shut down SSL on the stream.
243 * This function is used to asynchronously shut down SSL on the stream. This
244 * function call always returns immediately.
246 * @param handler The handler to be called when the handshake operation
247 * completes. Copies will be made of the handler as required. The equivalent
248 * function signature of the handler must be:
249 * @code void handler(
250 * const boost::system::error_code& error // Result of operation.
253 template <typename ShutdownHandler>
254 void async_shutdown(ShutdownHandler handler)
256 service_.async_shutdown(impl_, next_layer_, handler);
259 /// Write some data to the stream.
261 * This function is used to write data on the stream. The function call will
262 * block until one or more bytes of data has been written successfully, or
263 * until an error occurs.
265 * @param buffers The data to be written.
267 * @returns The number of bytes written.
269 * @throws boost::system::system_error Thrown on failure.
271 * @note The write_some operation may not transmit all of the data to the
272 * peer. Consider using the @ref write function if you need to ensure that all
273 * data is written before the blocking operation completes.
275 template <typename ConstBufferSequence>
276 std::size_t write_some(const ConstBufferSequence& buffers)
278 boost::system::error_code ec;
279 std::size_t s = service_.write_some(impl_, next_layer_, buffers, ec);
280 boost::asio::detail::throw_error(ec);
284 /// Write some data to the stream.
286 * This function is used to write data on the stream. The function call will
287 * block until one or more bytes of data has been written successfully, or
288 * until an error occurs.
290 * @param buffers The data to be written to the stream.
292 * @param ec Set to indicate what error occurred, if any.
294 * @returns The number of bytes written. Returns 0 if an error occurred.
296 * @note The write_some operation may not transmit all of the data to the
297 * peer. Consider using the @ref write function if you need to ensure that all
298 * data is written before the blocking operation completes.
300 template <typename ConstBufferSequence>
301 std::size_t write_some(const ConstBufferSequence& buffers,
302 boost::system::error_code& ec)
304 return service_.write_some(impl_, next_layer_, buffers, ec);
307 /// Start an asynchronous write.
309 * This function is used to asynchronously write one or more bytes of data to
310 * the stream. The function call always returns immediately.
312 * @param buffers The data to be written to the stream. Although the buffers
313 * object may be copied as necessary, ownership of the underlying buffers is
314 * retained by the caller, which must guarantee that they remain valid until
315 * the handler is called.
317 * @param handler The handler to be called when the write operation completes.
318 * Copies will be made of the handler as required. The equivalent function
319 * signature of the handler must be:
320 * @code void handler(
321 * const boost::system::error_code& error, // Result of operation.
322 * std::size_t bytes_transferred // Number of bytes written.
325 * @note The async_write_some operation may not transmit all of the data to
326 * the peer. Consider using the @ref async_write function if you need to
327 * ensure that all data is written before the blocking operation completes.
329 template <typename ConstBufferSequence, typename WriteHandler>
330 void async_write_some(const ConstBufferSequence& buffers,
331 WriteHandler handler)
333 service_.async_write_some(impl_, next_layer_, buffers, handler);
336 /// Read some data from the stream.
338 * This function is used to read data from the stream. The function call will
339 * block until one or more bytes of data has been read successfully, or until
342 * @param buffers The buffers into which the data will be read.
344 * @returns The number of bytes read.
346 * @throws boost::system::system_error Thrown on failure.
348 * @note The read_some operation may not read all of the requested number of
349 * bytes. Consider using the @ref read function if you need to ensure that the
350 * requested amount of data is read before the blocking operation completes.
352 template <typename MutableBufferSequence>
353 std::size_t read_some(const MutableBufferSequence& buffers)
355 boost::system::error_code ec;
356 std::size_t s = service_.read_some(impl_, next_layer_, buffers, ec);
357 boost::asio::detail::throw_error(ec);
361 /// Read some data from the stream.
363 * This function is used to read data from the stream. The function call will
364 * block until one or more bytes of data has been read successfully, or until
367 * @param buffers The buffers into which the data will be read.
369 * @param ec Set to indicate what error occurred, if any.
371 * @returns The number of bytes read. Returns 0 if an error occurred.
373 * @note The read_some operation may not read all of the requested number of
374 * bytes. Consider using the @ref read function if you need to ensure that the
375 * requested amount of data is read before the blocking operation completes.
377 template <typename MutableBufferSequence>
378 std::size_t read_some(const MutableBufferSequence& buffers,
379 boost::system::error_code& ec)
381 return service_.read_some(impl_, next_layer_, buffers, ec);
384 /// Start an asynchronous read.
386 * This function is used to asynchronously read one or more bytes of data from
387 * the stream. The function call always returns immediately.
389 * @param buffers The buffers into which the data will be read. Although the
390 * buffers object may be copied as necessary, ownership of the underlying
391 * buffers is retained by the caller, which must guarantee that they remain
392 * valid until the handler is called.
394 * @param handler The handler to be called when the read operation completes.
395 * Copies will be made of the handler as required. The equivalent function
396 * signature of the handler must be:
397 * @code void handler(
398 * const boost::system::error_code& error, // Result of operation.
399 * std::size_t bytes_transferred // Number of bytes read.
402 * @note The async_read_some operation may not read all of the requested
403 * number of bytes. Consider using the @ref async_read function if you need to
404 * ensure that the requested amount of data is read before the asynchronous
405 * operation completes.
407 template <typename MutableBufferSequence, typename ReadHandler>
408 void async_read_some(const MutableBufferSequence& buffers,
411 service_.async_read_some(impl_, next_layer_, buffers, handler);
414 /// Peek at the incoming data on the stream.
416 * This function is used to peek at the incoming data on the stream, without
417 * removing it from the input queue. The function call will block until data
418 * has been read successfully or an error occurs.
420 * @param buffers The buffers into which the data will be read.
422 * @returns The number of bytes read.
424 * @throws boost::system::system_error Thrown on failure.
426 template <typename MutableBufferSequence>
427 std::size_t peek(const MutableBufferSequence& buffers)
429 boost::system::error_code ec;
430 std::size_t s = service_.peek(impl_, next_layer_, buffers, ec);
431 boost::asio::detail::throw_error(ec);
435 /// Peek at the incoming data on the stream.
437 * This function is used to peek at the incoming data on the stream, withoutxi
438 * removing it from the input queue. The function call will block until data
439 * has been read successfully or an error occurs.
441 * @param buffers The buffers into which the data will be read.
443 * @param ec Set to indicate what error occurred, if any.
445 * @returns The number of bytes read. Returns 0 if an error occurred.
447 template <typename MutableBufferSequence>
448 std::size_t peek(const MutableBufferSequence& buffers,
449 boost::system::error_code& ec)
451 return service_.peek(impl_, next_layer_, buffers, ec);
454 /// Determine the amount of data that may be read without blocking.
456 * This function is used to determine the amount of data, in bytes, that may
457 * be read from the stream without blocking.
459 * @returns The number of bytes of data that can be read without blocking.
461 * @throws boost::system::system_error Thrown on failure.
463 std::size_t in_avail()
465 boost::system::error_code ec;
466 std::size_t s = service_.in_avail(impl_, next_layer_, ec);
467 boost::asio::detail::throw_error(ec);
471 /// Determine the amount of data that may be read without blocking.
473 * This function is used to determine the amount of data, in bytes, that may
474 * be read from the stream without blocking.
476 * @param ec Set to indicate what error occurred, if any.
478 * @returns The number of bytes of data that can be read without blocking.
480 std::size_t in_avail(boost::system::error_code& ec)
482 return service_.in_avail(impl_, next_layer_, ec);
489 /// The backend service implementation.
490 service_type& service_;
492 /// The underlying native implementation.
501 #include <boost/asio/detail/pop_options.hpp>
503 #endif // BOOST_ASIO_SSL_OLD_STREAM_HPP