Statistics
| Revision:

root / tmp / org.txm.statsengine.r.core.win32 / res / win32 / library / BH / include / boost / asio / basic_socket.hpp @ 2486

History | View | Annotate | Download (51.6 kB)

1 2486 sjacqu01
//
2 2486 sjacqu01
// basic_socket.hpp
3 2486 sjacqu01
// ~~~~~~~~~~~~~~~~
4 2486 sjacqu01
//
5 2486 sjacqu01
// Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6 2486 sjacqu01
//
7 2486 sjacqu01
// Distributed under the Boost Software License, Version 1.0. (See accompanying
8 2486 sjacqu01
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9 2486 sjacqu01
//
10 2486 sjacqu01
11 2486 sjacqu01
#ifndef BOOST_ASIO_BASIC_SOCKET_HPP
12 2486 sjacqu01
#define BOOST_ASIO_BASIC_SOCKET_HPP
13 2486 sjacqu01
14 2486 sjacqu01
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15 2486 sjacqu01
# pragma once
16 2486 sjacqu01
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17 2486 sjacqu01
18 2486 sjacqu01
#include <boost/asio/detail/config.hpp>
19 2486 sjacqu01
#include <boost/asio/async_result.hpp>
20 2486 sjacqu01
#include <boost/asio/basic_io_object.hpp>
21 2486 sjacqu01
#include <boost/asio/detail/handler_type_requirements.hpp>
22 2486 sjacqu01
#include <boost/asio/detail/throw_error.hpp>
23 2486 sjacqu01
#include <boost/asio/detail/type_traits.hpp>
24 2486 sjacqu01
#include <boost/asio/error.hpp>
25 2486 sjacqu01
#include <boost/asio/socket_base.hpp>
26 2486 sjacqu01
27 2486 sjacqu01
#include <boost/asio/detail/push_options.hpp>
28 2486 sjacqu01
29 2486 sjacqu01
namespace boost {
30 2486 sjacqu01
namespace asio {
31 2486 sjacqu01
32 2486 sjacqu01
/// Provides socket functionality.
33 2486 sjacqu01
/**
34 2486 sjacqu01
 * The basic_socket class template provides functionality that is common to both
35 2486 sjacqu01
 * stream-oriented and datagram-oriented sockets.
36 2486 sjacqu01
 *
37 2486 sjacqu01
 * @par Thread Safety
38 2486 sjacqu01
 * @e Distinct @e objects: Safe.@n
39 2486 sjacqu01
 * @e Shared @e objects: Unsafe.
40 2486 sjacqu01
 */
41 2486 sjacqu01
template <typename Protocol, typename SocketService>
42 2486 sjacqu01
class basic_socket
43 2486 sjacqu01
  : public basic_io_object<SocketService>,
44 2486 sjacqu01
    public socket_base
45 2486 sjacqu01
{
46 2486 sjacqu01
public:
47 2486 sjacqu01
  /// (Deprecated: Use native_handle_type.) The native representation of a
48 2486 sjacqu01
  /// socket.
49 2486 sjacqu01
  typedef typename SocketService::native_handle_type native_type;
50 2486 sjacqu01
51 2486 sjacqu01
  /// The native representation of a socket.
52 2486 sjacqu01
  typedef typename SocketService::native_handle_type native_handle_type;
53 2486 sjacqu01
54 2486 sjacqu01
  /// The protocol type.
55 2486 sjacqu01
  typedef Protocol protocol_type;
56 2486 sjacqu01
57 2486 sjacqu01
  /// The endpoint type.
58 2486 sjacqu01
  typedef typename Protocol::endpoint endpoint_type;
59 2486 sjacqu01
60 2486 sjacqu01
  /// A basic_socket is always the lowest layer.
61 2486 sjacqu01
  typedef basic_socket<Protocol, SocketService> lowest_layer_type;
62 2486 sjacqu01
63 2486 sjacqu01
  /// Construct a basic_socket without opening it.
64 2486 sjacqu01
  /**
65 2486 sjacqu01
   * This constructor creates a socket without opening it.
66 2486 sjacqu01
   *
67 2486 sjacqu01
   * @param io_service The io_service object that the socket will use to
68 2486 sjacqu01
   * dispatch handlers for any asynchronous operations performed on the socket.
69 2486 sjacqu01
   */
70 2486 sjacqu01
  explicit basic_socket(boost::asio::io_service& io_service)
71 2486 sjacqu01
    : basic_io_object<SocketService>(io_service)
72 2486 sjacqu01
  {
73 2486 sjacqu01
  }
74 2486 sjacqu01
75 2486 sjacqu01
  /// Construct and open a basic_socket.
76 2486 sjacqu01
  /**
77 2486 sjacqu01
   * This constructor creates and opens a socket.
78 2486 sjacqu01
   *
79 2486 sjacqu01
   * @param io_service The io_service object that the socket will use to
80 2486 sjacqu01
   * dispatch handlers for any asynchronous operations performed on the socket.
81 2486 sjacqu01
   *
82 2486 sjacqu01
   * @param protocol An object specifying protocol parameters to be used.
83 2486 sjacqu01
   *
84 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
85 2486 sjacqu01
   */
86 2486 sjacqu01
  basic_socket(boost::asio::io_service& io_service,
87 2486 sjacqu01
      const protocol_type& protocol)
88 2486 sjacqu01
    : basic_io_object<SocketService>(io_service)
89 2486 sjacqu01
  {
90 2486 sjacqu01
    boost::system::error_code ec;
91 2486 sjacqu01
    this->get_service().open(this->get_implementation(), protocol, ec);
92 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "open");
93 2486 sjacqu01
  }
94 2486 sjacqu01
95 2486 sjacqu01
  /// Construct a basic_socket, opening it and binding it to the given local
96 2486 sjacqu01
  /// endpoint.
97 2486 sjacqu01
  /**
98 2486 sjacqu01
   * This constructor creates a socket and automatically opens it bound to the
99 2486 sjacqu01
   * specified endpoint on the local machine. The protocol used is the protocol
100 2486 sjacqu01
   * associated with the given endpoint.
101 2486 sjacqu01
   *
102 2486 sjacqu01
   * @param io_service The io_service object that the socket will use to
103 2486 sjacqu01
   * dispatch handlers for any asynchronous operations performed on the socket.
104 2486 sjacqu01
   *
105 2486 sjacqu01
   * @param endpoint An endpoint on the local machine to which the socket will
106 2486 sjacqu01
   * be bound.
107 2486 sjacqu01
   *
108 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
109 2486 sjacqu01
   */
110 2486 sjacqu01
  basic_socket(boost::asio::io_service& io_service,
111 2486 sjacqu01
      const endpoint_type& endpoint)
112 2486 sjacqu01
    : basic_io_object<SocketService>(io_service)
113 2486 sjacqu01
  {
114 2486 sjacqu01
    boost::system::error_code ec;
115 2486 sjacqu01
    const protocol_type protocol = endpoint.protocol();
116 2486 sjacqu01
    this->get_service().open(this->get_implementation(), protocol, ec);
117 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "open");
118 2486 sjacqu01
    this->get_service().bind(this->get_implementation(), endpoint, ec);
119 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "bind");
120 2486 sjacqu01
  }
121 2486 sjacqu01
122 2486 sjacqu01
  /// Construct a basic_socket on an existing native socket.
123 2486 sjacqu01
  /**
124 2486 sjacqu01
   * This constructor creates a socket object to hold an existing native socket.
125 2486 sjacqu01
   *
126 2486 sjacqu01
   * @param io_service The io_service object that the socket will use to
127 2486 sjacqu01
   * dispatch handlers for any asynchronous operations performed on the socket.
128 2486 sjacqu01
   *
129 2486 sjacqu01
   * @param protocol An object specifying protocol parameters to be used.
130 2486 sjacqu01
   *
131 2486 sjacqu01
   * @param native_socket A native socket.
132 2486 sjacqu01
   *
133 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
134 2486 sjacqu01
   */
135 2486 sjacqu01
  basic_socket(boost::asio::io_service& io_service,
136 2486 sjacqu01
      const protocol_type& protocol, const native_handle_type& native_socket)
137 2486 sjacqu01
    : basic_io_object<SocketService>(io_service)
138 2486 sjacqu01
  {
139 2486 sjacqu01
    boost::system::error_code ec;
140 2486 sjacqu01
    this->get_service().assign(this->get_implementation(),
141 2486 sjacqu01
        protocol, native_socket, ec);
142 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "assign");
143 2486 sjacqu01
  }
144 2486 sjacqu01
145 2486 sjacqu01
#if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
146 2486 sjacqu01
  /// Move-construct a basic_socket from another.
147 2486 sjacqu01
  /**
148 2486 sjacqu01
   * This constructor moves a socket from one object to another.
149 2486 sjacqu01
   *
150 2486 sjacqu01
   * @param other The other basic_socket object from which the move will
151 2486 sjacqu01
   * occur.
152 2486 sjacqu01
   *
153 2486 sjacqu01
   * @note Following the move, the moved-from object is in the same state as if
154 2486 sjacqu01
   * constructed using the @c basic_socket(io_service&) constructor.
155 2486 sjacqu01
   */
156 2486 sjacqu01
  basic_socket(basic_socket&& other)
157 2486 sjacqu01
    : basic_io_object<SocketService>(
158 2486 sjacqu01
        BOOST_ASIO_MOVE_CAST(basic_socket)(other))
159 2486 sjacqu01
  {
160 2486 sjacqu01
  }
161 2486 sjacqu01
162 2486 sjacqu01
  /// Move-assign a basic_socket from another.
163 2486 sjacqu01
  /**
164 2486 sjacqu01
   * This assignment operator moves a socket from one object to another.
165 2486 sjacqu01
   *
166 2486 sjacqu01
   * @param other The other basic_socket object from which the move will
167 2486 sjacqu01
   * occur.
168 2486 sjacqu01
   *
169 2486 sjacqu01
   * @note Following the move, the moved-from object is in the same state as if
170 2486 sjacqu01
   * constructed using the @c basic_socket(io_service&) constructor.
171 2486 sjacqu01
   */
172 2486 sjacqu01
  basic_socket& operator=(basic_socket&& other)
173 2486 sjacqu01
  {
174 2486 sjacqu01
    basic_io_object<SocketService>::operator=(
175 2486 sjacqu01
        BOOST_ASIO_MOVE_CAST(basic_socket)(other));
176 2486 sjacqu01
    return *this;
177 2486 sjacqu01
  }
178 2486 sjacqu01
179 2486 sjacqu01
  // All sockets have access to each other's implementations.
180 2486 sjacqu01
  template <typename Protocol1, typename SocketService1>
181 2486 sjacqu01
  friend class basic_socket;
182 2486 sjacqu01
183 2486 sjacqu01
  /// Move-construct a basic_socket from a socket of another protocol type.
184 2486 sjacqu01
  /**
185 2486 sjacqu01
   * This constructor moves a socket from one object to another.
186 2486 sjacqu01
   *
187 2486 sjacqu01
   * @param other The other basic_socket object from which the move will
188 2486 sjacqu01
   * occur.
189 2486 sjacqu01
   *
190 2486 sjacqu01
   * @note Following the move, the moved-from object is in the same state as if
191 2486 sjacqu01
   * constructed using the @c basic_socket(io_service&) constructor.
192 2486 sjacqu01
   */
