~cmiller/ubuntu/quantal/deluge/fix-parameter-move-storage

« back to all changes in this revision

Viewing changes to libtorrent/include/asio/basic_datagram_socket.hpp

  • Committer: Bazaar Package Importer
  • Author(s): Cristian Greco
  • Date: 2009-11-13 02:39:45 UTC
  • mfrom: (4.1.7 squeeze)
  • Revision ID: james.westby@ubuntu.com-20091113023945-te1bybo2912ejzuc
Tags: 1.2.0~rc3-4
* debian/control: bump build-dep on python-setuptools to (>= 0.6c9).
* debian/patches:
  - 25_r5921_fastresume_files.patch
    new, should fix problems with fresh configs;
  - 30_r5931_ipc_lockfile.patch:
    new, should fix an issue where Deluge will fail to start if there is a
    stale ipc lockfile. (Closes: #555849)

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
//
2
 
// basic_datagram_socket.hpp
3
 
// ~~~~~~~~~~~~~~~~~~~~~~~~~
4
 
//
5
 
// Copyright (c) 2003-2008 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
 
 
11
 
#ifndef ASIO_BASIC_DATAGRAM_SOCKET_HPP
12
 
#define ASIO_BASIC_DATAGRAM_SOCKET_HPP
13
 
 
14
 
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15
 
# pragma once
16
 
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17
 
 
18
 
#include "asio/detail/push_options.hpp"
19
 
 
20
 
#include "asio/detail/push_options.hpp"
21
 
#include <cstddef>
22
 
#include <boost/config.hpp>
23
 
#include "asio/detail/pop_options.hpp"
24
 
 
25
 
#include "asio/basic_socket.hpp"
26
 
#include "asio/datagram_socket_service.hpp"
27
 
#include "asio/error.hpp"
28
 
#include "asio/detail/throw_error.hpp"
29
 
 
30
 
namespace asio {
31
 
 
32
 
/// Provides datagram-oriented socket functionality.
33
 
/**
34
 
 * The basic_datagram_socket class template provides asynchronous and blocking
35
 
 * datagram-oriented socket functionality.
36
 
 *
37
 
 * @par Thread Safety
38
 
 * @e Distinct @e objects: Safe.@n
39
 
 * @e Shared @e objects: Unsafe.
40
 
 */
41
 
template <typename Protocol,
42
 
    typename DatagramSocketService = datagram_socket_service<Protocol> >
43
 
class basic_datagram_socket
44
 
  : public basic_socket<Protocol, DatagramSocketService>
45
 
{
46
 
public:
47
 
  /// The native representation of a socket.
48
 
  typedef typename DatagramSocketService::native_type native_type;
49
 
 
50
 
  /// The protocol type.
51
 
  typedef Protocol protocol_type;
52
 
 
53
 
  /// The endpoint type.
54
 
  typedef typename Protocol::endpoint endpoint_type;
55
 
 
56
 
  /// Construct a basic_datagram_socket without opening it.
57
 
  /**
58
 
   * This constructor creates a datagram socket without opening it. The open()
59
 
   * function must be called before data can be sent or received on the socket.
60
 
   *
61
 
   * @param io_service The io_service object that the datagram socket will use
62
 
   * to dispatch handlers for any asynchronous operations performed on the
63
 
   * socket.
64
 
   */
65
 
  explicit basic_datagram_socket(asio::io_service& io_service)
66
 
    : basic_socket<Protocol, DatagramSocketService>(io_service)
67
 
  {
68
 
  }
69
 
 
70
 
  /// Construct and open a basic_datagram_socket.
71
 
  /**
72
 
   * This constructor creates and opens a datagram socket.
73
 
   *
74
 
   * @param io_service The io_service object that the datagram socket will use
75
 
   * to dispatch handlers for any asynchronous operations performed on the
76
 
   * socket.
77
 
   *
78
 
   * @param protocol An object specifying protocol parameters to be used.
79
 
   *
80
 
   * @throws asio::system_error Thrown on failure.
81
 
   */
82
 
  basic_datagram_socket(asio::io_service& io_service,
83
 
      const protocol_type& protocol)
84
 
    : basic_socket<Protocol, DatagramSocketService>(io_service, protocol)
85
 
  {
86
 
  }
87
 
 
88
 
  /// Construct a basic_datagram_socket, opening it and binding it to the given
89
 
  /// local endpoint.
90
 
  /**
91
 
   * This constructor creates a datagram socket and automatically opens it bound
92
 
   * to the specified endpoint on the local machine. The protocol used is the
93
 
   * protocol associated with the given endpoint.
94
 
   *
95
 
   * @param io_service The io_service object that the datagram socket will use
96
 
   * to dispatch handlers for any asynchronous operations performed on the
97
 
   * socket.
98
 
   *
99
 
   * @param endpoint An endpoint on the local machine to which the datagram
100
 
   * socket will be bound.
101
 
   *
102
 
   * @throws asio::system_error Thrown on failure.
103
 
   */
104
 
  basic_datagram_socket(asio::io_service& io_service,
105
 
      const endpoint_type& endpoint)
106
 
    : basic_socket<Protocol, DatagramSocketService>(io_service, endpoint)
107
 
  {
108
 
  }
109
 
 
110
 
  /// Construct a basic_datagram_socket on an existing native socket.
111
 
  /**
112
 
   * This constructor creates a datagram socket object to hold an existing
113
 
   * native socket.
114
 
   *
115
 
   * @param io_service The io_service object that the datagram socket will use
116
 
   * to dispatch handlers for any asynchronous operations performed on the
117
 
   * socket.
118
 
   *
119
 
   * @param protocol An object specifying protocol parameters to be used.
120
 
   *
121
 
   * @param native_socket The new underlying socket implementation.
122
 
   *
123
 
   * @throws asio::system_error Thrown on failure.
124
 
   */
125
 
  basic_datagram_socket(asio::io_service& io_service,
126
 
      const protocol_type& protocol, const native_type& native_socket)
127
 
    : basic_socket<Protocol, DatagramSocketService>(
128
 
        io_service, protocol, native_socket)
129
 
  {
130
 
  }
131
 
 
132
 
  /// Send some data on a connected socket.
133
 
  /**
134
 
   * This function is used to send data on the datagram socket. The function
135
 
   * call will block until the data has been sent successfully or an error
136
 
   * occurs.
137
 
   *
138
 
   * @param buffers One ore more data buffers to be sent on the socket.
139
 
   *
140
 
   * @returns The number of bytes sent.
141
 
   *
142
 
   * @throws asio::system_error Thrown on failure.
143
 
   *
144
 
   * @note The send operation can only be used with a connected socket. Use
145
 
   * the send_to function to send data on an unconnected datagram socket.
146
 
   *
147
 
   * @par Example
148
 
   * To send a single data buffer use the @ref buffer function as follows:
149
 
   * @code socket.send(asio::buffer(data, size)); @endcode
150
 
   * See the @ref buffer documentation for information on sending multiple
151
 
   * buffers in one go, and how to use it with arrays, boost::array or
152
 
   * std::vector.
153
 
   */
154
 
  template <typename ConstBufferSequence>
155
 
  std::size_t send(const ConstBufferSequence& buffers)
156
 
  {
157
 
    asio::error_code ec;
158
 
    std::size_t s = this->service.send(this->implementation, buffers, 0, ec);
159
 
    asio::detail::throw_error(ec);
160
 
    return s;
161
 
  }
162
 
 
163
 
  /// Send some data on a connected socket.
164
 
  /**
165
 
   * This function is used to send data on the datagram socket. The function
166
 
   * call will block until the data has been sent successfully or an error
167
 
   * occurs.
168
 
   *
169
 
   * @param buffers One ore more data buffers to be sent on the socket.
170
 
   *
171
 
   * @param flags Flags specifying how the send call is to be made.
172
 
   *
173
 
   * @returns The number of bytes sent.
174
 
   *
175
 
   * @throws asio::system_error Thrown on failure.
176
 
   *
177
 
   * @note The send operation can only be used with a connected socket. Use
178
 
   * the send_to function to send data on an unconnected datagram socket.
179
 
   */
180
 
  template <typename ConstBufferSequence>
181
 
  std::size_t send(const ConstBufferSequence& buffers,
182
 
      socket_base::message_flags flags)
183
 
  {
184
 
    asio::error_code ec;
185
 
    std::size_t s = this->service.send(
186
 
        this->implementation, buffers, flags, ec);
187
 
    asio::detail::throw_error(ec);
188
 
    return s;
189
 
  }
190
 
 
191
 
  /// Send some data on a connected socket.
192
 
  /**
193
 
   * This function is used to send data on the datagram socket. The function
194
 
   * call will block until the data has been sent successfully or an error
195
 
   * occurs.
196
 
   *
197
 
   * @param buffers One or more data buffers to be sent on the socket.
198
 
   *
199
 
   * @param flags Flags specifying how the send call is to be made.
200
 
   *
201
 
   * @param ec Set to indicate what error occurred, if any.
202
 
   *
203
 
   * @returns The number of bytes sent.
204
 
   *
205
 
   * @note The send operation can only be used with a connected socket. Use
206
 
   * the send_to function to send data on an unconnected datagram socket.
207
 
   */
208
 
  template <typename ConstBufferSequence>
209
 
  std::size_t send(const ConstBufferSequence& buffers,
210
 
      socket_base::message_flags flags, asio::error_code& ec)
211
 
  {
212
 
    return this->service.send(this->implementation, buffers, flags, ec);
213
 
  }
214
 
 
215
 
  /// Start an asynchronous send on a connected socket.
216
 
  /**
217
 
   * This function is used to send data on the datagram socket. The function
218
 
   * call will block until the data has been sent successfully or an error
219
 
   * occurs.
220
 
   *
221
 
   * @param buffers One or more data buffers to be sent on the socket. Although
222
 
   * the buffers object may be copied as necessary, ownership of the underlying
223
 
   * memory blocks is retained by the caller, which must guarantee that they
224
 
   * remain valid until the handler is called.
225
 
   *
226
 
   * @param handler The handler to be called when the send operation completes.
227
 
   * Copies will be made of the handler as required. The function signature of
228
 
   * the handler must be:
229
 
   * @code void handler(
230
 
   *   const asio::error_code& error, // Result of operation.
231
 
   *   std::size_t bytes_transferred           // Number of bytes sent.
232
 
   * ); @endcode
233
 
   * Regardless of whether the asynchronous operation completes immediately or
234
 
   * not, the handler will not be invoked from within this function. Invocation
235
 
   * of the handler will be performed in a manner equivalent to using
236
 
   * asio::io_service::post().
237
 
   *
238
 
   * @note The async_send operation can only be used with a connected socket.
239
 
   * Use the async_send_to function to send data on an unconnected datagram
240
 
   * socket.
241
 
   *
242
 
   * @par Example
243
 
   * To send a single data buffer use the @ref buffer function as follows:
244
 
   * @code
245
 
   * socket.async_send(asio::buffer(data, size), handler);
246
 
   * @endcode
247
 
   * See the @ref buffer documentation for information on sending multiple
248
 
   * buffers in one go, and how to use it with arrays, boost::array or
249
 
   * std::vector.
250
 
   */
251
 
  template <typename ConstBufferSequence, typename WriteHandler>
252
 
  void async_send(const ConstBufferSequence& buffers, WriteHandler handler)
253
 
  {
254
 
    this->service.async_send(this->implementation, buffers, 0, handler);
255
 
  }
256
 
 
257
 
  /// Start an asynchronous send on a connected socket.
258
 
  /**
259
 
   * This function is used to send data on the datagram socket. The function
260
 
   * call will block until the data has been sent successfully or an error
261
 
   * occurs.
262
 
   *
263
 
   * @param buffers One or more data buffers to be sent on the socket. Although
264
 
   * the buffers object may be copied as necessary, ownership of the underlying
265
 
   * memory blocks is retained by the caller, which must guarantee that they
266
 
   * remain valid until the handler is called.
267
 
   *
268
 
   * @param flags Flags specifying how the send call is to be made.
269
 
   *
270
 
   * @param handler The handler to be called when the send operation completes.
271
 
   * Copies will be made of the handler as required. The function signature of
272
 
   * the handler must be:
273
 
   * @code void handler(
274
 
   *   const asio::error_code& error, // Result of operation.
275
 
   *   std::size_t bytes_transferred           // Number of bytes sent.
276
 
   * ); @endcode
277
 
   * Regardless of whether the asynchronous operation completes immediately or
278
 
   * not, the handler will not be invoked from within this function. Invocation
279
 
   * of the handler will be performed in a manner equivalent to using
280
 
   * asio::io_service::post().
281
 
   *
282
 
   * @note The async_send operation can only be used with a connected socket.
283
 
   * Use the async_send_to function to send data on an unconnected datagram
284
 
   * socket.
285
 
   */
286
 
  template <typename ConstBufferSequence, typename WriteHandler>
287
 
  void async_send(const ConstBufferSequence& buffers,
288
 
      socket_base::message_flags flags, WriteHandler handler)
289
 
  {
290
 
    this->service.async_send(this->implementation, buffers, flags, handler);
291
 
  }
292
 
 
293
 
  /// Send a datagram to the specified endpoint.
294
 
  /**
295
 
   * This function is used to send a datagram to the specified remote endpoint.
296
 
   * The function call will block until the data has been sent successfully or
297
 
   * an error occurs.
298
 
   *
299
 
   * @param buffers One or more data buffers to be sent to the remote endpoint.
300
 
   *
301
 
   * @param destination The remote endpoint to which the data will be sent.
302
 
   *
303
 
   * @returns The number of bytes sent.
304
 
   *
305
 
   * @throws asio::system_error Thrown on failure.
306
 
   *
307
 
   * @par Example
308
 
   * To send a single data buffer use the @ref buffer function as follows:
309
 
   * @code
310
 
   * asio::ip::udp::endpoint destination(
311
 
   *     asio::ip::address::from_string("1.2.3.4"), 12345);
312
 
   * socket.send_to(asio::buffer(data, size), destination);
313
 
   * @endcode
314
 
   * See the @ref buffer documentation for information on sending multiple
315
 
   * buffers in one go, and how to use it with arrays, boost::array or
316
 
   * std::vector.
317
 
   */
318
 
  template <typename ConstBufferSequence>
319
 
  std::size_t send_to(const ConstBufferSequence& buffers,
320
 
      const endpoint_type& destination)
321
 
  {
322
 
    asio::error_code ec;
323
 
    std::size_t s = this->service.send_to(
324
 
        this->implementation, buffers, destination, 0, ec);
325
 
    asio::detail::throw_error(ec);
326
 
    return s;
327
 
  }
328
 
 
329
 
  /// Send a datagram to the specified endpoint.
330
 
  /**
331
 
   * This function is used to send a datagram to the specified remote endpoint.
332
 
   * The function call will block until the data has been sent successfully or
333
 
   * an error occurs.
334
 
   *
335
 
   * @param buffers One or more data buffers to be sent to the remote endpoint.
336
 
   *
337
 
   * @param destination The remote endpoint to which the data will be sent.
338
 
   *
339
 
   * @param flags Flags specifying how the send call is to be made.
340
 
   *
341
 
   * @returns The number of bytes sent.
342
 
   *
343
 
   * @throws asio::system_error Thrown on failure.
344
 
   */
345
 
  template <typename ConstBufferSequence>
346
 
  std::size_t send_to(const ConstBufferSequence& buffers,
347
 
      const endpoint_type& destination, socket_base::message_flags flags)
348
 
  {
349
 
    asio::error_code ec;
350
 
    std::size_t s = this->service.send_to(
351
 
        this->implementation, buffers, destination, flags, ec);
352
 
    asio::detail::throw_error(ec);
353
 
    return s;
354
 
  }
355
 
 
356
 
  /// Send a datagram to the specified endpoint.
357
 
  /**
358
 
   * This function is used to send a datagram to the specified remote endpoint.
359
 
   * The function call will block until the data has been sent successfully or
360
 
   * an error occurs.
361
 
   *
362
 
   * @param buffers One or more data buffers to be sent to the remote endpoint.
363
 
   *
364
 
   * @param destination The remote endpoint to which the data will be sent.
365
 
   *
366
 
   * @param flags Flags specifying how the send call is to be made.
367
 
   *
368
 
   * @param ec Set to indicate what error occurred, if any.
369
 
   *
370
 
   * @returns The number of bytes sent.
371
 
   */
372
 
  template <typename ConstBufferSequence>
373
 
  std::size_t send_to(const ConstBufferSequence& buffers,
374
 
      const endpoint_type& destination, socket_base::message_flags flags,
375
 
      asio::error_code& ec)
376
 
  {
377
 
    return this->service.send_to(this->implementation,
378
 
        buffers, destination, flags, ec);
379
 
  }
380
 
 
381
 
  /// Start an asynchronous send.
382
 
  /**
383
 
   * This function is used to asynchronously send a datagram to the specified
384
 
   * remote endpoint. The function call always returns immediately.
385
 
   *
386
 
   * @param buffers One or more data buffers to be sent to the remote endpoint.
387
 
   * Although the buffers object may be copied as necessary, ownership of the
388
 
   * underlying memory blocks is retained by the caller, which must guarantee
389
 
   * that they remain valid until the handler is called.
390
 
   *
391
 
   * @param destination The remote endpoint to which the data will be sent.
392
 
   * Copies will be made of the endpoint as required.
393
 
   *
394
 
   * @param handler The handler to be called when the send operation completes.
395
 
   * Copies will be made of the handler as required. The function signature of
396
 
   * the handler must be:
397
 
   * @code void handler(
398
 
   *   const asio::error_code& error, // Result of operation.
399
 
   *   std::size_t bytes_transferred           // Number of bytes sent.
400
 
   * ); @endcode
401
 
   * Regardless of whether the asynchronous operation completes immediately or
402
 
   * not, the handler will not be invoked from within this function. Invocation
403
 
   * of the handler will be performed in a manner equivalent to using
404
 
   * asio::io_service::post().
405
 
   *
406
 
   * @par Example
407
 
   * To send a single data buffer use the @ref buffer function as follows:
408
 
   * @code
409
 
   * asio::ip::udp::endpoint destination(
410
 
   *     asio::ip::address::from_string("1.2.3.4"), 12345);
411
 
   * socket.async_send_to(
412
 
   *     asio::buffer(data, size), destination, handler);
413
 
   * @endcode
414
 
   * See the @ref buffer documentation for information on sending multiple
415
 
   * buffers in one go, and how to use it with arrays, boost::array or
416
 
   * std::vector.
417
 
   */
418
 
  template <typename ConstBufferSequence, typename WriteHandler>
419
 
  void async_send_to(const ConstBufferSequence& buffers,
420
 
      const endpoint_type& destination, WriteHandler handler)
421
 
  {
422
 
    this->service.async_send_to(this->implementation, buffers, destination, 0,
423
 
        handler);
424
 
  }
425
 
 
426
 
  /// Start an asynchronous send.
427
 
  /**
428
 
   * This function is used to asynchronously send a datagram to the specified
429
 
   * remote endpoint. The function call always returns immediately.
430
 
   *
431
 
   * @param buffers One or more data buffers to be sent to the remote endpoint.
432
 
   * Although the buffers object may be copied as necessary, ownership of the
433
 
   * underlying memory blocks is retained by the caller, which must guarantee
434
 
   * that they remain valid until the handler is called.
435
 
   *
436
 
   * @param flags Flags specifying how the send call is to be made.
437
 
   *
438
 
   * @param destination The remote endpoint to which the data will be sent.
439
 
   * Copies will be made of the endpoint as required.
440
 
   *
441
 
   * @param handler The handler to be called when the send operation completes.
442
 
   * Copies will be made of the handler as required. The function signature of
443
 
   * the handler must be:
444
 
   * @code void handler(
445
 
   *   const asio::error_code& error, // Result of operation.
446
 
   *   std::size_t bytes_transferred           // Number of bytes sent.
447
 
   * ); @endcode
448
 
   * Regardless of whether the asynchronous operation completes immediately or
449
 
   * not, the handler will not be invoked from within this function. Invocation
450
 
   * of the handler will be performed in a manner equivalent to using
451
 
   * asio::io_service::post().
452
 
   */
453
 
  template <typename ConstBufferSequence, typename WriteHandler>
454
 
  void async_send_to(const ConstBufferSequence& buffers,
455
 
      const endpoint_type& destination, socket_base::message_flags flags,
456
 
      WriteHandler handler)
457
 
  {
458
 
    this->service.async_send_to(this->implementation, buffers, destination,
459
 
        flags, handler);
460
 
  }
461
 
 
462
 
  /// Receive some data on a connected socket.
463
 
  /**
464
 
   * This function is used to receive data on the datagram socket. The function
465
 
   * call will block until data has been received successfully or an error
466
 
   * occurs.
467
 
   *
468
 
   * @param buffers One or more buffers into which the data will be received.
469
 
   *
470
 
   * @returns The number of bytes received.
471
 
   *
472
 
   * @throws asio::system_error Thrown on failure.
473
 
   *
474
 
   * @note The receive operation can only be used with a connected socket. Use
475
 
   * the receive_from function to receive data on an unconnected datagram
476
 
   * socket.
477
 
   *
478
 
   * @par Example
479
 
   * To receive into a single data buffer use the @ref buffer function as
480
 
   * follows:
481
 
   * @code socket.receive(asio::buffer(data, size)); @endcode
482
 
   * See the @ref buffer documentation for information on receiving into
483
 
   * multiple buffers in one go, and how to use it with arrays, boost::array or
484
 
   * std::vector.
485
 
   */
486
 
  template <typename MutableBufferSequence>
487
 
  std::size_t receive(const MutableBufferSequence& buffers)
488
 
  {
489
 
    asio::error_code ec;
490
 
    std::size_t s = this->service.receive(
491
 
        this->implementation, buffers, 0, ec);
492
 
    asio::detail::throw_error(ec);
493
 
    return s;
494
 
  }
495
 
 
496
 
  /// Receive some data on a connected socket.
497
 
  /**
498
 
   * This function is used to receive data on the datagram socket. The function
499
 
   * call will block until data has been received successfully or an error
500
 
   * occurs.
501
 
   *
502
 
   * @param buffers One or more buffers into which the data will be received.
503
 
   *
504
 
   * @param flags Flags specifying how the receive call is to be made.
505
 
   *
506
 
   * @returns The number of bytes received.
507
 
   *
508
 
   * @throws asio::system_error Thrown on failure.
509
 
   *
510
 
   * @note The receive operation can only be used with a connected socket. Use
511
 
   * the receive_from function to receive data on an unconnected datagram
512
 
   * socket.
513
 
   */
514
 
  template <typename MutableBufferSequence>
515
 
  std::size_t receive(const MutableBufferSequence& buffers,
516
 
      socket_base::message_flags flags)
517
 
  {
518
 
    asio::error_code ec;
519
 
    std::size_t s = this->service.receive(
520
 
        this->implementation, buffers, flags, ec);
521
 
    asio::detail::throw_error(ec);
522
 
    return s;
523
 
  }
524
 
 
525
 
  /// Receive some data on a connected socket.
526
 
  /**
527
 
   * This function is used to receive data on the datagram socket. The function
528
 
   * call will block until data has been received successfully or an error
529
 
   * occurs.
530
 
   *
531
 
   * @param buffers One or more buffers into which the data will be received.
532
 
   *
533
 
   * @param flags Flags specifying how the receive call is to be made.
534
 
   *
535
 
   * @param ec Set to indicate what error occurred, if any.
536
 
   *
537
 
   * @returns The number of bytes received.
538
 
   *
539
 
   * @note The receive operation can only be used with a connected socket. Use
540
 
   * the receive_from function to receive data on an unconnected datagram
541
 
   * socket.
542
 
   */
543
 
  template <typename MutableBufferSequence>
544
 
  std::size_t receive(const MutableBufferSequence& buffers,
545
 
      socket_base::message_flags flags, asio::error_code& ec)
546
 
  {
547
 
    return this->service.receive(this->implementation, buffers, flags, ec);
548
 
  }
549
 
 
550
 
  /// Start an asynchronous receive on a connected socket.
551
 
  /**
552
 
   * This function is used to asynchronously receive data from the datagram
553
 
   * socket. The function call always returns immediately.
554
 
   *
555
 
   * @param buffers One or more buffers into which the data will be received.
556
 
   * Although the buffers object may be copied as necessary, ownership of the
557
 
   * underlying memory blocks is retained by the caller, which must guarantee
558
 
   * that they remain valid until the handler is called.
559
 
   *
560
 
   * @param handler The handler to be called when the receive operation
561
 
   * completes. Copies will be made of the handler as required. The function
562
 
   * signature of the handler must be:
563
 
   * @code void handler(
564
 
   *   const asio::error_code& error, // Result of operation.
565
 
   *   std::size_t bytes_transferred           // Number of bytes received.
566
 
   * ); @endcode
567
 
   * Regardless of whether the asynchronous operation completes immediately or
568
 
   * not, the handler will not be invoked from within this function. Invocation
569
 
   * of the handler will be performed in a manner equivalent to using
570
 
   * asio::io_service::post().
571
 
   *
572
 
   * @note The async_receive operation can only be used with a connected socket.
573
 
   * Use the async_receive_from function to receive data on an unconnected
574
 
   * datagram socket.
575
 
   *
576
 
   * @par Example
577
 
   * To receive into a single data buffer use the @ref buffer function as
578
 
   * follows:
579
 
   * @code
580
 
   * socket.async_receive(asio::buffer(data, size), handler);
581
 
   * @endcode
582
 
   * See the @ref buffer documentation for information on receiving into
583
 
   * multiple buffers in one go, and how to use it with arrays, boost::array or
584
 
   * std::vector.
585
 
   */
586
 
  template <typename MutableBufferSequence, typename ReadHandler>
587
 
  void async_receive(const MutableBufferSequence& buffers, ReadHandler handler)
588
 
  {
589
 
    this->service.async_receive(this->implementation, buffers, 0, handler);
590
 
  }
591
 
 
592
 
  /// Start an asynchronous receive on a connected socket.
593
 
  /**
594
 
   * This function is used to asynchronously receive data from the datagram
595
 
   * socket. The function call always returns immediately.
596
 
   *
597
 
   * @param buffers One or more buffers into which the data will be received.
598
 
   * Although the buffers object may be copied as necessary, ownership of the
599
 
   * underlying memory blocks is retained by the caller, which must guarantee
600
 
   * that they remain valid until the handler is called.
601
 
   *
602
 
   * @param flags Flags specifying how the receive call is to be made.
603
 
   *
604
 
   * @param handler The handler to be called when the receive operation
605
 
   * completes. Copies will be made of the handler as required. The function
606
 
   * signature of the handler must be:
607
 
   * @code void handler(
608
 
   *   const asio::error_code& error, // Result of operation.
609
 
   *   std::size_t bytes_transferred           // Number of bytes received.
610
 
   * ); @endcode
611
 
   * Regardless of whether the asynchronous operation completes immediately or
612
 
   * not, the handler will not be invoked from within this function. Invocation
613
 
   * of the handler will be performed in a manner equivalent to using
614
 
   * asio::io_service::post().
615
 
   *
616
 
   * @note The async_receive operation can only be used with a connected socket.
617
 
   * Use the async_receive_from function to receive data on an unconnected
618
 
   * datagram socket.
619
 
   */
620
 
  template <typename MutableBufferSequence, typename ReadHandler>
621
 
  void async_receive(const MutableBufferSequence& buffers,
622
 
      socket_base::message_flags flags, ReadHandler handler)
623
 
  {
624
 
    this->service.async_receive(this->implementation, buffers, flags, handler);
625
 
  }
626
 
 
627
 
  /// Receive a datagram with the endpoint of the sender.
628
 
  /**
629
 
   * This function is used to receive a datagram. The function call will block
630
 
   * until data has been received successfully or an error occurs.
631
 
   *
632
 
   * @param buffers One or more buffers into which the data will be received.
633
 
   *
634
 
   * @param sender_endpoint An endpoint object that receives the endpoint of
635
 
   * the remote sender of the datagram.
636
 
   *
637
 
   * @returns The number of bytes received.
638
 
   *
639
 
   * @throws asio::system_error Thrown on failure.
640
 
   *
641
 
   * @par Example
642
 
   * To receive into a single data buffer use the @ref buffer function as
643
 
   * follows:
644
 
   * @code
645
 
   * asio::ip::udp::endpoint sender_endpoint;
646
 
   * socket.receive_from(
647
 
   *     asio::buffer(data, size), sender_endpoint);
648
 
   * @endcode
649
 
   * See the @ref buffer documentation for information on receiving into
650
 
   * multiple buffers in one go, and how to use it with arrays, boost::array or
651
 
   * std::vector.
652
 
   */
653
 
  template <typename MutableBufferSequence>
654
 
  std::size_t receive_from(const MutableBufferSequence& buffers,
655
 
      endpoint_type& sender_endpoint)
656
 
  {
657
 
    asio::error_code ec;
658
 
    std::size_t s = this->service.receive_from(
659
 
        this->implementation, buffers, sender_endpoint, 0, ec);
660
 
    asio::detail::throw_error(ec);
661
 
    return s;
662
 
  }
663
 
  
664
 
  /// Receive a datagram with the endpoint of the sender.
665
 
  /**
666
 
   * This function is used to receive a datagram. The function call will block
667
 
   * until data has been received successfully or an error occurs.
668
 
   *
669
 
   * @param buffers One or more buffers into which the data will be received.
670
 
   *
671
 
   * @param sender_endpoint An endpoint object that receives the endpoint of
672
 
   * the remote sender of the datagram.
673
 
   *
674
 
   * @param flags Flags specifying how the receive call is to be made.
675
 
   *
676
 
   * @returns The number of bytes received.
677
 
   *
678
 
   * @throws asio::system_error Thrown on failure.
679
 
   */
680
 
  template <typename MutableBufferSequence>
681
 
  std::size_t receive_from(const MutableBufferSequence& buffers,
682
 
      endpoint_type& sender_endpoint, socket_base::message_flags flags)
683
 
  {
684
 
    asio::error_code ec;
685
 
    std::size_t s = this->service.receive_from(
686
 
        this->implementation, buffers, sender_endpoint, flags, ec);
687
 
    asio::detail::throw_error(ec);
688
 
    return s;
689
 
  }
690
 
  
691
 
  /// Receive a datagram with the endpoint of the sender.
692
 
  /**
693
 
   * This function is used to receive a datagram. The function call will block
694
 
   * until data has been received successfully or an error occurs.
695
 
   *
696
 
   * @param buffers One or more buffers into which the data will be received.
697
 
   *
698
 
   * @param sender_endpoint An endpoint object that receives the endpoint of
699
 
   * the remote sender of the datagram.
700
 
   *
701
 
   * @param flags Flags specifying how the receive call is to be made.
702
 
   *
703
 
   * @param ec Set to indicate what error occurred, if any.
704
 
   *
705
 
   * @returns The number of bytes received.
706
 
   */
707
 
  template <typename MutableBufferSequence>
708
 
  std::size_t receive_from(const MutableBufferSequence& buffers,
709
 
      endpoint_type& sender_endpoint, socket_base::message_flags flags,
710
 
      asio::error_code& ec)
711
 
  {
712
 
    return this->service.receive_from(this->implementation, buffers,
713
 
        sender_endpoint, flags, ec);
714
 
  }
715
 
 
716
 
  /// Start an asynchronous receive.
717
 
  /**
718
 
   * This function is used to asynchronously receive a datagram. The function
719
 
   * call always returns immediately.
720
 
   *
721
 
   * @param buffers One or more buffers into which the data will be received.
722
 
   * Although the buffers object may be copied as necessary, ownership of the
723
 
   * underlying memory blocks is retained by the caller, which must guarantee
724
 
   * that they remain valid until the handler is called.
725
 
   *
726
 
   * @param sender_endpoint An endpoint object that receives the endpoint of
727
 
   * the remote sender of the datagram. Ownership of the sender_endpoint object
728
 
   * is retained by the caller, which must guarantee that it is valid until the
729
 
   * handler is called.
730
 
   *
731
 
   * @param handler The handler to be called when the receive operation
732
 
   * completes. Copies will be made of the handler as required. The function
733
 
   * signature of the handler must be:
734
 
   * @code void handler(
735
 
   *   const asio::error_code& error, // Result of operation.
736
 
   *   std::size_t bytes_transferred           // Number of bytes received.
737
 
   * ); @endcode
738
 
   * Regardless of whether the asynchronous operation completes immediately or
739
 
   * not, the handler will not be invoked from within this function. Invocation
740
 
   * of the handler will be performed in a manner equivalent to using
741
 
   * asio::io_service::post().
742
 
   *
743
 
   * @par Example
744
 
   * To receive into a single data buffer use the @ref buffer function as
745
 
   * follows:
746
 
   * @code socket.async_receive_from(
747
 
   *     asio::buffer(data, size), 0, sender_endpoint, handler); @endcode
748
 
   * See the @ref buffer documentation for information on receiving into
749
 
   * multiple buffers in one go, and how to use it with arrays, boost::array or
750
 
   * std::vector.
751
 
   */
752
 
  template <typename MutableBufferSequence, typename ReadHandler>
753
 
  void async_receive_from(const MutableBufferSequence& buffers,
754
 
      endpoint_type& sender_endpoint, ReadHandler handler)
755
 
  {
756
 
    this->service.async_receive_from(this->implementation, buffers,
757
 
        sender_endpoint, 0, handler);
758
 
  }
759
 
 
760
 
  /// Start an asynchronous receive.
761
 
  /**
762
 
   * This function is used to asynchronously receive a datagram. The function
763
 
   * call always returns immediately.
764
 
   *
765
 
   * @param buffers One or more buffers into which the data will be received.
766
 
   * Although the buffers object may be copied as necessary, ownership of the
767
 
   * underlying memory blocks is retained by the caller, which must guarantee
768
 
   * that they remain valid until the handler is called.
769
 
   *
770
 
   * @param sender_endpoint An endpoint object that receives the endpoint of
771
 
   * the remote sender of the datagram. Ownership of the sender_endpoint object
772
 
   * is retained by the caller, which must guarantee that it is valid until the
773
 
   * handler is called.
774
 
   *
775
 
   * @param flags Flags specifying how the receive call is to be made.
776
 
   *
777
 
   * @param handler The handler to be called when the receive operation
778
 
   * completes. Copies will be made of the handler as required. The function
779
 
   * signature of the handler must be:
780
 
   * @code void handler(
781
 
   *   const asio::error_code& error, // Result of operation.
782
 
   *   std::size_t bytes_transferred           // Number of bytes received.
783
 
   * ); @endcode
784
 
   * Regardless of whether the asynchronous operation completes immediately or
785
 
   * not, the handler will not be invoked from within this function. Invocation
786
 
   * of the handler will be performed in a manner equivalent to using
787
 
   * asio::io_service::post().
788
 
   */
789
 
  template <typename MutableBufferSequence, typename ReadHandler>
790
 
  void async_receive_from(const MutableBufferSequence& buffers,
791
 
      endpoint_type& sender_endpoint, socket_base::message_flags flags,
792
 
      ReadHandler handler)
793
 
  {
794
 
    this->service.async_receive_from(this->implementation, buffers,
795
 
        sender_endpoint, flags, handler);
796
 
  }
797
 
};
798
 
 
799
 
} // namespace asio
800
 
 
801
 
#include "asio/detail/pop_options.hpp"
802
 
 
803
 
#endif // ASIO_BASIC_DATAGRAM_SOCKET_HPP