Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

stream.hpp 26KB

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