193 2486 sjacqu01
  template <typename Protocol1, typename SocketService1>
194 2486 sjacqu01
  basic_socket(basic_socket<Protocol1, SocketService1>&& other,
195 2486 sjacqu01
      typename enable_if<is_convertible<Protocol1, Protocol>::value>::type* = 0)
196 2486 sjacqu01
    : basic_io_object<SocketService>(other.get_io_service())
197 2486 sjacqu01
  {
198 2486 sjacqu01
    this->get_service().template converting_move_construct<Protocol1>(
199 2486 sjacqu01
        this->get_implementation(), other.get_implementation());
200 2486 sjacqu01
  }
201 2486 sjacqu01
202 2486 sjacqu01
  /// Move-assign a basic_socket from a socket of another protocol type.
203 2486 sjacqu01
  /**
204 2486 sjacqu01
   * This assignment operator moves a socket from one object to another.
205 2486 sjacqu01
   *
206 2486 sjacqu01
   * @param other The other basic_socket object from which the move will
207 2486 sjacqu01
   * occur.
208 2486 sjacqu01
   *
209 2486 sjacqu01
   * @note Following the move, the moved-from object is in the same state as if
210 2486 sjacqu01
   * constructed using the @c basic_socket(io_service&) constructor.
211 2486 sjacqu01
   */
212 2486 sjacqu01
  template <typename Protocol1, typename SocketService1>
213 2486 sjacqu01
  typename enable_if<is_convertible<Protocol1, Protocol>::value,
214 2486 sjacqu01
      basic_socket>::type& operator=(
215 2486 sjacqu01
        basic_socket<Protocol1, SocketService1>&& other)
216 2486 sjacqu01
  {
217 2486 sjacqu01
    basic_socket tmp(BOOST_ASIO_MOVE_CAST2(basic_socket<
218 2486 sjacqu01
            Protocol1, SocketService1>)(other));
219 2486 sjacqu01
    basic_io_object<SocketService>::operator=(
220 2486 sjacqu01
        BOOST_ASIO_MOVE_CAST(basic_socket)(tmp));
221 2486 sjacqu01
    return *this;
222 2486 sjacqu01
  }
223 2486 sjacqu01
#endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
224 2486 sjacqu01
225 2486 sjacqu01
  /// Get a reference to the lowest layer.
226 2486 sjacqu01
  /**
227 2486 sjacqu01
   * This function returns a reference to the lowest layer in a stack of
228 2486 sjacqu01
   * layers. Since a basic_socket cannot contain any further layers, it simply
229 2486 sjacqu01
   * returns a reference to itself.
230 2486 sjacqu01
   *
231 2486 sjacqu01
   * @return A reference to the lowest layer in the stack of layers. Ownership
232 2486 sjacqu01
   * is not transferred to the caller.
233 2486 sjacqu01
   */
234 2486 sjacqu01
  lowest_layer_type& lowest_layer()
235 2486 sjacqu01
  {
236 2486 sjacqu01
    return *this;
237 2486 sjacqu01
  }
238 2486 sjacqu01
239 2486 sjacqu01
  /// Get a const reference to the lowest layer.
240 2486 sjacqu01
  /**
241 2486 sjacqu01
   * This function returns a const reference to the lowest layer in a stack of
242 2486 sjacqu01
   * layers. Since a basic_socket cannot contain any further layers, it simply
243 2486 sjacqu01
   * returns a reference to itself.
244 2486 sjacqu01
   *
245 2486 sjacqu01
   * @return A const reference to the lowest layer in the stack of layers.
246 2486 sjacqu01
   * Ownership is not transferred to the caller.
247 2486 sjacqu01
   */
248 2486 sjacqu01
  const lowest_layer_type& lowest_layer() const
249 2486 sjacqu01
  {
250 2486 sjacqu01
    return *this;
251 2486 sjacqu01
  }
252 2486 sjacqu01
253 2486 sjacqu01
  /// Open the socket using the specified protocol.
254 2486 sjacqu01
  /**
255 2486 sjacqu01
   * This function opens the socket so that it will use the specified protocol.
256 2486 sjacqu01
   *
257 2486 sjacqu01
   * @param protocol An object specifying protocol parameters to be used.
258 2486 sjacqu01
   *
259 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
260 2486 sjacqu01
   *
261 2486 sjacqu01
   * @par Example
262 2486 sjacqu01
   * @code
263 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
264 2486 sjacqu01
   * socket.open(boost::asio::ip::tcp::v4());
265 2486 sjacqu01
   * @endcode
266 2486 sjacqu01
   */
267 2486 sjacqu01
  void open(const protocol_type& protocol = protocol_type())
268 2486 sjacqu01
  {
269 2486 sjacqu01
    boost::system::error_code ec;
270 2486 sjacqu01
    this->get_service().open(this->get_implementation(), protocol, ec);
271 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "open");
272 2486 sjacqu01
  }
273 2486 sjacqu01
274 2486 sjacqu01
  /// Open the socket using the specified protocol.
275 2486 sjacqu01
  /**
276 2486 sjacqu01
   * This function opens the socket so that it will use the specified protocol.
277 2486 sjacqu01
   *
278 2486 sjacqu01
   * @param protocol An object specifying which protocol is to be used.
279 2486 sjacqu01
   *
280 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
281 2486 sjacqu01
   *
282 2486 sjacqu01
   * @par Example
283 2486 sjacqu01
   * @code
284 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
285 2486 sjacqu01
   * boost::system::error_code ec;
286 2486 sjacqu01
   * socket.open(boost::asio::ip::tcp::v4(), ec);
287 2486 sjacqu01
   * if (ec)
288 2486 sjacqu01
   * {
289 2486 sjacqu01
   *   // An error occurred.
290 2486 sjacqu01
   * }
291 2486 sjacqu01
   * @endcode
292 2486 sjacqu01
   */
293 2486 sjacqu01
  boost::system::error_code open(const protocol_type& protocol,
294 2486 sjacqu01
      boost::system::error_code& ec)
295 2486 sjacqu01
  {
296 2486 sjacqu01
    return this->get_service().open(this->get_implementation(), protocol, ec);
297 2486 sjacqu01
  }
298 2486 sjacqu01
299 2486 sjacqu01
  /// Assign an existing native socket to the socket.
300 2486 sjacqu01
  /*
301 2486 sjacqu01
   * This function opens the socket to hold an existing native socket.
302 2486 sjacqu01
   *
303 2486 sjacqu01
   * @param protocol An object specifying which protocol is to be used.
304 2486 sjacqu01
   *
305 2486 sjacqu01
   * @param native_socket A native socket.
306 2486 sjacqu01
   *
307 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
308 2486 sjacqu01
   */
309 2486 sjacqu01
  void assign(const protocol_type& protocol,
310 2486 sjacqu01
      const native_handle_type& native_socket)
311 2486 sjacqu01
  {
312 2486 sjacqu01
    boost::system::error_code ec;
313 2486 sjacqu01
    this->get_service().assign(this->get_implementation(),
314 2486 sjacqu01
        protocol, native_socket, ec);
315 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "assign");
316 2486 sjacqu01
  }
317 2486 sjacqu01
318 2486 sjacqu01
  /// Assign an existing native socket to the socket.
319 2486 sjacqu01
  /*
320 2486 sjacqu01
   * This function opens the socket to hold an existing native socket.
321 2486 sjacqu01
   *
322 2486 sjacqu01
   * @param protocol An object specifying which protocol is to be used.
323 2486 sjacqu01
   *
324 2486 sjacqu01
   * @param native_socket A native socket.
325 2486 sjacqu01
   *
326 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
327 2486 sjacqu01
   */
328 2486 sjacqu01
  boost::system::error_code assign(const protocol_type& protocol,
329 2486 sjacqu01
      const native_handle_type& native_socket, boost::system::error_code& ec)
330 2486 sjacqu01
  {
331 2486 sjacqu01
    return this->get_service().assign(this->get_implementation(),
332 2486 sjacqu01
        protocol, native_socket, ec);
333 2486 sjacqu01
  }
334 2486 sjacqu01
335 2486 sjacqu01
  /// Determine whether the socket is open.
336 2486 sjacqu01
  bool is_open() const
337 2486 sjacqu01
  {
338 2486 sjacqu01
    return this->get_service().is_open(this->get_implementation());
339 2486 sjacqu01
  }
340 2486 sjacqu01
341 2486 sjacqu01
  /// Close the socket.
342 2486 sjacqu01
  /**
343 2486 sjacqu01
   * This function is used to close the socket. Any asynchronous send, receive
344 2486 sjacqu01
   * or connect operations will be cancelled immediately, and will complete
345 2486 sjacqu01
   * with the boost::asio::error::operation_aborted error.
346 2486 sjacqu01
   *
347 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure. Note that, even if
348 2486 sjacqu01
   * the function indicates an error, the underlying descriptor is closed.
349 2486 sjacqu01
   *
350 2486 sjacqu01
   * @note For portable behaviour with respect to graceful closure of a
351 2486 sjacqu01
   * connected socket, call shutdown() before closing the socket.
352 2486 sjacqu01
   */
353 2486 sjacqu01
  void close()
354 2486 sjacqu01
  {
355 2486 sjacqu01
    boost::system::error_code ec;
356 2486 sjacqu01
    this->get_service().close(this->get_implementation(), ec);
357 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "close");
358 2486 sjacqu01
  }
359 2486 sjacqu01
360 2486 sjacqu01
  /// Close the socket.
361 2486 sjacqu01
  /**
362 2486 sjacqu01
   * This function is used to close the socket. Any asynchronous send, receive
363 2486 sjacqu01
   * or connect operations will be cancelled immediately, and will complete
364 2486 sjacqu01
   * with the boost::asio::error::operation_aborted error.
365 2486 sjacqu01
   *
366 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any. Note that, even if
367 2486 sjacqu01
   * the function indicates an error, the underlying descriptor is closed.
368 2486 sjacqu01
   *
369 2486 sjacqu01
   * @par Example
370 2486 sjacqu01
   * @code
371 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
372 2486 sjacqu01
   * ...
373 2486 sjacqu01
   * boost::system::error_code ec;
374 2486 sjacqu01
   * socket.close(ec);
375 2486 sjacqu01
   * if (ec)
376 2486 sjacqu01
   * {
377 2486 sjacqu01
   *   // An error occurred.
378 2486 sjacqu01
   * }
379 2486 sjacqu01
   * @endcode
380 2486 sjacqu01
   *
381 2486 sjacqu01
   * @note For portable behaviour with respect to graceful closure of a
382 2486 sjacqu01
   * connected socket, call shutdown() before closing the socket.
383 2486 sjacqu01
   */
384 2486 sjacqu01
  boost::system::error_code close(boost::system::error_code& ec)
385 2486 sjacqu01
  {
386 2486 sjacqu01
    return this->get_service().close(this->get_implementation(), ec);
387 2486 sjacqu01
  }
388 2486 sjacqu01
389 2486 sjacqu01
  /// (Deprecated: Use native_handle().) Get the native socket representation.
