stream.hpp 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789
  1. //
  2. // ssl/stream.hpp
  3. // ~~~~~~~~~~~~~~
  4. //
  5. // Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com)
  6. //
  7. // Distributed under the Boost Software License, Version 1.0. (See accompanying
  8. // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  9. //
  10. #ifndef BOOST_ASIO_SSL_STREAM_HPP
  11. #define BOOST_ASIO_SSL_STREAM_HPP
  12. #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  13. # pragma once
  14. #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  15. #include <boost/asio/detail/config.hpp>
  16. #include <boost/asio/async_result.hpp>
  17. #include <boost/asio/detail/buffer_sequence_adapter.hpp>
  18. #include <boost/asio/detail/handler_type_requirements.hpp>
  19. #include <boost/asio/detail/non_const_lvalue.hpp>
  20. #include <boost/asio/detail/noncopyable.hpp>
  21. #include <boost/asio/detail/type_traits.hpp>
  22. #include <boost/asio/ssl/context.hpp>
  23. #include <boost/asio/ssl/detail/buffered_handshake_op.hpp>
  24. #include <boost/asio/ssl/detail/handshake_op.hpp>
  25. #include <boost/asio/ssl/detail/io.hpp>
  26. #include <boost/asio/ssl/detail/read_op.hpp>
  27. #include <boost/asio/ssl/detail/shutdown_op.hpp>
  28. #include <boost/asio/ssl/detail/stream_core.hpp>
  29. #include <boost/asio/ssl/detail/write_op.hpp>
  30. #include <boost/asio/ssl/stream_base.hpp>
  31. #include <boost/asio/detail/push_options.hpp>
  32. namespace boost {
  33. namespace asio {
  34. namespace ssl {
  35. /// Provides stream-oriented functionality using SSL.
  36. /**
  37. * The stream class template provides asynchronous and blocking stream-oriented
  38. * functionality using SSL.
  39. *
  40. * @par Thread Safety
  41. * @e Distinct @e objects: Safe.@n
  42. * @e Shared @e objects: Unsafe. The application must also ensure that all
  43. * asynchronous operations are performed within the same implicit or explicit
  44. * strand.
  45. *
  46. * @par Example
  47. * To use the SSL stream template with an ip::tcp::socket, you would write:
  48. * @code
  49. * boost::asio::io_context my_context;
  50. * boost::asio::ssl::context ctx(boost::asio::ssl::context::sslv23);
  51. * boost::asio::ssl::stream<asio:ip::tcp::socket> sock(my_context, ctx);
  52. * @endcode
  53. *
  54. * @par Concepts:
  55. * AsyncReadStream, AsyncWriteStream, Stream, SyncReadStream, SyncWriteStream.
  56. */
  57. template <typename Stream>
  58. class stream :
  59. public stream_base,
  60. private noncopyable
  61. {
  62. public:
  63. /// The native handle type of the SSL stream.
  64. typedef SSL* native_handle_type;
  65. /// Structure for use with deprecated impl_type.
  66. struct impl_struct
  67. {
  68. SSL* ssl;
  69. };
  70. /// The type of the next layer.
  71. typedef typename remove_reference<Stream>::type next_layer_type;
  72. /// The type of the lowest layer.
  73. typedef typename next_layer_type::lowest_layer_type lowest_layer_type;
  74. /// The type of the executor associated with the object.
  75. typedef typename lowest_layer_type::executor_type executor_type;
  76. #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  77. /// Construct a stream.
  78. /**
  79. * This constructor creates a stream and initialises the underlying stream
  80. * object.
  81. *
  82. * @param arg The argument to be passed to initialise the underlying stream.
  83. *
  84. * @param ctx The SSL context to be used for the stream.
  85. */
  86. template <typename Arg>
  87. stream(Arg&& arg, context& ctx)
  88. : next_layer_(BOOST_ASIO_MOVE_CAST(Arg)(arg)),
  89. core_(ctx.native_handle(), next_layer_.lowest_layer().get_executor())
  90. {
  91. }
  92. #else // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  93. template <typename Arg>
  94. stream(Arg& arg, context& ctx)
  95. : next_layer_(arg),
  96. core_(ctx.native_handle(), next_layer_.lowest_layer().get_executor())
  97. {
  98. }
  99. #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  100. /// Destructor.
  101. /**
  102. * @note A @c stream object must not be destroyed while there are pending
  103. * asynchronous operations associated with it.
  104. */
  105. ~stream()
  106. {
  107. }
  108. /// Get the executor associated with the object.
  109. /**
  110. * This function may be used to obtain the executor object that the stream
  111. * uses to dispatch handlers for asynchronous operations.
  112. *
  113. * @return A copy of the executor that stream will use to dispatch handlers.
  114. */
  115. executor_type get_executor() BOOST_ASIO_NOEXCEPT
  116. {
  117. return next_layer_.lowest_layer().get_executor();
  118. }
  119. /// Get the underlying implementation in the native type.
  120. /**
  121. * This function may be used to obtain the underlying implementation of the
  122. * context. This is intended to allow access to context functionality that is
  123. * not otherwise provided.
  124. *
  125. * @par Example
  126. * The native_handle() function returns a pointer of type @c SSL* that is
  127. * suitable for passing to functions such as @c SSL_get_verify_result and
  128. * @c SSL_get_peer_certificate:
  129. * @code
  130. * boost::asio::ssl::stream<asio:ip::tcp::socket> sock(my_context, ctx);
  131. *
  132. * // ... establish connection and perform handshake ...
  133. *
  134. * if (X509* cert = SSL_get_peer_certificate(sock.native_handle()))
  135. * {
  136. * if (SSL_get_verify_result(sock.native_handle()) == X509_V_OK)
  137. * {
  138. * // ...
  139. * }
  140. * }
  141. * @endcode
  142. */
  143. native_handle_type native_handle()
  144. {
  145. return core_.engine_.native_handle();
  146. }
  147. /// Get a reference to the next layer.
  148. /**
  149. * This function returns a reference to the next layer in a stack of stream
  150. * layers.
  151. *
  152. * @return A reference to the next layer in the stack of stream layers.
  153. * Ownership is not transferred to the caller.
  154. */
  155. const next_layer_type& next_layer() const
  156. {
  157. return next_layer_;
  158. }
  159. /// Get a reference to the next layer.
  160. /**
  161. * This function returns a reference to the next layer in a stack of stream
  162. * layers.
  163. *
  164. * @return A reference to the next layer in the stack of stream layers.
  165. * Ownership is not transferred to the caller.
  166. */
  167. next_layer_type& next_layer()
  168. {
  169. return next_layer_;
  170. }
  171. /// Get a reference to the lowest layer.
  172. /**
  173. * This function returns a reference to the lowest layer in a stack of
  174. * stream layers.
  175. *
  176. * @return A reference to the lowest layer in the stack of stream layers.
  177. * Ownership is not transferred to the caller.
  178. */
  179. lowest_layer_type& lowest_layer()
  180. {
  181. return next_layer_.lowest_layer();
  182. }
  183. /// Get a reference to the lowest layer.
  184. /**
  185. * This function returns a reference to the lowest layer in a stack of
  186. * stream layers.
  187. *
  188. * @return A reference to the lowest layer in the stack of stream layers.
  189. * Ownership is not transferred to the caller.
  190. */
  191. const lowest_layer_type& lowest_layer() const
  192. {
  193. return next_layer_.lowest_layer();
  194. }
  195. /// Set the peer verification mode.
  196. /**
  197. * This function may be used to configure the peer verification mode used by
  198. * the stream. The new mode will override the mode inherited from the context.
  199. *
  200. * @param v A bitmask of peer verification modes. See @ref verify_mode for
  201. * available values.
  202. *
  203. * @throws boost::system::system_error Thrown on failure.
  204. *
  205. * @note Calls @c SSL_set_verify.
  206. */
  207. void set_verify_mode(verify_mode v)
  208. {
  209. boost::system::error_code ec;
  210. set_verify_mode(v, ec);
  211. boost::asio::detail::throw_error(ec, "set_verify_mode");
  212. }
  213. /// Set the peer verification mode.
  214. /**
  215. * This function may be used to configure the peer verification mode used by
  216. * the stream. The new mode will override the mode inherited from the context.
  217. *
  218. * @param v A bitmask of peer verification modes. See @ref verify_mode for
  219. * available values.
  220. *
  221. * @param ec Set to indicate what error occurred, if any.
  222. *
  223. * @note Calls @c SSL_set_verify.
  224. */
  225. BOOST_ASIO_SYNC_OP_VOID set_verify_mode(
  226. verify_mode v, boost::system::error_code& ec)
  227. {
  228. core_.engine_.set_verify_mode(v, ec);
  229. BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
  230. }
  231. /// Set the peer verification depth.
  232. /**
  233. * This function may be used to configure the maximum verification depth
  234. * allowed by the stream.
  235. *
  236. * @param depth Maximum depth for the certificate chain verification that
  237. * shall be allowed.
  238. *
  239. * @throws boost::system::system_error Thrown on failure.
  240. *
  241. * @note Calls @c SSL_set_verify_depth.
  242. */
  243. void set_verify_depth(int depth)
  244. {
  245. boost::system::error_code ec;
  246. set_verify_depth(depth, ec);
  247. boost::asio::detail::throw_error(ec, "set_verify_depth");
  248. }
  249. /// Set the peer verification depth.
  250. /**
  251. * This function may be used to configure the maximum verification depth
  252. * allowed by the stream.
  253. *
  254. * @param depth Maximum depth for the certificate chain verification that
  255. * shall be allowed.
  256. *
  257. * @param ec Set to indicate what error occurred, if any.
  258. *
  259. * @note Calls @c SSL_set_verify_depth.
  260. */
  261. BOOST_ASIO_SYNC_OP_VOID set_verify_depth(
  262. int depth, boost::system::error_code& ec)
  263. {
  264. core_.engine_.set_verify_depth(depth, ec);
  265. BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
  266. }
  267. /// Set the callback used to verify peer certificates.
  268. /**
  269. * This function is used to specify a callback function that will be called
  270. * by the implementation when it needs to verify a peer certificate.
  271. *
  272. * @param callback The function object to be used for verifying a certificate.
  273. * The function signature of the handler must be:
  274. * @code bool verify_callback(
  275. * bool preverified, // True if the certificate passed pre-verification.
  276. * verify_context& ctx // The peer certificate and other context.
  277. * ); @endcode
  278. * The return value of the callback is true if the certificate has passed
  279. * verification, false otherwise.
  280. *
  281. * @throws boost::system::system_error Thrown on failure.
  282. *
  283. * @note Calls @c SSL_set_verify.
  284. */
  285. template <typename VerifyCallback>
  286. void set_verify_callback(VerifyCallback callback)
  287. {
  288. boost::system::error_code ec;
  289. this->set_verify_callback(callback, ec);
  290. boost::asio::detail::throw_error(ec, "set_verify_callback");
  291. }
  292. /// Set the callback used to verify peer certificates.
  293. /**
  294. * This function is used to specify a callback function that will be called
  295. * by the implementation when it needs to verify a peer certificate.
  296. *
  297. * @param callback The function object to be used for verifying a certificate.
  298. * The function signature of the handler must be:
  299. * @code bool verify_callback(
  300. * bool preverified, // True if the certificate passed pre-verification.
  301. * verify_context& ctx // The peer certificate and other context.
  302. * ); @endcode
  303. * The return value of the callback is true if the certificate has passed
  304. * verification, false otherwise.
  305. *
  306. * @param ec Set to indicate what error occurred, if any.
  307. *
  308. * @note Calls @c SSL_set_verify.
  309. */
  310. template <typename VerifyCallback>
  311. BOOST_ASIO_SYNC_OP_VOID set_verify_callback(VerifyCallback callback,
  312. boost::system::error_code& ec)
  313. {
  314. core_.engine_.set_verify_callback(
  315. new detail::verify_callback<VerifyCallback>(callback), ec);
  316. BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
  317. }
  318. /// Perform SSL handshaking.
  319. /**
  320. * This function is used to perform SSL handshaking on the stream. The
  321. * function call will block until handshaking is complete or an error occurs.
  322. *
  323. * @param type The type of handshaking to be performed, i.e. as a client or as
  324. * a server.
  325. *
  326. * @throws boost::system::system_error Thrown on failure.
  327. */
  328. void handshake(handshake_type type)
  329. {
  330. boost::system::error_code ec;
  331. handshake(type, ec);
  332. boost::asio::detail::throw_error(ec, "handshake");
  333. }
  334. /// Perform SSL handshaking.
  335. /**
  336. * This function is used to perform SSL handshaking on the stream. The
  337. * function call will block until handshaking is complete or an error occurs.
  338. *
  339. * @param type The type of handshaking to be performed, i.e. as a client or as
  340. * a server.
  341. *
  342. * @param ec Set to indicate what error occurred, if any.
  343. */
  344. BOOST_ASIO_SYNC_OP_VOID handshake(handshake_type type,
  345. boost::system::error_code& ec)
  346. {
  347. detail::io(next_layer_, core_, detail::handshake_op(type), ec);
  348. BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
  349. }
  350. /// Perform SSL handshaking.
  351. /**
  352. * This function is used to perform SSL handshaking on the stream. The
  353. * function call will block until handshaking is complete or an error occurs.
  354. *
  355. * @param type The type of handshaking to be performed, i.e. as a client or as
  356. * a server.
  357. *
  358. * @param buffers The buffered data to be reused for the handshake.
  359. *
  360. * @throws boost::system::system_error Thrown on failure.
  361. */
  362. template <typename ConstBufferSequence>
  363. void handshake(handshake_type type, const ConstBufferSequence& buffers)
  364. {
  365. boost::system::error_code ec;
  366. handshake(type, buffers, ec);
  367. boost::asio::detail::throw_error(ec, "handshake");
  368. }
  369. /// Perform SSL handshaking.
  370. /**
  371. * This function is used to perform SSL handshaking on the stream. The
  372. * function call will block until handshaking is complete or an error occurs.
  373. *
  374. * @param type The type of handshaking to be performed, i.e. as a client or as
  375. * a server.
  376. *
  377. * @param buffers The buffered data to be reused for the handshake.
  378. *
  379. * @param ec Set to indicate what error occurred, if any.
  380. */
  381. template <typename ConstBufferSequence>
  382. BOOST_ASIO_SYNC_OP_VOID handshake(handshake_type type,
  383. const ConstBufferSequence& buffers, boost::system::error_code& ec)
  384. {
  385. detail::io(next_layer_, core_,
  386. detail::buffered_handshake_op<ConstBufferSequence>(type, buffers), ec);
  387. BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
  388. }
  389. /// Start an asynchronous SSL handshake.
  390. /**
  391. * This function is used to asynchronously perform an SSL handshake on the
  392. * stream. This function call always returns immediately.
  393. *
  394. * @param type The type of handshaking to be performed, i.e. as a client or as
  395. * a server.
  396. *
  397. * @param handler The handler to be called when the handshake operation
  398. * completes. Copies will be made of the handler as required. The equivalent
  399. * function signature of the handler must be:
  400. * @code void handler(
  401. * const boost::system::error_code& error // Result of operation.
  402. * ); @endcode
  403. */
  404. template <typename HandshakeHandler>
  405. BOOST_ASIO_INITFN_RESULT_TYPE(HandshakeHandler,
  406. void (boost::system::error_code))
  407. async_handshake(handshake_type type,
  408. BOOST_ASIO_MOVE_ARG(HandshakeHandler) handler)
  409. {
  410. return async_initiate<HandshakeHandler,
  411. void (boost::system::error_code)>(
  412. initiate_async_handshake(), handler, this, type);
  413. }
  414. /// Start an asynchronous SSL handshake.
  415. /**
  416. * This function is used to asynchronously perform an SSL handshake on the
  417. * stream. This function call always returns immediately.
  418. *
  419. * @param type The type of handshaking to be performed, i.e. as a client or as
  420. * a server.
  421. *
  422. * @param buffers The buffered data to be reused for the handshake. Although
  423. * the buffers object may be copied as necessary, ownership of the underlying
  424. * buffers is retained by the caller, which must guarantee that they remain
  425. * valid until the handler is called.
  426. *
  427. * @param handler The handler to be called when the handshake operation
  428. * completes. Copies will be made of the handler as required. The equivalent
  429. * function signature of the handler must be:
  430. * @code void handler(
  431. * const boost::system::error_code& error, // Result of operation.
  432. * std::size_t bytes_transferred // Amount of buffers used in handshake.
  433. * ); @endcode
  434. */
  435. template <typename ConstBufferSequence, typename BufferedHandshakeHandler>
  436. BOOST_ASIO_INITFN_RESULT_TYPE(BufferedHandshakeHandler,
  437. void (boost::system::error_code, std::size_t))
  438. async_handshake(handshake_type type, const ConstBufferSequence& buffers,
  439. BOOST_ASIO_MOVE_ARG(BufferedHandshakeHandler) handler)
  440. {
  441. return async_initiate<BufferedHandshakeHandler,
  442. void (boost::system::error_code, std::size_t)>(
  443. initiate_async_buffered_handshake(), handler, this, type, buffers);
  444. }
  445. /// Shut down SSL on the stream.
  446. /**
  447. * This function is used to shut down SSL on the stream. The function call
  448. * will block until SSL has been shut down or an error occurs.
  449. *
  450. * @throws boost::system::system_error Thrown on failure.
  451. */
  452. void shutdown()
  453. {
  454. boost::system::error_code ec;
  455. shutdown(ec);
  456. boost::asio::detail::throw_error(ec, "shutdown");
  457. }
  458. /// Shut down SSL on the stream.
  459. /**
  460. * This function is used to shut down SSL on the stream. The function call
  461. * will block until SSL has been shut down or an error occurs.
  462. *
  463. * @param ec Set to indicate what error occurred, if any.
  464. */
  465. BOOST_ASIO_SYNC_OP_VOID shutdown(boost::system::error_code& ec)
  466. {
  467. detail::io(next_layer_, core_, detail::shutdown_op(), ec);
  468. BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
  469. }
  470. /// Asynchronously shut down SSL on the stream.
  471. /**
  472. * This function is used to asynchronously shut down SSL on the stream. This
  473. * function call always returns immediately.
  474. *
  475. * @param handler The handler to be called when the handshake operation
  476. * completes. Copies will be made of the handler as required. The equivalent
  477. * function signature of the handler must be:
  478. * @code void handler(
  479. * const boost::system::error_code& error // Result of operation.
  480. * ); @endcode
  481. */
  482. template <typename ShutdownHandler>
  483. BOOST_ASIO_INITFN_RESULT_TYPE(ShutdownHandler,
  484. void (boost::system::error_code))
  485. async_shutdown(BOOST_ASIO_MOVE_ARG(ShutdownHandler) handler)
  486. {
  487. return async_initiate<ShutdownHandler,
  488. void (boost::system::error_code)>(
  489. initiate_async_shutdown(), handler, this);
  490. }
  491. /// Write some data to the stream.
  492. /**
  493. * This function is used to write data on the stream. The function call will
  494. * block until one or more bytes of data has been written successfully, or
  495. * until an error occurs.
  496. *
  497. * @param buffers The data to be written.
  498. *
  499. * @returns The number of bytes written.
  500. *
  501. * @throws boost::system::system_error Thrown on failure.
  502. *
  503. * @note The write_some operation may not transmit all of the data to the
  504. * peer. Consider using the @ref write function if you need to ensure that all
  505. * data is written before the blocking operation completes.
  506. */
  507. template <typename ConstBufferSequence>
  508. std::size_t write_some(const ConstBufferSequence& buffers)
  509. {
  510. boost::system::error_code ec;
  511. std::size_t n = write_some(buffers, ec);
  512. boost::asio::detail::throw_error(ec, "write_some");
  513. return n;
  514. }
  515. /// Write some data to the stream.
  516. /**
  517. * This function is used to write data on the stream. The function call will
  518. * block until one or more bytes of data has been written successfully, or
  519. * until an error occurs.
  520. *
  521. * @param buffers The data to be written to the stream.
  522. *
  523. * @param ec Set to indicate what error occurred, if any.
  524. *
  525. * @returns The number of bytes written. Returns 0 if an error occurred.
  526. *
  527. * @note The write_some operation may not transmit all of the data to the
  528. * peer. Consider using the @ref write function if you need to ensure that all
  529. * data is written before the blocking operation completes.
  530. */
  531. template <typename ConstBufferSequence>
  532. std::size_t write_some(const ConstBufferSequence& buffers,
  533. boost::system::error_code& ec)
  534. {
  535. return detail::io(next_layer_, core_,
  536. detail::write_op<ConstBufferSequence>(buffers), ec);
  537. }
  538. /// Start an asynchronous write.
  539. /**
  540. * This function is used to asynchronously write one or more bytes of data to
  541. * the stream. The function call always returns immediately.
  542. *
  543. * @param buffers The data to be written to the stream. Although the buffers
  544. * object may be copied as necessary, ownership of the underlying buffers is
  545. * retained by the caller, which must guarantee that they remain valid until
  546. * the handler is called.
  547. *
  548. * @param handler The handler to be called when the write operation completes.
  549. * Copies will be made of the handler as required. The equivalent function
  550. * signature of the handler must be:
  551. * @code void handler(
  552. * const boost::system::error_code& error, // Result of operation.
  553. * std::size_t bytes_transferred // Number of bytes written.
  554. * ); @endcode
  555. *
  556. * @note The async_write_some operation may not transmit all of the data to
  557. * the peer. Consider using the @ref async_write function if you need to
  558. * ensure that all data is written before the asynchronous operation
  559. * completes.
  560. */
  561. template <typename ConstBufferSequence, typename WriteHandler>
  562. BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
  563. void (boost::system::error_code, std::size_t))
  564. async_write_some(const ConstBufferSequence& buffers,
  565. BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
  566. {
  567. return async_initiate<WriteHandler,
  568. void (boost::system::error_code, std::size_t)>(
  569. initiate_async_write_some(), handler, this, buffers);
  570. }
  571. /// Read some data from the stream.
  572. /**
  573. * This function is used to read data from the stream. The function call will
  574. * block until one or more bytes of data has been read successfully, or until
  575. * an error occurs.
  576. *
  577. * @param buffers The buffers into which the data will be read.
  578. *
  579. * @returns The number of bytes read.
  580. *
  581. * @throws boost::system::system_error Thrown on failure.
  582. *
  583. * @note The read_some operation may not read all of the requested number of
  584. * bytes. Consider using the @ref read function if you need to ensure that the
  585. * requested amount of data is read before the blocking operation completes.
  586. */
  587. template <typename MutableBufferSequence>
  588. std::size_t read_some(const MutableBufferSequence& buffers)
  589. {
  590. boost::system::error_code ec;
  591. std::size_t n = read_some(buffers, ec);
  592. boost::asio::detail::throw_error(ec, "read_some");
  593. return n;
  594. }
  595. /// Read some data from the stream.
  596. /**
  597. * This function is used to read data from the stream. The function call will
  598. * block until one or more bytes of data has been read successfully, or until
  599. * an error occurs.
  600. *
  601. * @param buffers The buffers into which the data will be read.
  602. *
  603. * @param ec Set to indicate what error occurred, if any.
  604. *
  605. * @returns The number of bytes read. Returns 0 if an error occurred.
  606. *
  607. * @note The read_some operation may not read all of the requested number of
  608. * bytes. Consider using the @ref read function if you need to ensure that the
  609. * requested amount of data is read before the blocking operation completes.
  610. */
  611. template <typename MutableBufferSequence>
  612. std::size_t read_some(const MutableBufferSequence& buffers,
  613. boost::system::error_code& ec)
  614. {
  615. return detail::io(next_layer_, core_,
  616. detail::read_op<MutableBufferSequence>(buffers), ec);
  617. }
  618. /// Start an asynchronous read.
  619. /**
  620. * This function is used to asynchronously read one or more bytes of data from
  621. * the stream. The function call always returns immediately.
  622. *
  623. * @param buffers The buffers into which the data will be read. Although the
  624. * buffers object may be copied as necessary, ownership of the underlying
  625. * buffers is retained by the caller, which must guarantee that they remain
  626. * valid until the handler is called.
  627. *
  628. * @param handler The handler to be called when the read operation completes.
  629. * Copies will be made of the handler as required. The equivalent function
  630. * signature of the handler must be:
  631. * @code void handler(
  632. * const boost::system::error_code& error, // Result of operation.
  633. * std::size_t bytes_transferred // Number of bytes read.
  634. * ); @endcode
  635. *
  636. * @note The async_read_some operation may not read all of the requested
  637. * number of bytes. Consider using the @ref async_read function if you need to
  638. * ensure that the requested amount of data is read before the asynchronous
  639. * operation completes.
  640. */
  641. template <typename MutableBufferSequence, typename ReadHandler>
  642. BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
  643. void (boost::system::error_code, std::size_t))
  644. async_read_some(const MutableBufferSequence& buffers,
  645. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  646. {
  647. return async_initiate<ReadHandler,
  648. void (boost::system::error_code, std::size_t)>(
  649. initiate_async_read_some(), handler, this, buffers);
  650. }
  651. private:
  652. struct initiate_async_handshake
  653. {
  654. template <typename HandshakeHandler>
  655. void operator()(BOOST_ASIO_MOVE_ARG(HandshakeHandler) handler,
  656. stream* self, handshake_type type) const
  657. {
  658. // If you get an error on the following line it means that your handler
  659. // does not meet the documented type requirements for a HandshakeHandler.
  660. BOOST_ASIO_HANDSHAKE_HANDLER_CHECK(HandshakeHandler, handler) type_check;
  661. boost::asio::detail::non_const_lvalue<HandshakeHandler> handler2(handler);
  662. detail::async_io(self->next_layer_, self->core_,
  663. detail::handshake_op(type), handler2.value);
  664. }
  665. };
  666. struct initiate_async_buffered_handshake
  667. {
  668. template <typename BufferedHandshakeHandler, typename ConstBufferSequence>
  669. void operator()(BOOST_ASIO_MOVE_ARG(BufferedHandshakeHandler) handler,
  670. stream* self, handshake_type type,
  671. const ConstBufferSequence& buffers) const
  672. {
  673. // If you get an error on the following line it means that your
  674. // handler does not meet the documented type requirements for a
  675. // BufferedHandshakeHandler.
  676. BOOST_ASIO_BUFFERED_HANDSHAKE_HANDLER_CHECK(
  677. BufferedHandshakeHandler, handler) type_check;
  678. boost::asio::detail::non_const_lvalue<
  679. BufferedHandshakeHandler> handler2(handler);
  680. detail::async_io(self->next_layer_, self->core_,
  681. detail::buffered_handshake_op<ConstBufferSequence>(type, buffers),
  682. handler2.value);
  683. }
  684. };
  685. struct initiate_async_shutdown
  686. {
  687. template <typename ShutdownHandler>
  688. void operator()(BOOST_ASIO_MOVE_ARG(ShutdownHandler) handler,
  689. stream* self) const
  690. {
  691. // If you get an error on the following line it means that your handler
  692. // does not meet the documented type requirements for a ShutdownHandler.
  693. BOOST_ASIO_HANDSHAKE_HANDLER_CHECK(ShutdownHandler, handler) type_check;
  694. boost::asio::detail::non_const_lvalue<ShutdownHandler> handler2(handler);
  695. detail::async_io(self->next_layer_, self->core_,
  696. detail::shutdown_op(), handler2.value);
  697. }
  698. };
  699. struct initiate_async_write_some
  700. {
  701. template <typename WriteHandler, typename ConstBufferSequence>
  702. void operator()(BOOST_ASIO_MOVE_ARG(WriteHandler) handler,
  703. stream* self, const ConstBufferSequence& buffers) const
  704. {
  705. // If you get an error on the following line it means that your handler
  706. // does not meet the documented type requirements for a WriteHandler.
  707. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  708. boost::asio::detail::non_const_lvalue<WriteHandler> handler2(handler);
  709. detail::async_io(self->next_layer_, self->core_,
  710. detail::write_op<ConstBufferSequence>(buffers), handler2.value);
  711. }
  712. };
  713. struct initiate_async_read_some
  714. {
  715. template <typename ReadHandler, typename MutableBufferSequence>
  716. void operator()(BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
  717. stream* self, const MutableBufferSequence& buffers) const
  718. {
  719. // If you get an error on the following line it means that your handler
  720. // does not meet the documented type requirements for a ReadHandler.
  721. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  722. boost::asio::detail::non_const_lvalue<ReadHandler> handler2(handler);
  723. detail::async_io(self->next_layer_, self->core_,
  724. detail::read_op<MutableBufferSequence>(buffers), handler2.value);
  725. }
  726. };
  727. Stream next_layer_;
  728. detail::stream_core core_;
  729. };
  730. } // namespace ssl
  731. } // namespace asio
  732. } // namespace boost
  733. #include <boost/asio/detail/pop_options.hpp>
  734. #endif // BOOST_ASIO_SSL_STREAM_HPP