boost/asio/basic_socket_iostream.hpp

0001 //
0002 // basic_socket_iostream.hpp
0003 // ~~~~~~~~~~~~~~~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2025 Christopher M. Kohlhoff (chris at kohlhoff dot com)
0006 //
0007 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0008 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0009 //
0010
0011 #ifndef BOOST_ASIO_BASIC_SOCKET_IOSTREAM_HPP
0012 #define BOOST_ASIO_BASIC_SOCKET_IOSTREAM_HPP
0013
0014 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
0015 # pragma once
0016 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
0017
0018 #include <boost/asio/detail/config.hpp>
0019
0020 #if !defined(BOOST_ASIO_NO_IOSTREAM)
0021
0022 #include <istream>
0023 #include <ostream>
0024 #include <boost/asio/basic_socket_streambuf.hpp>
0025
0026 #include <boost/asio/detail/push_options.hpp>
0027
0028 namespace boost {
0029 namespace asio {
0030 namespace detail {
0031
0032 // A separate base class is used to ensure that the streambuf is initialised
0033 // prior to the basic_socket_iostream's basic_iostream base class.
0034 template <typename Protocol, typename Clock, typename WaitTraits>
0035 class socket_iostream_base
0036 {
0037 protected:
0038   socket_iostream_base()
0039   {
0040   }
0041
0042   socket_iostream_base(socket_iostream_base&& other)
0043     : streambuf_(std::move(other.streambuf_))
0044   {
0045   }
0046
0047   socket_iostream_base(basic_stream_socket<Protocol> s)
0048     : streambuf_(std::move(s))
0049   {
0050   }
0051
0052   socket_iostream_base& operator=(socket_iostream_base&& other)
0053   {
0054     streambuf_ = std::move(other.streambuf_);
0055     return *this;
0056   }
0057
0058   basic_socket_streambuf<Protocol, Clock, WaitTraits> streambuf_;
0059 };
0060
0061 } // namespace detail
0062
0063 #if !defined(BOOST_ASIO_BASIC_SOCKET_IOSTREAM_FWD_DECL)
0064 #define BOOST_ASIO_BASIC_SOCKET_IOSTREAM_FWD_DECL
0065
0066 // Forward declaration with defaulted arguments.
0067 template <typename Protocol,
0068     typename Clock = chrono::steady_clock,
0069     typename WaitTraits = wait_traits<Clock>>
0070 class basic_socket_iostream;
0071
0072 #endif // !defined(BOOST_ASIO_BASIC_SOCKET_IOSTREAM_FWD_DECL)
0073
0074 /// Iostream interface for a socket.
0075 #if defined(GENERATING_DOCUMENTATION)
0076 template <typename Protocol,
0077     typename Clock = chrono::steady_clock,
0078     typename WaitTraits = wait_traits<Clock>>
0079 #else // defined(GENERATING_DOCUMENTATION)
0080 template <typename Protocol, typename Clock, typename WaitTraits>
0081 #endif // defined(GENERATING_DOCUMENTATION)
0082 class basic_socket_iostream
0083   : private detail::socket_iostream_base<Protocol, Clock, WaitTraits>,
0084     public std::basic_iostream<char>
0085 {
0086 private:
0087   typedef detail::chrono_time_traits<Clock, WaitTraits> traits_helper;
0088
0089 public:
0090   /// The protocol type.
0091   typedef Protocol protocol_type;
0092
0093   /// The endpoint type.
0094   typedef typename Protocol::endpoint endpoint_type;
0095
0096   /// The clock type.
0097   typedef Clock clock_type;
0098
0099 #if defined(GENERATING_DOCUMENTATION)
0100   /// The time type.
0101   typedef typename WaitTraits::time_point time_point;
0102
0103   /// The duration type.
0104   typedef typename WaitTraits::duration duration;
0105 #else
0106   typedef typename traits_helper::time_type time_point;
0107   typedef typename traits_helper::duration_type duration;
0108 #endif
0109
0110   /// Construct a basic_socket_iostream without establishing a connection.
0111   basic_socket_iostream()
0112     : std::basic_iostream<char>(
0113         &this->detail::socket_iostream_base<
0114           Protocol, Clock, WaitTraits>::streambuf_)
0115   {
0116     this->setf(std::ios_base::unitbuf);
0117   }
0118
0119   /// Construct a basic_socket_iostream from the supplied socket.
0120   explicit basic_socket_iostream(basic_stream_socket<protocol_type> s)
0121     : detail::socket_iostream_base<
0122         Protocol, Clock, WaitTraits>(std::move(s)),
0123       std::basic_iostream<char>(
0124         &this->detail::socket_iostream_base<
0125           Protocol, Clock, WaitTraits>::streambuf_)
0126   {
0127     this->setf(std::ios_base::unitbuf);
0128   }
0129
0130   /// Move-construct a basic_socket_iostream from another.
0131   basic_socket_iostream(basic_socket_iostream&& other)
0132     : detail::socket_iostream_base<
0133         Protocol, Clock, WaitTraits>(std::move(other)),
0134       std::basic_iostream<char>(std::move(other))
0135   {
0136     this->set_rdbuf(&this->detail::socket_iostream_base<
0137           Protocol, Clock, WaitTraits>::streambuf_);
0138   }
0139
0140   /// Move-assign a basic_socket_iostream from another.
0141   basic_socket_iostream& operator=(basic_socket_iostream&& other)
0142   {
0143     std::basic_iostream<char>::operator=(std::move(other));
0144     detail::socket_iostream_base<
0145         Protocol, Clock, WaitTraits>::operator=(std::move(other));
0146     return *this;
0147   }
0148
0149   /// Establish a connection to an endpoint corresponding to a resolver query.
0150   /**
0151    * This constructor automatically establishes a connection based on the
0152    * supplied resolver query parameters. The arguments are used to construct
0153    * a resolver query object.
0154    */
0155   template <typename... T>
0156   explicit basic_socket_iostream(T... x)
0157     : std::basic_iostream<char>(
0158         &this->detail::socket_iostream_base<
0159           Protocol, Clock, WaitTraits>::streambuf_)
0160   {
0161     this->setf(std::ios_base::unitbuf);
0162     if (rdbuf()->connect(x...) == 0)
0163       this->setstate(std::ios_base::failbit);
0164   }
0165
0166   /// Establish a connection to an endpoint corresponding to a resolver query.
0167   /**
0168    * This function automatically establishes a connection based on the supplied
0169    * resolver query parameters. The arguments are used to construct a resolver
0170    * query object.
0171    */
0172   template <typename... T>
0173   void connect(T... x)
0174   {
0175     if (rdbuf()->connect(x...) == 0)
0176       this->setstate(std::ios_base::failbit);
0177   }
0178
0179   /// Close the connection.
0180   void close()
0181   {
0182     if (rdbuf()->close() == 0)
0183       this->setstate(std::ios_base::failbit);
0184   }
0185
0186   /// Return a pointer to the underlying streambuf.
0187   basic_socket_streambuf<Protocol, Clock, WaitTraits>* rdbuf() const
0188   {
0189     return const_cast<basic_socket_streambuf<Protocol, Clock, WaitTraits>*>(
0190         &this->detail::socket_iostream_base<
0191           Protocol, Clock, WaitTraits>::streambuf_);
0192   }
0193
0194   /// Get a reference to the underlying socket.
0195   basic_socket<Protocol>& socket()
0196   {
0197     return rdbuf()->socket();
0198   }
0199
0200   /// Get the last error associated with the stream.
0201   /**
0202    * @return An \c error_code corresponding to the last error from the stream.
0203    *
0204    * @par Example
0205    * To print the error associated with a failure to establish a connection:
0206    * @code tcp::iostream s("www.boost.org", "http");
0207    * if (!s)
0208    * {
0209    *   std::cout << "Error: " << s.error().message() << std::endl;
0210    * } @endcode
0211    */
0212   const boost::system::error_code& error() const
0213   {
0214     return rdbuf()->error();
0215   }
0216
0217   /// Get the stream's expiry time as an absolute time.
0218   /**
0219    * @return An absolute time value representing the stream's expiry time.
0220    */
0221   time_point expiry() const
0222   {
0223     return rdbuf()->expiry();
0224   }
0225
0226   /// Set the stream's expiry time as an absolute time.
0227   /**
0228    * This function sets the expiry time associated with the stream. Stream
0229    * operations performed after this time (where the operations cannot be
0230    * completed using the internal buffers) will fail with the error
0231    * boost::asio::error::operation_aborted.
0232    *
0233    * @param expiry_time The expiry time to be used for the stream.
0234    */
0235   void expires_at(const time_point& expiry_time)
0236   {
0237     rdbuf()->expires_at(expiry_time);
0238   }
0239
0240   /// Set the stream's expiry time relative to now.
0241   /**
0242    * This function sets the expiry time associated with the stream. Stream
0243    * operations performed after this time (where the operations cannot be
0244    * completed using the internal buffers) will fail with the error
0245    * boost::asio::error::operation_aborted.
0246    *
0247    * @param expiry_time The expiry time to be used for the timer.
0248    */
0249   void expires_after(const duration& expiry_time)
0250   {
0251     rdbuf()->expires_after(expiry_time);
0252   }
0253
0254 private:
0255   // Disallow copying and assignment.
0256   basic_socket_iostream(const basic_socket_iostream&) = delete;
0257   basic_socket_iostream& operator=(
0258       const basic_socket_iostream&) = delete;
0259 };
0260
0261 } // namespace asio
0262 } // namespace boost
0263
0264 #include <boost/asio/detail/pop_options.hpp>
0265
0266 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
0267
0268 #endif // BOOST_ASIO_BASIC_SOCKET_IOSTREAM_HPP