390 2486 sjacqu01
  /**
391 2486 sjacqu01
   * This function may be used to obtain the underlying representation of the
392 2486 sjacqu01
   * socket. This is intended to allow access to native socket functionality
393 2486 sjacqu01
   * that is not otherwise provided.
394 2486 sjacqu01
   */
395 2486 sjacqu01
  native_type native()
396 2486 sjacqu01
  {
397 2486 sjacqu01
    return this->get_service().native_handle(this->get_implementation());
398 2486 sjacqu01
  }
399 2486 sjacqu01
400 2486 sjacqu01
  /// Get the native socket representation.
401 2486 sjacqu01
  /**
402 2486 sjacqu01
   * This function may be used to obtain the underlying representation of the
403 2486 sjacqu01
   * socket. This is intended to allow access to native socket functionality
404 2486 sjacqu01
   * that is not otherwise provided.
405 2486 sjacqu01
   */
406 2486 sjacqu01
  native_handle_type native_handle()
407 2486 sjacqu01
  {
408 2486 sjacqu01
    return this->get_service().native_handle(this->get_implementation());
409 2486 sjacqu01
  }
410 2486 sjacqu01
411 2486 sjacqu01
  /// Cancel all asynchronous operations associated with the socket.
412 2486 sjacqu01
  /**
413 2486 sjacqu01
   * This function causes all outstanding asynchronous connect, send and receive
414 2486 sjacqu01
   * operations to finish immediately, and the handlers for cancelled operations
415 2486 sjacqu01
   * will be passed the boost::asio::error::operation_aborted error.
416 2486 sjacqu01
   *
417 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
418 2486 sjacqu01
   *
419 2486 sjacqu01
   * @note Calls to cancel() will always fail with
420 2486 sjacqu01
   * boost::asio::error::operation_not_supported when run on Windows XP, Windows
421 2486 sjacqu01
   * Server 2003, and earlier versions of Windows, unless
422 2486 sjacqu01
   * BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has
423 2486 sjacqu01
   * two issues that should be considered before enabling its use:
424 2486 sjacqu01
   *
425 2486 sjacqu01
   * @li It will only cancel asynchronous operations that were initiated in the
426 2486 sjacqu01
   * current thread.
427 2486 sjacqu01
   *
428 2486 sjacqu01
   * @li It can appear to complete without error, but the request to cancel the
429 2486 sjacqu01
   * unfinished operations may be silently ignored by the operating system.
430 2486 sjacqu01
   * Whether it works or not seems to depend on the drivers that are installed.
431 2486 sjacqu01
   *
432 2486 sjacqu01
   * For portable cancellation, consider using one of the following
433 2486 sjacqu01
   * alternatives:
434 2486 sjacqu01
   *
435 2486 sjacqu01
   * @li Disable asio's I/O completion port backend by defining
436 2486 sjacqu01
   * BOOST_ASIO_DISABLE_IOCP.
437 2486 sjacqu01
   *
438 2486 sjacqu01
   * @li Use the close() function to simultaneously cancel the outstanding
439 2486 sjacqu01
   * operations and close the socket.
440 2486 sjacqu01
   *
441 2486 sjacqu01
   * When running on Windows Vista, Windows Server 2008, and later, the
442 2486 sjacqu01
   * CancelIoEx function is always used. This function does not have the
443 2486 sjacqu01
   * problems described above.
444 2486 sjacqu01
   */
445 2486 sjacqu01
#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
446 2486 sjacqu01
  && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \
447 2486 sjacqu01
  && !defined(BOOST_ASIO_ENABLE_CANCELIO)
448 2486 sjacqu01
  __declspec(deprecated("By default, this function always fails with "
449 2486 sjacqu01
        "operation_not_supported when used on Windows XP, Windows Server 2003, "
450 2486 sjacqu01
        "or earlier. Consult documentation for details."))
451 2486 sjacqu01
#endif
452 2486 sjacqu01
  void cancel()
453 2486 sjacqu01
  {
454 2486 sjacqu01
    boost::system::error_code ec;
455 2486 sjacqu01
    this->get_service().cancel(this->get_implementation(), ec);
456 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "cancel");
457 2486 sjacqu01
  }
458 2486 sjacqu01
459 2486 sjacqu01
  /// Cancel all asynchronous operations associated with the socket.
460 2486 sjacqu01
  /**
461 2486 sjacqu01
   * This function causes all outstanding asynchronous connect, send and receive
462 2486 sjacqu01
   * operations to finish immediately, and the handlers for cancelled operations
463 2486 sjacqu01
   * will be passed the boost::asio::error::operation_aborted error.
464 2486 sjacqu01
   *
465 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
466 2486 sjacqu01
   *
467 2486 sjacqu01
   * @note Calls to cancel() will always fail with
468 2486 sjacqu01
   * boost::asio::error::operation_not_supported when run on Windows XP, Windows
469 2486 sjacqu01
   * Server 2003, and earlier versions of Windows, unless
470 2486 sjacqu01
   * BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has
471 2486 sjacqu01
   * two issues that should be considered before enabling its use:
472 2486 sjacqu01
   *
473 2486 sjacqu01
   * @li It will only cancel asynchronous operations that were initiated in the
474 2486 sjacqu01
   * current thread.
475 2486 sjacqu01
   *
476 2486 sjacqu01
   * @li It can appear to complete without error, but the request to cancel the
477 2486 sjacqu01
   * unfinished operations may be silently ignored by the operating system.
478 2486 sjacqu01
   * Whether it works or not seems to depend on the drivers that are installed.
479 2486 sjacqu01
   *
480 2486 sjacqu01
   * For portable cancellation, consider using one of the following
481 2486 sjacqu01
   * alternatives:
482 2486 sjacqu01
   *
483 2486 sjacqu01
   * @li Disable asio's I/O completion port backend by defining
484 2486 sjacqu01
   * BOOST_ASIO_DISABLE_IOCP.
485 2486 sjacqu01
   *
486 2486 sjacqu01
   * @li Use the close() function to simultaneously cancel the outstanding
487 2486 sjacqu01
   * operations and close the socket.
488 2486 sjacqu01
   *
489 2486 sjacqu01
   * When running on Windows Vista, Windows Server 2008, and later, the
490 2486 sjacqu01
   * CancelIoEx function is always used. This function does not have the
491 2486 sjacqu01
   * problems described above.
492 2486 sjacqu01
   */
493 2486 sjacqu01
#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
494 2486 sjacqu01
  && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \
495 2486 sjacqu01
  && !defined(BOOST_ASIO_ENABLE_CANCELIO)
496 2486 sjacqu01
  __declspec(deprecated("By default, this function always fails with "
497 2486 sjacqu01
        "operation_not_supported when used on Windows XP, Windows Server 2003, "
498 2486 sjacqu01
        "or earlier. Consult documentation for details."))
499 2486 sjacqu01
#endif
500 2486 sjacqu01
  boost::system::error_code cancel(boost::system::error_code& ec)
501 2486 sjacqu01
  {
502 2486 sjacqu01
    return this->get_service().cancel(this->get_implementation(), ec);
503 2486 sjacqu01
  }
504 2486 sjacqu01
505 2486 sjacqu01
  /// Determine whether the socket is at the out-of-band data mark.
506 2486 sjacqu01
  /**
507 2486 sjacqu01
   * This function is used to check whether the socket input is currently
508 2486 sjacqu01
   * positioned at the out-of-band data mark.
509 2486 sjacqu01
   *
510 2486 sjacqu01
   * @return A bool indicating whether the socket is at the out-of-band data
511 2486 sjacqu01
   * mark.
512 2486 sjacqu01
   *
513 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
514 2486 sjacqu01
   */
515 2486 sjacqu01
  bool at_mark() const
516 2486 sjacqu01
  {
517 2486 sjacqu01
    boost::system::error_code ec;
518 2486 sjacqu01
    bool b = this->get_service().at_mark(this->get_implementation(), ec);
519 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "at_mark");
520 2486 sjacqu01
    return b;
521 2486 sjacqu01
  }
522 2486 sjacqu01
523 2486 sjacqu01
  /// Determine whether the socket is at the out-of-band data mark.
524 2486 sjacqu01
  /**
525 2486 sjacqu01
   * This function is used to check whether the socket input is currently
526 2486 sjacqu01
   * positioned at the out-of-band data mark.
527 2486 sjacqu01
   *
528 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
529 2486 sjacqu01
   *
530 2486 sjacqu01
   * @return A bool indicating whether the socket is at the out-of-band data
531 2486 sjacqu01
   * mark.
532 2486 sjacqu01
   */
533 2486 sjacqu01
  bool at_mark(boost::system::error_code& ec) const
534 2486 sjacqu01
  {
535 2486 sjacqu01
    return this->get_service().at_mark(this->get_implementation(), ec);
536 2486 sjacqu01
  }
537 2486 sjacqu01
538 2486 sjacqu01
  /// Determine the number of bytes available for reading.
539 2486 sjacqu01
  /**
540 2486 sjacqu01
   * This function is used to determine the number of bytes that may be read
541 2486 sjacqu01
   * without blocking.
542 2486 sjacqu01
   *
543 2486 sjacqu01
   * @return The number of bytes that may be read without blocking, or 0 if an
544 2486 sjacqu01
   * error occurs.
545 2486 sjacqu01
   *
546 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
547 2486 sjacqu01
   */
548 2486 sjacqu01
  std::size_t available() const
549 2486 sjacqu01
  {
550 2486 sjacqu01
    boost::system::error_code ec;
551 2486 sjacqu01
    std::size_t s = this->get_service().available(
552 2486 sjacqu01
        this->get_implementation(), ec);
553 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "available");
554 2486 sjacqu01
    return s;
555 2486 sjacqu01
  }
556 2486 sjacqu01
557 2486 sjacqu01
  /// Determine the number of bytes available for reading.
558 2486 sjacqu01
  /**
559 2486 sjacqu01
   * This function is used to determine the number of bytes that may be read
560 2486 sjacqu01
   * without blocking.
561 2486 sjacqu01
   *
562 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
563 2486 sjacqu01
   *
564 2486 sjacqu01
   * @return The number of bytes that may be read without blocking, or 0 if an
565 2486 sjacqu01
   * error occurs.
566 2486 sjacqu01
   */
567 2486 sjacqu01
  std::size_t available(boost::system::error_code& ec) const
568 2486 sjacqu01
  {
569 2486 sjacqu01
    return this->get_service().available(this->get_implementation(), ec);
570 2486 sjacqu01
  }
571 2486 sjacqu01
572 2486 sjacqu01
  /// Bind the socket to the given local endpoint.
573 2486 sjacqu01
  /**
574 2486 sjacqu01
   * This function binds the socket to the specified endpoint on the local
575 2486 sjacqu01
   * machine.
576 2486 sjacqu01
   *
577 2486 sjacqu01
   * @param endpoint An endpoint on the local machine to which the socket will
578 2486 sjacqu01
   * be bound.
579 2486 sjacqu01
   *
580 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
581 2486 sjacqu01
   *
582 2486 sjacqu01
   * @par Example
583 2486 sjacqu01
   * @code
584 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
585 2486 sjacqu01
   * socket.open(boost::asio::ip::tcp::v4());
586 2486 sjacqu01
   * socket.bind(boost::asio::ip::tcp::endpoint(
587 2486 sjacqu01
   *       boost::asio::ip::tcp::v4(), 12345));
588 2486 sjacqu01
   * @endcode
589 2486 sjacqu01
   */
590 2486 sjacqu01
  void bind(const endpoint_type& endpoint)
591 2486 sjacqu01
  {
592 2486 sjacqu01
    boost::system::error_code ec;
593 2486 sjacqu01
    this->get_service().bind(this->get_implementation(), endpoint, ec);
594 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "bind");
595 2486 sjacqu01
  }
596 2486 sjacqu01
597 2486 sjacqu01
  /// Bind the socket to the given local endpoint.
598 2486 sjacqu01
  /**
599 2486 sjacqu01
   * This function binds the socket to the specified endpoint on the local
600 2486 sjacqu01
   * machine.
601 2486 sjacqu01
   *
602 2486 sjacqu01
   * @param endpoint An endpoint on the local machine to which the socket will
603 2486 sjacqu01
   * be bound.
604 2486 sjacqu01
   *
605 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
606 2486 sjacqu01
   *
607 2486 sjacqu01
   * @par Example
608 2486 sjacqu01
   * @code
609 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
610 2486 sjacqu01
   * socket.open(boost::asio::ip::tcp::v4());
611 2486 sjacqu01
   * boost::system::error_code ec;
612 2486 sjacqu01
   * socket.bind(boost::asio::ip::tcp::endpoint(
613 2486 sjacqu01
   *       boost::asio::ip::tcp::v4(), 12345), ec);
614 2486 sjacqu01
   * if (ec)
615 2486 sjacqu01
   * {
616 2486 sjacqu01
   *   // An error occurred.
617 2486 sjacqu01
   * }
618 2486 sjacqu01
   * @endcode
619 2486 sjacqu01
   */
620 2486 sjacqu01
  boost::system::error_code bind(const endpoint_type& endpoint,
621 2486 sjacqu01
      boost::system::error_code& ec)
622 2486 sjacqu01
  {
623 2486 sjacqu01
    return this->get_service().bind(this->get_implementation(), endpoint, ec);
624 2486 sjacqu01
  }
625 2486 sjacqu01
626 2486 sjacqu01
  /// Connect the socket to the specified endpoint.
627 2486 sjacqu01
  /**
628 2486 sjacqu01
   * This function is used to connect a socket to the specified remote endpoint.
629 2486 sjacqu01
   * The function call will block until the connection is successfully made or
630 2486 sjacqu01
   * an error occurs.
631 2486 sjacqu01
   *
632 2486 sjacqu01
   * The socket is automatically opened if it is not already open. If the
633 2486 sjacqu01
   * connect fails, and the socket was automatically opened, the socket is
634 2486 sjacqu01
   * not returned to the closed state.
635 2486 sjacqu01
   *
636 2486 sjacqu01
   * @param peer_endpoint The remote endpoint to which the socket will be
637 2486 sjacqu01
   * connected.
638 2486 sjacqu01
   *
639 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
640 2486 sjacqu01
   *
641 2486 sjacqu01
   * @par Example
642 2486 sjacqu01
   * @code
643 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
644 2486 sjacqu01
   * boost::asio::ip::tcp::endpoint endpoint(
645 2486 sjacqu01
   *     boost::asio::ip::address::from_string("1.2.3.4"), 12345);
646 2486 sjacqu01
   * socket.connect(endpoint);
647 2486 sjacqu01
   * @endcode
648 2486 sjacqu01
   */
649 2486 sjacqu01
  void connect(const endpoint_type& peer_endpoint)
650 2486 sjacqu01
  {
651 2486 sjacqu01
    boost::system::error_code ec;
652 2486 sjacqu01
    if (!is_open())
653 2486 sjacqu01
    {
654 2486 sjacqu01
      this->get_service().open(this->get_implementation(),
655 2486 sjacqu01
          peer_endpoint.protocol(), ec);
656 2486 sjacqu01
      boost::asio::detail::throw_error(ec, "connect");
657 2486 sjacqu01
    }
658 2486 sjacqu01
    this->get_service().connect(this->get_implementation(), peer_endpoint, ec);
659 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "connect");
660 2486 sjacqu01
  }
661 2486 sjacqu01
662 2486 sjacqu01
  /// Connect the socket to the specified endpoint.
663 2486 sjacqu01
  /**
664 2486 sjacqu01
   * This function is used to connect a socket to the specified remote endpoint.
665 2486 sjacqu01
   * The function call will block until the connection is successfully made or
666 2486 sjacqu01
   * an error occurs.
667 2486 sjacqu01
   *
668 2486 sjacqu01
   * The socket is automatically opened if it is not already open. If the
669 2486 sjacqu01
   * connect fails, and the socket was automatically opened, the socket is
670 2486 sjacqu01
   * not returned to the closed state.
671 2486 sjacqu01
   *
672 2486 sjacqu01
   * @param peer_endpoint The remote endpoint to which the socket will be
673 2486 sjacqu01
   * connected.
674 2486 sjacqu01
   *
675 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
676 2486 sjacqu01
   *
677 2486 sjacqu01
   * @par Example
678 2486 sjacqu01
   * @code
679 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
680 2486 sjacqu01
   * boost::asio::ip::tcp::endpoint endpoint(
681 2486 sjacqu01
   *     boost::asio::ip::address::from_string("1.2.3.4"), 12345);
682 2486 sjacqu01
   * boost::system::error_code ec;
683 2486 sjacqu01
   * socket.connect(endpoint, ec);
684 2486 sjacqu01
   * if (ec)
685 2486 sjacqu01
   * {
686 2486 sjacqu01
   *   // An error occurred.
687 2486 sjacqu01
   * }
688 2486 sjacqu01
   * @endcode
689 2486 sjacqu01
   */
690 2486 sjacqu01
  boost::system::error_code connect(const endpoint_type& peer_endpoint,
691 2486 sjacqu01
      boost::system::error_code& ec)
692 2486 sjacqu01
  {
693 2486 sjacqu01
    if (!is_open())
694 2486 sjacqu01
    {
695 2486 sjacqu01
      if (this->get_service().open(this->get_implementation(),
696 2486 sjacqu01
            peer_endpoint.protocol(), ec))
697 2486 sjacqu01
      {
698 2486 sjacqu01
        return ec;
699 2486 sjacqu01
      }
700 2486 sjacqu01
    }
701 2486 sjacqu01
702 2486 sjacqu01
    return this->get_service().connect(
703 2486 sjacqu01
        this->get_implementation(), peer_endpoint, ec);
704 2486 sjacqu01
  }
705 2486 sjacqu01
706 2486 sjacqu01
  /// Start an asynchronous connect.
707 2486 sjacqu01
  /**
708 2486 sjacqu01
   * This function is used to asynchronously connect a socket to the specified
709 2486 sjacqu01
   * remote endpoint. The function call always returns immediately.
710 2486 sjacqu01
   *
711 2486 sjacqu01
   * The socket is automatically opened if it is not already open. If the
712 2486 sjacqu01
   * connect fails, and the socket was automatically opened, the socket is
713 2486 sjacqu01
   * not returned to the closed state.
714 2486 sjacqu01
   *
715 2486 sjacqu01
   * @param peer_endpoint The remote endpoint to which the socket will be
716 2486 sjacqu01
   * connected. Copies will be made of the endpoint object as required.
717 2486 sjacqu01
   *
718 2486 sjacqu01
   * @param handler The handler to be called when the connection operation
719 2486 sjacqu01
   * completes. Copies will be made of the handler as required. The function
720 2486 sjacqu01
   * signature of the handler must be:
721 2486 sjacqu01
   * @code void handler(
722 2486 sjacqu01
   *   const boost::system::error_code& error // Result of operation
723 2486 sjacqu01
   * ); @endcode
724 2486 sjacqu01
   * Regardless of whether the asynchronous operation completes immediately or
725 2486 sjacqu01
   * not, the handler will not be invoked from within this function. Invocation
726 2486 sjacqu01
   * of the handler will be performed in a manner equivalent to using
727 2486 sjacqu01
   * boost::asio::io_service::post().
728 2486 sjacqu01
   *
729 2486 sjacqu01
   * @par Example
730 2486 sjacqu01
   * @code
731 2486 sjacqu01
   * void connect_handler(const boost::system::error_code& error)
732 2486 sjacqu01
   * {
733 2486 sjacqu01
   *   if (!error)
734 2486 sjacqu01
   *   {
735 2486 sjacqu01
   *     // Connect succeeded.
736 2486 sjacqu01
   *   }
737 2486 sjacqu01
   * }
738 2486 sjacqu01
   *
739 2486 sjacqu01
   * ...
740 2486 sjacqu01
   *
741 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
742 2486 sjacqu01
   * boost::asio::ip::tcp::endpoint endpoint(
743 2486 sjacqu01
   *     boost::asio::ip::address::from_string("1.2.3.4"), 12345);
744 2486 sjacqu01
   * socket.async_connect(endpoint, connect_handler);
745 2486 sjacqu01
   * @endcode
746 2486 sjacqu01
   */
747 2486 sjacqu01
  template <typename ConnectHandler>
748 2486 sjacqu01
  BOOST_ASIO_INITFN_RESULT_TYPE(ConnectHandler,
749 2486 sjacqu01
      void (boost::system::error_code))
750 2486 sjacqu01
  async_connect(const endpoint_type& peer_endpoint,
751 2486 sjacqu01
      BOOST_ASIO_MOVE_ARG(ConnectHandler) handler)
752 2486 sjacqu01
  {
753 2486 sjacqu01
    // If you get an error on the following line it means that your handler does
754 2486 sjacqu01
    // not meet the documented type requirements for a ConnectHandler.
755 2486 sjacqu01
    BOOST_ASIO_CONNECT_HANDLER_CHECK(ConnectHandler, handler) type_check;
756 2486 sjacqu01
757 2486 sjacqu01
    if (!is_open())
758 2486 sjacqu01
    {
759 2486 sjacqu01
      boost::system::error_code ec;
760 2486 sjacqu01
      const protocol_type protocol = peer_endpoint.protocol();
761 2486 sjacqu01
      if (this->get_service().open(this->get_implementation(), protocol, ec))
762 2486 sjacqu01
      {
763 2486 sjacqu01
        detail::async_result_init<
764 2486 sjacqu01
          ConnectHandler, void (boost::system::error_code)> init(
765 2486 sjacqu01
            BOOST_ASIO_MOVE_CAST(ConnectHandler)(handler));
766 2486 sjacqu01
767 2486 sjacqu01
        this->get_io_service().post(
768 2486 sjacqu01
            boost::asio::detail::bind_handler(
769 2486 sjacqu01
              BOOST_ASIO_MOVE_CAST(BOOST_ASIO_HANDLER_TYPE(
770 2486 sjacqu01
                ConnectHandler, void (boost::system::error_code)))(
771 2486 sjacqu01
                  init.handler), ec));
772 2486 sjacqu01
773 2486 sjacqu01
        return init.result.get();
774 2486 sjacqu01
      }
775 2486 sjacqu01
    }
776 2486 sjacqu01
777 2486 sjacqu01
    return this->get_service().async_connect(this->get_implementation(),
778 2486 sjacqu01
        peer_endpoint, BOOST_ASIO_MOVE_CAST(ConnectHandler)(handler));
779 2486 sjacqu01
  }
780 2486 sjacqu01
781 2486 sjacqu01
  /// Set an option on the socket.
782 2486 sjacqu01
  /**
783 2486 sjacqu01
   * This function is used to set an option on the socket.
784 2486 sjacqu01
   *
785 2486 sjacqu01
   * @param option The new option value to be set on the socket.
786 2486 sjacqu01
   *
787 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
788 2486 sjacqu01
   *
789 2486 sjacqu01
   * @sa SettableSocketOption @n
790 2486 sjacqu01
   * boost::asio::socket_base::broadcast @n
791 2486 sjacqu01
   * boost::asio::socket_base::do_not_route @n
792 2486 sjacqu01
   * boost::asio::socket_base::keep_alive @n
793 2486 sjacqu01
   * boost::asio::socket_base::linger @n
794 2486 sjacqu01
   * boost::asio::socket_base::receive_buffer_size @n
795 2486 sjacqu01
   * boost::asio::socket_base::receive_low_watermark @n
796 2486 sjacqu01
   * boost::asio::socket_base::reuse_address @n
797 2486 sjacqu01
   * boost::asio::socket_base::send_buffer_size @n
798 2486 sjacqu01
   * boost::asio::socket_base::send_low_watermark @n
799 2486 sjacqu01
   * boost::asio::ip::multicast::join_group @n
800 2486 sjacqu01
   * boost::asio::ip::multicast::leave_group @n
801 2486 sjacqu01
   * boost::asio::ip::multicast::enable_loopback @n
802 2486 sjacqu01
   * boost::asio::ip::multicast::outbound_interface @n
803 2486 sjacqu01
   * boost::asio::ip::multicast::hops @n
804 2486 sjacqu01
   * boost::asio::ip::tcp::no_delay
805 2486 sjacqu01
   *
806 2486 sjacqu01
   * @par Example
807 2486 sjacqu01
   * Setting the IPPROTO_TCP/TCP_NODELAY option:
808 2486 sjacqu01
   * @code
809 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
810 2486 sjacqu01
   * ...
811 2486 sjacqu01
   * boost::asio::ip::tcp::no_delay option(true);
812 2486 sjacqu01
   * socket.set_option(option);
813 2486 sjacqu01
   * @endcode
814 2486 sjacqu01
   */
815 2486 sjacqu01
  template <typename SettableSocketOption>
816 2486 sjacqu01
  void set_option(const SettableSocketOption& option)
817 2486 sjacqu01
  {
818 2486 sjacqu01
    boost::system::error_code ec;
819 2486 sjacqu01
    this->get_service().set_option(this->get_implementation(), option, ec);
820 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "set_option");
821 2486 sjacqu01
  }
822 2486 sjacqu01
823 2486 sjacqu01
  /// Set an option on the socket.
824 2486 sjacqu01
  /**
825 2486 sjacqu01
   * This function is used to set an option on the socket.
826 2486 sjacqu01
   *
827 2486 sjacqu01
   * @param option The new option value to be set on the socket.
828 2486 sjacqu01
   *
829 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
830 2486 sjacqu01
   *
831 2486 sjacqu01
   * @sa SettableSocketOption @n
832 2486 sjacqu01
   * boost::asio::socket_base::broadcast @n
833 2486 sjacqu01
   * boost::asio::socket_base::do_not_route @n
834 2486 sjacqu01
   * boost::asio::socket_base::keep_alive @n
835 2486 sjacqu01
   * boost::asio::socket_base::linger @n
836 2486 sjacqu01
   * boost::asio::socket_base::receive_buffer_size @n
837 2486 sjacqu01
   * boost::asio::socket_base::receive_low_watermark @n
838 2486 sjacqu01
   * boost::asio::socket_base::reuse_address @n
839 2486 sjacqu01
   * boost::asio::socket_base::send_buffer_size @n
840 2486 sjacqu01
   * boost::asio::socket_base::send_low_watermark @n
841 2486 sjacqu01
   * boost::asio::ip::multicast::join_group @n
842 2486 sjacqu01
   * boost::asio::ip::multicast::leave_group @n
843 2486 sjacqu01
   * boost::asio::ip::multicast::enable_loopback @n
844 2486 sjacqu01
   * boost::asio::ip::multicast::outbound_interface @n
845 2486 sjacqu01
   * boost::asio::ip::multicast::hops @n
846 2486 sjacqu01
   * boost::asio::ip::tcp::no_delay
847 2486 sjacqu01
   *
848 2486 sjacqu01
   * @par Example
849 2486 sjacqu01
   * Setting the IPPROTO_TCP/TCP_NODELAY option:
850 2486 sjacqu01
   * @code
851 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
852 2486 sjacqu01
   * ...
853 2486 sjacqu01
   * boost::asio::ip::tcp::no_delay option(true);
854 2486 sjacqu01
   * boost::system::error_code ec;
855 2486 sjacqu01
   * socket.set_option(option, ec);
856 2486 sjacqu01
   * if (ec)
857 2486 sjacqu01
   * {
858 2486 sjacqu01
   *   // An error occurred.
859 2486 sjacqu01
   * }
860 2486 sjacqu01
   * @endcode
861 2486 sjacqu01
   */
862 2486 sjacqu01
  template <typename SettableSocketOption>
863 2486 sjacqu01
  boost::system::error_code set_option(const SettableSocketOption& option,
864 2486 sjacqu01
      boost::system::error_code& ec)
865 2486 sjacqu01
  {
866 2486 sjacqu01
    return this->get_service().set_option(
867 2486 sjacqu01
        this->get_implementation(), option, ec);
868 2486 sjacqu01
  }
869 2486 sjacqu01
870 2486 sjacqu01
  /// Get an option from the socket.
871 2486 sjacqu01
  /**
872 2486 sjacqu01
   * This function is used to get the current value of an option on the socket.
873 2486 sjacqu01
   *
874 2486 sjacqu01
   * @param option The option value to be obtained from the socket.
875 2486 sjacqu01
   *
876 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
877 2486 sjacqu01
   *
878 2486 sjacqu01
   * @sa GettableSocketOption @n
879 2486 sjacqu01
   * boost::asio::socket_base::broadcast @n
880 2486 sjacqu01
   * boost::asio::socket_base::do_not_route @n
881 2486 sjacqu01
   * boost::asio::socket_base::keep_alive @n
882 2486 sjacqu01
   * boost::asio::socket_base::linger @n
883 2486 sjacqu01
   * boost::asio::socket_base::receive_buffer_size @n
884 2486 sjacqu01
   * boost::asio::socket_base::receive_low_watermark @n
885 2486 sjacqu01
   * boost::asio::socket_base::reuse_address @n
886 2486 sjacqu01
   * boost::asio::socket_base::send_buffer_size @n
887 2486 sjacqu01
   * boost::asio::socket_base::send_low_watermark @n
888 2486 sjacqu01
   * boost::asio::ip::multicast::join_group @n
889 2486 sjacqu01
   * boost::asio::ip::multicast::leave_group @n
890 2486 sjacqu01
   * boost::asio::ip::multicast::enable_loopback @n
891 2486 sjacqu01
   * boost::asio::ip::multicast::outbound_interface @n
892 2486 sjacqu01
   * boost::asio::ip::multicast::hops @n
893 2486 sjacqu01
   * boost::asio::ip::tcp::no_delay
894 2486 sjacqu01
   *
895 2486 sjacqu01
   * @par Example
896 2486 sjacqu01
   * Getting the value of the SOL_SOCKET/SO_KEEPALIVE option:
897 2486 sjacqu01
   * @code
898 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
899 2486 sjacqu01
   * ...
900 2486 sjacqu01
   * boost::asio::ip::tcp::socket::keep_alive option;
901 2486 sjacqu01
   * socket.get_option(option);
902 2486 sjacqu01
   * bool is_set = option.value();
903 2486 sjacqu01
   * @endcode
904 2486 sjacqu01
   */
905 2486 sjacqu01
  template <typename GettableSocketOption>
906 2486 sjacqu01
  void get_option(GettableSocketOption& option) const
907 2486 sjacqu01
  {
908 2486 sjacqu01
    boost::system::error_code ec;
909 2486 sjacqu01
    this->get_service().get_option(this->get_implementation(), option, ec);
910 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "get_option");
911 2486 sjacqu01
  }
912 2486 sjacqu01
913 2486 sjacqu01
  /// Get an option from the socket.
914 2486 sjacqu01
  /**
915 2486 sjacqu01
   * This function is used to get the current value of an option on the socket.
916 2486 sjacqu01
   *
917 2486 sjacqu01
   * @param option The option value to be obtained from the socket.
918 2486 sjacqu01
   *
919 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
920 2486 sjacqu01
   *
921 2486 sjacqu01
   * @sa GettableSocketOption @n
922 2486 sjacqu01
   * boost::asio::socket_base::broadcast @n
923 2486 sjacqu01
   * boost::asio::socket_base::do_not_route @n
924 2486 sjacqu01
   * boost::asio::socket_base::keep_alive @n
925 2486 sjacqu01
   * boost::asio::socket_base::linger @n
926 2486 sjacqu01
   * boost::asio::socket_base::receive_buffer_size @n
927 2486 sjacqu01
   * boost::asio::socket_base::receive_low_watermark @n
928 2486 sjacqu01
   * boost::asio::socket_base::reuse_address @n
929 2486 sjacqu01
   * boost::asio::socket_base::send_buffer_size @n
930 2486 sjacqu01
   * boost::asio::socket_base::send_low_watermark @n
931 2486 sjacqu01
   * boost::asio::ip::multicast::join_group @n
932 2486 sjacqu01
   * boost::asio::ip::multicast::leave_group @n
933 2486 sjacqu01
   * boost::asio::ip::multicast::enable_loopback @n
934 2486 sjacqu01
   * boost::asio::ip::multicast::outbound_interface @n
935 2486 sjacqu01
   * boost::asio::ip::multicast::hops @n
936 2486 sjacqu01
   * boost::asio::ip::tcp::no_delay
937 2486 sjacqu01
   *
938 2486 sjacqu01
   * @par Example
939 2486 sjacqu01
   * Getting the value of the SOL_SOCKET/SO_KEEPALIVE option:
940 2486 sjacqu01
   * @code
941 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
942 2486 sjacqu01
   * ...
943 2486 sjacqu01
   * boost::asio::ip::tcp::socket::keep_alive option;
944 2486 sjacqu01
   * boost::system::error_code ec;
945 2486 sjacqu01
   * socket.get_option(option, ec);
946 2486 sjacqu01
   * if (ec)
947 2486 sjacqu01
   * {
948 2486 sjacqu01
   *   // An error occurred.
949 2486 sjacqu01
   * }
950 2486 sjacqu01
   * bool is_set = option.value();
951 2486 sjacqu01
   * @endcode
952 2486 sjacqu01
   */
953 2486 sjacqu01
  template <typename GettableSocketOption>
954 2486 sjacqu01
  boost::system::error_code get_option(GettableSocketOption& option,
955 2486 sjacqu01
      boost::system::error_code& ec) const
956 2486 sjacqu01
  {
957 2486 sjacqu01
    return this->get_service().get_option(
958 2486 sjacqu01
        this->get_implementation(), option, ec);
959 2486 sjacqu01
  }
960 2486 sjacqu01
961 2486 sjacqu01
  /// Perform an IO control command on the socket.
962 2486 sjacqu01
  /**
963 2486 sjacqu01
   * This function is used to execute an IO control command on the socket.
964 2486 sjacqu01
   *
965 2486 sjacqu01
   * @param command The IO control command to be performed on the socket.
966 2486 sjacqu01
   *
967 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
968 2486 sjacqu01
   *
969 2486 sjacqu01
   * @sa IoControlCommand @n
970 2486 sjacqu01
   * boost::asio::socket_base::bytes_readable @n
971 2486 sjacqu01
   * boost::asio::socket_base::non_blocking_io
972 2486 sjacqu01
   *
973 2486 sjacqu01
   * @par Example
974 2486 sjacqu01
   * Getting the number of bytes ready to read:
975 2486 sjacqu01
   * @code
976 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
977 2486 sjacqu01
   * ...
978 2486 sjacqu01
   * boost::asio::ip::tcp::socket::bytes_readable command;
979 2486 sjacqu01
   * socket.io_control(command);
980 2486 sjacqu01
   * std::size_t bytes_readable = command.get();
981 2486 sjacqu01
   * @endcode
982 2486 sjacqu01
   */
983 2486 sjacqu01
  template <typename IoControlCommand>
984 2486 sjacqu01
  void io_control(IoControlCommand& command)
985 2486 sjacqu01
  {
986 2486 sjacqu01
    boost::system::error_code ec;
987 2486 sjacqu01
    this->get_service().io_control(this->get_implementation(), command, ec);
988 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "io_control");
989 2486 sjacqu01
  }
990 2486 sjacqu01
991 2486 sjacqu01
  /// Perform an IO control command on the socket.
992 2486 sjacqu01
  /**
993 2486 sjacqu01
   * This function is used to execute an IO control command on the socket.
994 2486 sjacqu01
   *
995 2486 sjacqu01
   * @param command The IO control command to be performed on the socket.
996 2486 sjacqu01
   *
997 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
998 2486 sjacqu01
   *
999 2486 sjacqu01
   * @sa IoControlCommand @n
1000 2486 sjacqu01
   * boost::asio::socket_base::bytes_readable @n
1001 2486 sjacqu01
   * boost::asio::socket_base::non_blocking_io
1002 2486 sjacqu01
   *
1003 2486 sjacqu01
   * @par Example
1004 2486 sjacqu01
   * Getting the number of bytes ready to read:
1005 2486 sjacqu01
   * @code
1006 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
1007 2486 sjacqu01
   * ...
1008 2486 sjacqu01
   * boost::asio::ip::tcp::socket::bytes_readable command;
1009 2486 sjacqu01
   * boost::system::error_code ec;
1010 2486 sjacqu01
   * socket.io_control(command, ec);
1011 2486 sjacqu01
   * if (ec)
1012 2486 sjacqu01
   * {
1013 2486 sjacqu01
   *   // An error occurred.
1014 2486 sjacqu01
   * }
1015 2486 sjacqu01
   * std::size_t bytes_readable = command.get();
1016 2486 sjacqu01
   * @endcode
1017 2486 sjacqu01
   */
1018 2486 sjacqu01
  template <typename IoControlCommand>
1019 2486 sjacqu01
  boost::system::error_code io_control(IoControlCommand& command,
1020 2486 sjacqu01
      boost::system::error_code& ec)
1021 2486 sjacqu01
  {
1022 2486 sjacqu01
    return this->get_service().io_control(
1023 2486 sjacqu01
        this->get_implementation(), command, ec);
1024 2486 sjacqu01
  }
1025 2486 sjacqu01
1026 2486 sjacqu01
  /// Gets the non-blocking mode of the socket.
1027 2486 sjacqu01
  /**
1028 2486 sjacqu01
   * @returns @c true if the socket's synchronous operations will fail with
1029 2486 sjacqu01
   * boost::asio::error::would_block if they are unable to perform the requested
1030 2486 sjacqu01
   * operation immediately. If @c false, synchronous operations will block
1031 2486 sjacqu01
   * until complete.
1032 2486 sjacqu01
   *
1033 2486 sjacqu01
   * @note The non-blocking mode has no effect on the behaviour of asynchronous
1034 2486 sjacqu01
   * operations. Asynchronous operations will never fail with the error
1035 2486 sjacqu01
   * boost::asio::error::would_block.
1036 2486 sjacqu01
   */
1037 2486 sjacqu01
  bool non_blocking() const
1038 2486 sjacqu01
  {
1039 2486 sjacqu01
    return this->get_service().non_blocking(this->get_implementation());
1040 2486 sjacqu01
  }
1041 2486 sjacqu01
1042 2486 sjacqu01
  /// Sets the non-blocking mode of the socket.
1043 2486 sjacqu01
  /**
1044 2486 sjacqu01
   * @param mode If @c true, the socket's synchronous operations will fail with
1045 2486 sjacqu01
   * boost::asio::error::would_block if they are unable to perform the requested
1046 2486 sjacqu01
   * operation immediately. If @c false, synchronous operations will block
1047 2486 sjacqu01
   * until complete.
1048 2486 sjacqu01
   *
1049 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
1050 2486 sjacqu01
   *
1051 2486 sjacqu01
   * @note The non-blocking mode has no effect on the behaviour of asynchronous
1052 2486 sjacqu01
   * operations. Asynchronous operations will never fail with the error
1053 2486 sjacqu01
   * boost::asio::error::would_block.
1054 2486 sjacqu01
   */
1055 2486 sjacqu01
  void non_blocking(bool mode)
1056 2486 sjacqu01
  {
1057 2486 sjacqu01
    boost::system::error_code ec;
1058 2486 sjacqu01
    this->get_service().non_blocking(this->get_implementation(), mode, ec);
1059 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "non_blocking");
1060 2486 sjacqu01
  }
1061 2486 sjacqu01
1062 2486 sjacqu01
  /// Sets the non-blocking mode of the socket.
1063 2486 sjacqu01
  /**
1064 2486 sjacqu01
   * @param mode If @c true, the socket's synchronous operations will fail with
1065 2486 sjacqu01
   * boost::asio::error::would_block if they are unable to perform the requested
1066 2486 sjacqu01
   * operation immediately. If @c false, synchronous operations will block
1067 2486 sjacqu01
   * until complete.
1068 2486 sjacqu01
   *
1069 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
1070 2486 sjacqu01
   *
1071 2486 sjacqu01
   * @note The non-blocking mode has no effect on the behaviour of asynchronous
1072 2486 sjacqu01
   * operations. Asynchronous operations will never fail with the error
1073 2486 sjacqu01
   * boost::asio::error::would_block.
1074 2486 sjacqu01
   */
1075 2486 sjacqu01
  boost::system::error_code non_blocking(
1076 2486 sjacqu01
      bool mode, boost::system::error_code& ec)
1077 2486 sjacqu01
  {
1078 2486 sjacqu01
    return this->get_service().non_blocking(
1079 2486 sjacqu01
        this->get_implementation(), mode, ec);
1080 2486 sjacqu01
  }
1081 2486 sjacqu01
1082 2486 sjacqu01
  /// Gets the non-blocking mode of the native socket implementation.
1083 2486 sjacqu01
  /**
1084 2486 sjacqu01
   * This function is used to retrieve the non-blocking mode of the underlying
1085 2486 sjacqu01
   * native socket. This mode has no effect on the behaviour of the socket
1086 2486 sjacqu01
   * object's synchronous operations.
1087 2486 sjacqu01
   *
1088 2486 sjacqu01
   * @returns @c true if the underlying socket is in non-blocking mode and
1089 2486 sjacqu01
   * direct system calls may fail with boost::asio::error::would_block (or the
1090 2486 sjacqu01
   * equivalent system error).
1091 2486 sjacqu01
   *
1092 2486 sjacqu01
   * @note The current non-blocking mode is cached by the socket object.
1093 2486 sjacqu01
   * Consequently, the return value may be incorrect if the non-blocking mode
1094 2486 sjacqu01
   * was set directly on the native socket.
1095 2486 sjacqu01
   *
1096 2486 sjacqu01
   * @par Example
1097 2486 sjacqu01
   * This function is intended to allow the encapsulation of arbitrary
1098 2486 sjacqu01
   * non-blocking system calls as asynchronous operations, in a way that is
1099 2486 sjacqu01
   * transparent to the user of the socket object. The following example
1100 2486 sjacqu01
   * illustrates how Linux's @c sendfile system call might be encapsulated:
1101 2486 sjacqu01
   * @code template <typename Handler>
1102 2486 sjacqu01
   * struct sendfile_op
1103 2486 sjacqu01
   * {
1104 2486 sjacqu01
   *   tcp::socket& sock_;
1105 2486 sjacqu01
   *   int fd_;
1106 2486 sjacqu01
   *   Handler handler_;
1107 2486 sjacqu01
   *   off_t offset_;
1108 2486 sjacqu01
   *   std::size_t total_bytes_transferred_;
1109 2486 sjacqu01
   *
1110 2486 sjacqu01
   *   // Function call operator meeting WriteHandler requirements.
1111 2486 sjacqu01
   *   // Used as the handler for the async_write_some operation.
1112 2486 sjacqu01
   *   void operator()(boost::system::error_code ec, std::size_t)
1113 2486 sjacqu01
   *   {
1114 2486 sjacqu01
   *     // Put the underlying socket into non-blocking mode.
1115 2486 sjacqu01
   *     if (!ec)
1116 2486 sjacqu01
   *       if (!sock_.native_non_blocking())
1117 2486 sjacqu01
   *         sock_.native_non_blocking(true, ec);
1118 2486 sjacqu01
   *
1119 2486 sjacqu01
   *     if (!ec)
1120 2486 sjacqu01
   *     {
1121 2486 sjacqu01
   *       for (;;)
1122 2486 sjacqu01
   *       {
1123 2486 sjacqu01
   *         // Try the system call.
1124 2486 sjacqu01
   *         errno = 0;
1125 2486 sjacqu01
   *         int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536);
1126 2486 sjacqu01
   *         ec = boost::system::error_code(n < 0 ? errno : 0,
1127 2486 sjacqu01
   *             boost::asio::error::get_system_category());
1128 2486 sjacqu01
   *         total_bytes_transferred_ += ec ? 0 : n;
1129 2486 sjacqu01
   *
1130 2486 sjacqu01
   *         // Retry operation immediately if interrupted by signal.
1131 2486 sjacqu01
   *         if (ec == boost::asio::error::interrupted)
1132 2486 sjacqu01
   *           continue;
1133 2486 sjacqu01
   *
1134 2486 sjacqu01
   *         // Check if we need to run the operation again.
1135 2486 sjacqu01
   *         if (ec == boost::asio::error::would_block
1136 2486 sjacqu01
   *             || ec == boost::asio::error::try_again)
1137 2486 sjacqu01
   *         {
1138 2486 sjacqu01
   *           // We have to wait for the socket to become ready again.
1139 2486 sjacqu01
   *           sock_.async_write_some(boost::asio::null_buffers(), *this);
1140 2486 sjacqu01
   *           return;
1141 2486 sjacqu01
   *         }
1142 2486 sjacqu01
   *
1143 2486 sjacqu01
   *         if (ec || n == 0)
1144 2486 sjacqu01
   *         {
1145 2486 sjacqu01
   *           // An error occurred, or we have reached the end of the file.
1146 2486 sjacqu01
   *           // Either way we must exit the loop so we can call the handler.
1147 2486 sjacqu01
   *           break;
1148 2486 sjacqu01
   *         }
1149 2486 sjacqu01
   *
1150 2486 sjacqu01
   *         // Loop around to try calling sendfile again.
1151 2486 sjacqu01
   *       }
1152 2486 sjacqu01
   *     }
1153 2486 sjacqu01
   *
1154 2486 sjacqu01
   *     // Pass result back to user's handler.
1155 2486 sjacqu01
   *     handler_(ec, total_bytes_transferred_);
1156 2486 sjacqu01
   *   }
1157 2486 sjacqu01
   * };
1158 2486 sjacqu01
   *
1159 2486 sjacqu01
   * template <typename Handler>
1160 2486 sjacqu01
   * void async_sendfile(tcp::socket& sock, int fd, Handler h)
1161 2486 sjacqu01
   * {
1162 2486 sjacqu01
   *   sendfile_op<Handler> op = { sock, fd, h, 0, 0 };
1163 2486 sjacqu01
   *   sock.async_write_some(boost::asio::null_buffers(), op);
1164 2486 sjacqu01
   * } @endcode
1165 2486 sjacqu01
   */
1166 2486 sjacqu01
  bool native_non_blocking() const
1167 2486 sjacqu01
  {
1168 2486 sjacqu01
    return this->get_service().native_non_blocking(this->get_implementation());
1169 2486 sjacqu01
  }
1170 2486 sjacqu01
1171 2486 sjacqu01
  /// Sets the non-blocking mode of the native socket implementation.
1172 2486 sjacqu01
  /**
1173 2486 sjacqu01
   * This function is used to modify the non-blocking mode of the underlying
1174 2486 sjacqu01
   * native socket. It has no effect on the behaviour of the socket object's
1175 2486 sjacqu01
   * synchronous operations.
1176 2486 sjacqu01
   *
1177 2486 sjacqu01
   * @param mode If @c true, the underlying socket is put into non-blocking
1178 2486 sjacqu01
   * mode and direct system calls may fail with boost::asio::error::would_block
1179 2486 sjacqu01
   * (or the equivalent system error).
1180 2486 sjacqu01
   *
1181 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure. If the @c mode is
1182 2486 sjacqu01
   * @c false, but the current value of @c non_blocking() is @c true, this
1183 2486 sjacqu01
   * function fails with boost::asio::error::invalid_argument, as the
1184 2486 sjacqu01
   * combination does not make sense.
1185 2486 sjacqu01
   *
1186 2486 sjacqu01
   * @par Example
1187 2486 sjacqu01
   * This function is intended to allow the encapsulation of arbitrary
1188 2486 sjacqu01
   * non-blocking system calls as asynchronous operations, in a way that is
1189 2486 sjacqu01
   * transparent to the user of the socket object. The following example
1190 2486 sjacqu01
   * illustrates how Linux's @c sendfile system call might be encapsulated:
1191 2486 sjacqu01
   * @code template <typename Handler>
1192 2486 sjacqu01
   * struct sendfile_op
1193 2486 sjacqu01
   * {
1194 2486 sjacqu01
   *   tcp::socket& sock_;
1195 2486 sjacqu01
   *   int fd_;
1196 2486 sjacqu01
   *   Handler handler_;
1197 2486 sjacqu01
   *   off_t offset_;
1198 2486 sjacqu01
   *   std::size_t total_bytes_transferred_;
1199 2486 sjacqu01
   *
1200 2486 sjacqu01
   *   // Function call operator meeting WriteHandler requirements.
1201 2486 sjacqu01
   *   // Used as the handler for the async_write_some operation.
1202 2486 sjacqu01
   *   void operator()(boost::system::error_code ec, std::size_t)
1203 2486 sjacqu01
   *   {
1204 2486 sjacqu01
   *     // Put the underlying socket into non-blocking mode.
1205 2486 sjacqu01
   *     if (!ec)
1206 2486 sjacqu01
   *       if (!sock_.native_non_blocking())
1207 2486 sjacqu01
   *         sock_.native_non_blocking(true, ec);
1208 2486 sjacqu01
   *
1209 2486 sjacqu01
   *     if (!ec)
1210 2486 sjacqu01
   *     {
1211 2486 sjacqu01
   *       for (;;)
1212 2486 sjacqu01
   *       {
1213 2486 sjacqu01
   *         // Try the system call.
1214 2486 sjacqu01
   *         errno = 0;
1215 2486 sjacqu01
   *         int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536);
1216 2486 sjacqu01
   *         ec = boost::system::error_code(n < 0 ? errno : 0,
1217 2486 sjacqu01
   *             boost::asio::error::get_system_category());
1218 2486 sjacqu01
   *         total_bytes_transferred_ += ec ? 0 : n;
1219 2486 sjacqu01
   *
1220 2486 sjacqu01
   *         // Retry operation immediately if interrupted by signal.
1221 2486 sjacqu01
   *         if (ec == boost::asio::error::interrupted)
1222 2486 sjacqu01
   *           continue;
1223 2486 sjacqu01
   *
1224 2486 sjacqu01
   *         // Check if we need to run the operation again.
1225 2486 sjacqu01
   *         if (ec == boost::asio::error::would_block
1226 2486 sjacqu01
   *             || ec == boost::asio::error::try_again)
1227 2486 sjacqu01
   *         {
1228 2486 sjacqu01
   *           // We have to wait for the socket to become ready again.
1229 2486 sjacqu01
   *           sock_.async_write_some(boost::asio::null_buffers(), *this);
1230 2486 sjacqu01
   *           return;
1231 2486 sjacqu01
   *         }
1232 2486 sjacqu01
   *
1233 2486 sjacqu01
   *         if (ec || n == 0)
1234 2486 sjacqu01
   *         {
1235 2486 sjacqu01
   *           // An error occurred, or we have reached the end of the file.
1236 2486 sjacqu01
   *           // Either way we must exit the loop so we can call the handler.
1237 2486 sjacqu01
   *           break;
1238 2486 sjacqu01
   *         }
1239 2486 sjacqu01
   *
1240 2486 sjacqu01
   *         // Loop around to try calling sendfile again.
1241 2486 sjacqu01
   *       }
1242 2486 sjacqu01
   *     }
1243 2486 sjacqu01
   *
1244 2486 sjacqu01
   *     // Pass result back to user's handler.
1245 2486 sjacqu01
   *     handler_(ec, total_bytes_transferred_);
1246 2486 sjacqu01
   *   }
1247 2486 sjacqu01
   * };
1248 2486 sjacqu01
   *
1249 2486 sjacqu01
   * template <typename Handler>
1250 2486 sjacqu01
   * void async_sendfile(tcp::socket& sock, int fd, Handler h)
1251 2486 sjacqu01
   * {
1252 2486 sjacqu01
   *   sendfile_op<Handler> op = { sock, fd, h, 0, 0 };
1253 2486 sjacqu01
   *   sock.async_write_some(boost::asio::null_buffers(), op);
1254 2486 sjacqu01
   * } @endcode
1255 2486 sjacqu01
   */
1256 2486 sjacqu01
  void native_non_blocking(bool mode)
1257 2486 sjacqu01
  {
1258 2486 sjacqu01
    boost::system::error_code ec;
1259 2486 sjacqu01
    this->get_service().native_non_blocking(
1260 2486 sjacqu01
        this->get_implementation(), mode, ec);
1261 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "native_non_blocking");
1262 2486 sjacqu01
  }
1263 2486 sjacqu01
1264 2486 sjacqu01
  /// Sets the non-blocking mode of the native socket implementation.
1265 2486 sjacqu01
  /**
1266 2486 sjacqu01
   * This function is used to modify the non-blocking mode of the underlying
1267 2486 sjacqu01
   * native socket. It has no effect on the behaviour of the socket object's
1268 2486 sjacqu01
   * synchronous operations.
1269 2486 sjacqu01
   *
1270 2486 sjacqu01
   * @param mode If @c true, the underlying socket is put into non-blocking
1271 2486 sjacqu01
   * mode and direct system calls may fail with boost::asio::error::would_block
1272 2486 sjacqu01
   * (or the equivalent system error).
1273 2486 sjacqu01
   *
1274 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any. If the @c mode is
1275 2486 sjacqu01
   * @c false, but the current value of @c non_blocking() is @c true, this
1276 2486 sjacqu01
   * function fails with boost::asio::error::invalid_argument, as the
1277 2486 sjacqu01
   * combination does not make sense.
1278 2486 sjacqu01
   *
1279 2486 sjacqu01
   * @par Example
1280 2486 sjacqu01
   * This function is intended to allow the encapsulation of arbitrary
1281 2486 sjacqu01
   * non-blocking system calls as asynchronous operations, in a way that is
1282 2486 sjacqu01
   * transparent to the user of the socket object. The following example
1283 2486 sjacqu01
   * illustrates how Linux's @c sendfile system call might be encapsulated:
1284 2486 sjacqu01
   * @code template <typename Handler>
1285 2486 sjacqu01
   * struct sendfile_op
1286 2486 sjacqu01
   * {
1287 2486 sjacqu01
   *   tcp::socket& sock_;
1288 2486 sjacqu01
   *   int fd_;
1289 2486 sjacqu01
   *   Handler handler_;
1290 2486 sjacqu01
   *   off_t offset_;
1291 2486 sjacqu01
   *   std::size_t total_bytes_transferred_;
1292 2486 sjacqu01
   *
1293 2486 sjacqu01
   *   // Function call operator meeting WriteHandler requirements.
1294 2486 sjacqu01
   *   // Used as the handler for the async_write_some operation.
1295 2486 sjacqu01
   *   void operator()(boost::system::error_code ec, std::size_t)
1296 2486 sjacqu01
   *   {
1297 2486 sjacqu01
   *     // Put the underlying socket into non-blocking mode.
1298 2486 sjacqu01
   *     if (!ec)
1299 2486 sjacqu01
   *       if (!sock_.native_non_blocking())
1300 2486 sjacqu01
   *         sock_.native_non_blocking(true, ec);
1301 2486 sjacqu01
   *
1302 2486 sjacqu01
   *     if (!ec)
1303 2486 sjacqu01
   *     {
1304 2486 sjacqu01
   *       for (;;)
1305 2486 sjacqu01
   *       {
1306 2486 sjacqu01
   *         // Try the system call.
1307 2486 sjacqu01
   *         errno = 0;
1308 2486 sjacqu01
   *         int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536);
1309 2486 sjacqu01
   *         ec = boost::system::error_code(n < 0 ? errno : 0,
1310 2486 sjacqu01
   *             boost::asio::error::get_system_category());
1311 2486 sjacqu01
   *         total_bytes_transferred_ += ec ? 0 : n;
1312 2486 sjacqu01
   *
1313 2486 sjacqu01
   *         // Retry operation immediately if interrupted by signal.
1314 2486 sjacqu01
   *         if (ec == boost::asio::error::interrupted)
1315 2486 sjacqu01
   *           continue;
1316 2486 sjacqu01
   *
1317 2486 sjacqu01
   *         // Check if we need to run the operation again.
1318 2486 sjacqu01
   *         if (ec == boost::asio::error::would_block
1319 2486 sjacqu01
   *             || ec == boost::asio::error::try_again)
1320 2486 sjacqu01
   *         {
1321 2486 sjacqu01
   *           // We have to wait for the socket to become ready again.
1322 2486 sjacqu01
   *           sock_.async_write_some(boost::asio::null_buffers(), *this);
1323 2486 sjacqu01
   *           return;
1324 2486 sjacqu01
   *         }
1325 2486 sjacqu01
   *
1326 2486 sjacqu01
   *         if (ec || n == 0)
1327 2486 sjacqu01
   *         {
1328 2486 sjacqu01
   *           // An error occurred, or we have reached the end of the file.
1329 2486 sjacqu01
   *           // Either way we must exit the loop so we can call the handler.
1330 2486 sjacqu01
   *           break;
1331 2486 sjacqu01
   *         }
1332 2486 sjacqu01
   *
1333 2486 sjacqu01
   *         // Loop around to try calling sendfile again.
1334 2486 sjacqu01
   *       }
1335 2486 sjacqu01
   *     }
1336 2486 sjacqu01
   *
1337 2486 sjacqu01
   *     // Pass result back to user's handler.
1338 2486 sjacqu01
   *     handler_(ec, total_bytes_transferred_);
1339 2486 sjacqu01
   *   }
1340 2486 sjacqu01
   * };
1341 2486 sjacqu01
   *
1342 2486 sjacqu01
   * template <typename Handler>
1343 2486 sjacqu01
   * void async_sendfile(tcp::socket& sock, int fd, Handler h)
1344 2486 sjacqu01
   * {
1345 2486 sjacqu01
   *   sendfile_op<Handler> op = { sock, fd, h, 0, 0 };
1346 2486 sjacqu01
   *   sock.async_write_some(boost::asio::null_buffers(), op);
1347 2486 sjacqu01
   * } @endcode
1348 2486 sjacqu01
   */
1349 2486 sjacqu01
  boost::system::error_code native_non_blocking(
1350 2486 sjacqu01
      bool mode, boost::system::error_code& ec)
1351 2486 sjacqu01
  {
1352 2486 sjacqu01
    return this->get_service().native_non_blocking(
1353 2486 sjacqu01
        this->get_implementation(), mode, ec);
1354 2486 sjacqu01
  }
1355 2486 sjacqu01
1356 2486 sjacqu01
  /// Get the local endpoint of the socket.
1357 2486 sjacqu01
  /**
1358 2486 sjacqu01
   * This function is used to obtain the locally bound endpoint of the socket.
1359 2486 sjacqu01
   *
1360 2486 sjacqu01
   * @returns An object that represents the local endpoint of the socket.
1361 2486 sjacqu01
   *
1362 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
1363 2486 sjacqu01
   *
1364 2486 sjacqu01
   * @par Example
1365 2486 sjacqu01
   * @code
1366 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
1367 2486 sjacqu01
   * ...
1368 2486 sjacqu01
   * boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint();
1369 2486 sjacqu01
   * @endcode
1370 2486 sjacqu01
   */
1371 2486 sjacqu01
  endpoint_type local_endpoint() const
1372 2486 sjacqu01
  {
1373 2486 sjacqu01
    boost::system::error_code ec;
1374 2486 sjacqu01
    endpoint_type ep = this->get_service().local_endpoint(
1375 2486 sjacqu01
        this->get_implementation(), ec);
1376 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "local_endpoint");
1377 2486 sjacqu01
    return ep;
1378 2486 sjacqu01
  }
1379 2486 sjacqu01
1380 2486 sjacqu01
  /// Get the local endpoint of the socket.
1381 2486 sjacqu01
  /**
1382 2486 sjacqu01
   * This function is used to obtain the locally bound endpoint of the socket.
1383 2486 sjacqu01
   *
1384 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
1385 2486 sjacqu01
   *
1386 2486 sjacqu01
   * @returns An object that represents the local endpoint of the socket.
1387 2486 sjacqu01
   * Returns a default-constructed endpoint object if an error occurred.
1388 2486 sjacqu01
   *
1389 2486 sjacqu01
   * @par Example
1390 2486 sjacqu01
   * @code
1391 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
1392 2486 sjacqu01
   * ...
1393 2486 sjacqu01
   * boost::system::error_code ec;
1394 2486 sjacqu01
   * boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(ec);
1395 2486 sjacqu01
   * if (ec)
1396 2486 sjacqu01
   * {
1397 2486 sjacqu01
   *   // An error occurred.
1398 2486 sjacqu01
   * }
1399 2486 sjacqu01
   * @endcode
1400 2486 sjacqu01
   */
1401 2486 sjacqu01
  endpoint_type local_endpoint(boost::system::error_code& ec) const
1402 2486 sjacqu01
  {
1403 2486 sjacqu01
    return this->get_service().local_endpoint(this->get_implementation(), ec);
1404 2486 sjacqu01
  }
1405 2486 sjacqu01
1406 2486 sjacqu01
  /// Get the remote endpoint of the socket.
1407 2486 sjacqu01
  /**
1408 2486 sjacqu01
   * This function is used to obtain the remote endpoint of the socket.
1409 2486 sjacqu01
   *
1410 2486 sjacqu01
   * @returns An object that represents the remote endpoint of the socket.
1411 2486 sjacqu01
   *
1412 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
1413 2486 sjacqu01
   *
1414 2486 sjacqu01
   * @par Example
1415 2486 sjacqu01
   * @code
1416 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
1417 2486 sjacqu01
   * ...
1418 2486 sjacqu01
   * boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint();
1419 2486 sjacqu01
   * @endcode
1420 2486 sjacqu01
   */
1421 2486 sjacqu01
  endpoint_type remote_endpoint() const
1422 2486 sjacqu01
  {
1423 2486 sjacqu01
    boost::system::error_code ec;
1424 2486 sjacqu01
    endpoint_type ep = this->get_service().remote_endpoint(
1425 2486 sjacqu01
        this->get_implementation(), ec);
1426 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "remote_endpoint");
1427 2486 sjacqu01
    return ep;
1428 2486 sjacqu01
  }
1429 2486 sjacqu01
1430 2486 sjacqu01
  /// Get the remote endpoint of the socket.
1431 2486 sjacqu01
  /**
1432 2486 sjacqu01
   * This function is used to obtain the remote endpoint of the socket.
1433 2486 sjacqu01
   *
1434 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
1435 2486 sjacqu01
   *
1436 2486 sjacqu01
   * @returns An object that represents the remote endpoint of the socket.
1437 2486 sjacqu01
   * Returns a default-constructed endpoint object if an error occurred.
1438 2486 sjacqu01
   *
1439 2486 sjacqu01
   * @par Example
1440 2486 sjacqu01
   * @code
1441 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
1442 2486 sjacqu01
   * ...
1443 2486 sjacqu01
   * boost::system::error_code ec;
1444 2486 sjacqu01
   * boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(ec);
1445 2486 sjacqu01
   * if (ec)
1446 2486 sjacqu01
   * {
1447 2486 sjacqu01
   *   // An error occurred.
1448 2486 sjacqu01
   * }
1449 2486 sjacqu01
   * @endcode
1450 2486 sjacqu01
   */
1451 2486 sjacqu01
  endpoint_type remote_endpoint(boost::system::error_code& ec) const
1452 2486 sjacqu01
  {
1453 2486 sjacqu01
    return this->get_service().remote_endpoint(this->get_implementation(), ec);
1454 2486 sjacqu01
  }
1455 2486 sjacqu01
1456 2486 sjacqu01
  /// Disable sends or receives on the socket.
1457 2486 sjacqu01
  /**
1458 2486 sjacqu01
   * This function is used to disable send operations, receive operations, or
1459 2486 sjacqu01
   * both.
1460 2486 sjacqu01
   *
1461 2486 sjacqu01
   * @param what Determines what types of operation will no longer be allowed.
1462 2486 sjacqu01
   *
1463 2486 sjacqu01
   * @throws boost::system::system_error Thrown on failure.
1464 2486 sjacqu01
   *
1465 2486 sjacqu01
   * @par Example
1466 2486 sjacqu01
   * Shutting down the send side of the socket:
1467 2486 sjacqu01
   * @code
1468 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
1469 2486 sjacqu01
   * ...
1470 2486 sjacqu01
   * socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send);
1471 2486 sjacqu01
   * @endcode
1472 2486 sjacqu01
   */
1473 2486 sjacqu01
  void shutdown(shutdown_type what)
1474 2486 sjacqu01
  {
1475 2486 sjacqu01
    boost::system::error_code ec;
1476 2486 sjacqu01
    this->get_service().shutdown(this->get_implementation(), what, ec);
1477 2486 sjacqu01
    boost::asio::detail::throw_error(ec, "shutdown");
1478 2486 sjacqu01
  }
1479 2486 sjacqu01
1480 2486 sjacqu01
  /// Disable sends or receives on the socket.
1481 2486 sjacqu01
  /**
1482 2486 sjacqu01
   * This function is used to disable send operations, receive operations, or
1483 2486 sjacqu01
   * both.
1484 2486 sjacqu01
   *
1485 2486 sjacqu01
   * @param what Determines what types of operation will no longer be allowed.
1486 2486 sjacqu01
   *
1487 2486 sjacqu01
   * @param ec Set to indicate what error occurred, if any.
1488 2486 sjacqu01
   *
1489 2486 sjacqu01
   * @par Example
1490 2486 sjacqu01
   * Shutting down the send side of the socket:
1491 2486 sjacqu01
   * @code
1492 2486 sjacqu01
   * boost::asio::ip::tcp::socket socket(io_service);
1493 2486 sjacqu01
   * ...
1494 2486 sjacqu01
   * boost::system::error_code ec;
1495 2486 sjacqu01
   * socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send, ec);
1496 2486 sjacqu01
   * if (ec)
1497 2486 sjacqu01
   * {
1498 2486 sjacqu01
   *   // An error occurred.
1499 2486 sjacqu01
   * }
1500 2486 sjacqu01
   * @endcode
1501 2486 sjacqu01
   */
1502 2486 sjacqu01
  boost::system::error_code shutdown(shutdown_type what,
1503 2486 sjacqu01
      boost::system::error_code& ec)
1504 2486 sjacqu01
  {
1505 2486 sjacqu01
    return this->get_service().shutdown(this->get_implementation(), what, ec);
1506 2486 sjacqu01
  }
1507 2486 sjacqu01
1508 2486 sjacqu01
protected:
1509 2486 sjacqu01
  /// Protected destructor to prevent deletion through this type.
1510 2486 sjacqu01
  ~basic_socket()
1511 2486 sjacqu01
  {
1512 2486 sjacqu01
  }
1513 2486 sjacqu01
};
1514 2486 sjacqu01
1515 2486 sjacqu01
} // namespace asio
1516 2486 sjacqu01
} // namespace boost
1517 2486 sjacqu01
1518 2486 sjacqu01
#include <boost/asio/detail/pop_options.hpp>
1519 2486 sjacqu01
1520 2486 sjacqu01
#endif // BOOST_ASIO_BASIC_SOCKET_HPP