← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjlib/include/pj/activesock.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjlib/include/pj/activesock.h
1
 
/* $Id: activesock.h 3553 2011-05-05 06:14:19Z nanang $ */
2
 
/*
3
 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
 
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5
 
 *
6
 
 * This program is free software; you can redistribute it and/or modify
7
 
 * it under the terms of the GNU General Public License as published by
8
 
 * the Free Software Foundation; either version 2 of the License, or
9
 
 * (at your option) any later version.
10
 
 *
11
 
 * This program is distributed in the hope that it will be useful,
12
 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13
 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
 
 * GNU General Public License for more details.
15
 
 *
16
 
 * You should have received a copy of the GNU General Public License
17
 
 * along with this program; if not, write to the Free Software
18
 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19
 
 */
20
 
#ifndef __PJ_ASYNCSOCK_H__
21
 
#define __PJ_ASYNCSOCK_H__
22
 
 
23
 
/**
24
 
 * @file activesock.h
25
 
 * @brief Active socket
26
 
 */
27
 
 
28
 
#include <pj/ioqueue.h>
29
 
#include <pj/sock.h>
30
 
 
31
 
 
32
 
PJ_BEGIN_DECL
33
 
 
34
 
/**
35
 
 * @defgroup PJ_ACTIVESOCK Active socket I/O
36
 
 * @brief Active socket performs active operations on socket.
37
 
 * @ingroup PJ_IO
38
 
 * @{
39
 
 *
40
 
 * Active socket is a higher level abstraction to the ioqueue. It provides
41
 
 * automation to socket operations which otherwise would have to be done
42
 
 * manually by the applications. For example with socket recv(), recvfrom(),
43
 
 * and accept() operations, application only needs to invoke these
44
 
 * operation once, and it will be notified whenever data or incoming TCP
45
 
 * connection (in the case of accept()) arrives.
46
 
 */
47
 
 
48
 
/**
49
 
 * This opaque structure describes the active socket.
50
 
 */
51
 
typedef struct pj_activesock_t pj_activesock_t;
52
 
 
53
 
/**
54
 
 * This structure contains the callbacks to be called by the active socket.
55
 
 */
56
 
typedef struct pj_activesock_cb
57
 
{
58
 
    /**
59
 
     * This callback is called when a data arrives as the result of
60
 
     * pj_activesock_start_read().
61
 
     *
62
 
     * @param asock     The active socket.
63
 
     * @param data      The buffer containing the new data, if any. If
64
 
     *                  the status argument is non-PJ_SUCCESS, this
65
 
     *                  argument may be NULL.
66
 
     * @param size      The length of data in the buffer.
67
 
     * @param status    The status of the read operation. This may contain
68
 
     *                  non-PJ_SUCCESS for example when the TCP connection
69
 
     *                  has been closed. In this case, the buffer may
70
 
     *                  contain left over data from previous callback which
71
 
     *                  the application may want to process.
72
 
     * @param remainder If application wishes to leave some data in the
73
 
     *                  buffer (common for TCP applications), it should
74
 
     *                  move the remainder data to the front part of the
75
 
     *                  buffer and set the remainder length here. The value
76
 
     *                  of this parameter will be ignored for datagram
77
 
     *                  sockets.
78
 
     *
79
 
     * @return          PJ_TRUE if further read is desired, and PJ_FALSE
80
 
     *                  when application no longer wants to receive data.
81
 
     *                  Application may destroy the active socket in the
82
 
     *                  callback and return PJ_FALSE here.
83
 
     */
84
 
    pj_bool_t (*on_data_read)(pj_activesock_t *asock,
85
 
                              void *data,
86
 
                              pj_size_t size,
87
 
                              pj_status_t status,
88
 
                              pj_size_t *remainder);
89
 
    /**
90
 
     * This callback is called when a packet arrives as the result of
91
 
     * pj_activesock_start_recvfrom().
92
 
     *
93
 
     * @param asock     The active socket.
94
 
     * @param data      The buffer containing the packet, if any. If
95
 
     *                  the status argument is non-PJ_SUCCESS, this
96
 
     *                  argument will be set to NULL.
97
 
     * @param size      The length of packet in the buffer. If
98
 
     *                  the status argument is non-PJ_SUCCESS, this
99
 
     *                  argument will be set to zero.
100
 
     * @param src_addr  Source address of the packet.
101
 
     * @param addr_len  Length of the source address.
102
 
     * @param status    This contains
103
 
     *
104
 
     * @return          PJ_TRUE if further read is desired, and PJ_FALSE
105
 
     *                  when application no longer wants to receive data.
106
 
     *                  Application may destroy the active socket in the
107
 
     *                  callback and return PJ_FALSE here.
108
 
     */
109
 
    pj_bool_t (*on_data_recvfrom)(pj_activesock_t *asock,
110
 
                                  void *data,
111
 
                                  pj_size_t size,
112
 
                                  const pj_sockaddr_t *src_addr,
113
 
                                  int addr_len,
114
 
                                  pj_status_t status);
115
 
 
116
 
    /**
117
 
     * This callback is called when data has been sent.
118
 
     *
119
 
     * @param asock     The active socket.
120
 
     * @param send_key  Key associated with the send operation.
121
 
     * @param sent      If value is positive non-zero it indicates the
122
 
     *                  number of data sent. When the value is negative,
123
 
     *                  it contains the error code which can be retrieved
124
 
     *                  by negating the value (i.e. status=-sent).
125
 
     *
126
 
     * @return          Application may destroy the active socket in the
127
 
     *                  callback and return PJ_FALSE here.
128
 
     */
129
 
    pj_bool_t (*on_data_sent)(pj_activesock_t *asock,
130
 
                              pj_ioqueue_op_key_t *send_key,
131
 
                              pj_ssize_t sent);
132
 
 
133
 
    /**
134
 
     * This callback is called when new connection arrives as the result
135
 
     * of pj_activesock_start_accept().
136
 
     *
137
 
     * @param asock     The active socket.
138
 
     * @param newsock   The new incoming socket.
139
 
     * @param src_addr  The source address of the connection.
140
 
     * @param addr_len  Length of the source address.
141
 
     *
142
 
     * @return          PJ_TRUE if further accept() is desired, and PJ_FALSE
143
 
     *                  when application no longer wants to accept incoming
144
 
     *                  connection. Application may destroy the active socket
145
 
     *                  in the callback and return PJ_FALSE here.
146
 
     */
147
 
    pj_bool_t (*on_accept_complete)(pj_activesock_t *asock,
148
 
                                    pj_sock_t newsock,
149
 
                                    const pj_sockaddr_t *src_addr,
150
 
                                    int src_addr_len);
151
 
 
152
 
    /**
153
 
     * This callback is called when pending connect operation has been
154
 
     * completed.
155
 
     *
156
 
     * @param asock     The active  socket.
157
 
     * @param status    The connection result. If connection has been
158
 
     *                  successfully established, the status will contain
159
 
     *                  PJ_SUCCESS.
160
 
     *
161
 
     * @return          Application may destroy the active socket in the
162
 
     *                  callback and return PJ_FALSE here.
163
 
     */
164
 
    pj_bool_t (*on_connect_complete)(pj_activesock_t *asock,
165
 
                                     pj_status_t status);
166
 
 
167
 
} pj_activesock_cb;
168
 
 
169
 
 
170
 
/**
171
 
 * Settings that can be given during active socket creation. Application
172
 
 * must initialize this structure with #pj_activesock_cfg_default().
173
 
 */
174
 
typedef struct pj_activesock_cfg
175
 
{
176
 
    /**
177
 
     * Number of concurrent asynchronous operations that is to be supported
178
 
     * by the active socket. This value only affects socket receive and
179
 
     * accept operations -- the active socket will issue one or more
180
 
     * asynchronous read and accept operations based on the value of this
181
 
     * field. Setting this field to more than one will allow more than one
182
 
     * incoming data or incoming connections to be processed simultaneously
183
 
     * on multiprocessor systems, when the ioqueue is polled by more than
184
 
     * one threads.
185
 
     *
186
 
     * The default value is 1.
187
 
     */
188
 
    unsigned async_cnt;
189
 
 
190
 
    /**
191
 
     * The ioqueue concurrency to be forced on the socket when it is
192
 
     * registered to the ioqueue. See #pj_ioqueue_set_concurrency() for more
193
 
     * info about ioqueue concurrency.
194
 
     *
195
 
     * When this value is -1, the concurrency setting will not be forced for
196
 
     * this socket, and the socket will inherit the concurrency setting of
197
 
     * the ioqueue. When this value is zero, the active socket will disable
198
 
     * concurrency for the socket. When this value is +1, the active socket
199
 
     * will enable concurrency for the socket.
200
 
     *
201
 
     * The default value is -1.
202
 
     */
203
 
    int concurrency;
204
 
 
205
 
    /**
206
 
     * If this option is specified, the active socket will make sure that
207
 
     * asynchronous send operation with stream oriented socket will only
208
 
     * call the callback after all data has been sent. This means that the
209
 
     * active socket will automatically resend the remaining data until
210
 
     * all data has been sent.
211
 
     *
212
 
     * Please note that when this option is specified, it is possible that
213
 
     * error is reported after partial data has been sent. Also setting
214
 
     * this will disable the ioqueue concurrency for the socket.
215
 
     *
216
 
     * Default value is 1.
217
 
     */
218
 
    pj_bool_t whole_data;
219
 
 
220
 
} pj_activesock_cfg;
221
 
 
222
 
 
223
 
/**
224
 
 * Initialize the active socket configuration with the default values.
225
 
 *
226
 
 * @param cfg           The configuration to be initialized.
227
 
 */
228
 
PJ_DECL(void) pj_activesock_cfg_default(pj_activesock_cfg *cfg);
229
 
 
230
 
 
231
 
/**
232
 
 * Create the active socket for the specified socket. This will register
233
 
 * the socket to the specified ioqueue.
234
 
 *
235
 
 * @param pool          Pool to allocate memory from.
236
 
 * @param sock          The socket handle.
237
 
 * @param sock_type     Specify socket type, either pj_SOCK_DGRAM() or
238
 
 *                      pj_SOCK_STREAM(). The active socket needs this
239
 
 *                      information to handle connection closure for
240
 
 *                      connection oriented sockets.
241
 
 * @param ioqueue       The ioqueue to use.
242
 
 * @param opt           Optional settings. When this setting is not specifed,
243
 
 *                      the default values will be used.
244
 
 * @param cb            Pointer to structure containing application
245
 
 *                      callbacks.
246
 
 * @param user_data     Arbitrary user data to be associated with this
247
 
 *                      active socket.
248
 
 * @param p_asock       Pointer to receive the active socket instance.
249
 
 *
250
 
 * @return              PJ_SUCCESS if the operation has been successful,
251
 
 *                      or the appropriate error code on failure.
252
 
 */
253
 
PJ_DECL(pj_status_t) pj_activesock_create(pj_pool_t *pool,
254
 
                                          pj_sock_t sock,
255
 
                                          int sock_type,
256
 
                                          const pj_activesock_cfg *opt,
257
 
                                          pj_ioqueue_t *ioqueue,
258
 
                                          const pj_activesock_cb *cb,
259
 
                                          void *user_data,
260
 
                                          pj_activesock_t **p_asock);
261
 
 
262
 
/**
263
 
 * Create UDP socket descriptor, bind it to the specified address, and
264
 
 * create the active socket for the socket descriptor.
265
 
 *
266
 
 * @param pool          Pool to allocate memory from.
267
 
 * @param addr          Specifies the address family of the socket and the
268
 
 *                      address where the socket should be bound to. If
269
 
 *                      this argument is NULL, then AF_INET is assumed and
270
 
 *                      the socket will be bound to any addresses and port.
271
 
 * @param opt           Optional settings. When this setting is not specifed,
272
 
 *                      the default values will be used.
273
 
 * @param cb            Pointer to structure containing application
274
 
 *                      callbacks.
275
 
 * @param user_data     Arbitrary user data to be associated with this
276
 
 *                      active socket.
277
 
 * @param p_asock       Pointer to receive the active socket instance.
278
 
 * @param bound_addr    If this argument is specified, it will be filled with
279
 
 *                      the bound address on return.
280
 
 *
281
 
 * @return              PJ_SUCCESS if the operation has been successful,
282
 
 *                      or the appropriate error code on failure.
283
 
 */
284
 
PJ_DECL(pj_status_t) pj_activesock_create_udp(pj_pool_t *pool,
285
 
                                              const pj_sockaddr *addr,
286
 
                                              const pj_activesock_cfg *opt,
287
 
                                              pj_ioqueue_t *ioqueue,
288
 
                                              const pj_activesock_cb *cb,
289
 
                                              void *user_data,
290
 
                                              pj_activesock_t **p_asock,
291
 
                                              pj_sockaddr *bound_addr);
292
 
 
293
 
 
294
 
/**
295
 
 * Close the active socket. This will unregister the socket from the
296
 
 * ioqueue and ultimately close the socket.
297
 
 *
298
 
 * @param asock     The active socket.
299
 
 *
300
 
 * @return          PJ_SUCCESS if the operation has been successful,
301
 
 *                  or the appropriate error code on failure.
302
 
 */
303
 
PJ_DECL(pj_status_t) pj_activesock_close(pj_activesock_t *asock);
304
 
 
305
 
#if (defined(PJ_IPHONE_OS_HAS_MULTITASKING_SUPPORT) && \
306
 
     PJ_IPHONE_OS_HAS_MULTITASKING_SUPPORT!=0) || \
307
 
     defined(DOXYGEN)
308
 
/**
309
 
 * Set iPhone OS background mode setting. Setting to 1 will enable TCP
310
 
 * active socket to receive incoming data when application is in the
311
 
 * background. Setting to 0 will disable it. Default value of this
312
 
 * setting is PJ_ACTIVESOCK_TCP_IPHONE_OS_BG.
313
 
 *
314
 
 * This API is only available if PJ_IPHONE_OS_HAS_MULTITASKING_SUPPORT
315
 
 * is set to non-zero.
316
 
 *
317
 
 * @param asock     The active socket.
318
 
 * @param val       The value of background mode setting.
319
 
 *
320
 
 */
321
 
PJ_DECL(void) pj_activesock_set_iphone_os_bg(pj_activesock_t *asock,
322
 
                                             int val);
323
 
 
324
 
/**
325
 
 * Enable/disable support for iPhone OS background mode. This setting
326
 
 * will apply globally and will affect any active sockets created
327
 
 * afterwards, if you want to change the setting for a particular
328
 
 * active socket, use #pj_activesock_set_iphone_os_bg() instead.
329
 
 * By default, this setting is enabled.
330
 
 *
331
 
 * This API is only available if PJ_IPHONE_OS_HAS_MULTITASKING_SUPPORT
332
 
 * is set to non-zero.
333
 
 *
334
 
 * @param val       The value of global background mode setting.
335
 
 *
336
 
 */
337
 
PJ_DECL(void) pj_activesock_enable_iphone_os_bg(pj_bool_t val);
338
 
#endif
339
 
 
340
 
/**
341
 
 * Associate arbitrary data with the active socket. Application may
342
 
 * inspect this data in the callbacks and associate it with higher
343
 
 * level processing.
344
 
 *
345
 
 * @param asock     The active socket.
346
 
 * @param user_data The user data to be associated with the active
347
 
 *                  socket.
348
 
 *
349
 
 * @return          PJ_SUCCESS if the operation has been successful,
350
 
 *                  or the appropriate error code on failure.
351
 
 */
352
 
PJ_DECL(pj_status_t) pj_activesock_set_user_data(pj_activesock_t *asock,
353
 
                                                 void *user_data);
354
 
 
355
 
/**
356
 
 * Retrieve the user data previously associated with this active
357
 
 * socket.
358
 
 *
359
 
 * @param asock     The active socket.
360
 
 *
361
 
 * @return          The user data.
362
 
 */
363
 
PJ_DECL(void*) pj_activesock_get_user_data(pj_activesock_t *asock);
364
 
 
365
 
 
366
 
/**
367
 
 * Starts read operation on this active socket. This function will create
368
 
 * \a async_cnt number of buffers (the \a async_cnt parameter was given
369
 
 * in \a pj_activesock_create() function) where each buffer is \a buff_size
370
 
 * long. The buffers are allocated from the specified \a pool. Once the
371
 
 * buffers are created, it then issues \a async_cnt number of asynchronous
372
 
 * \a recv() operations to the socket and returns back to caller. Incoming
373
 
 * data on the socket will be reported back to application via the
374
 
 * \a on_data_read() callback.
375
 
 *
376
 
 * Application only needs to call this function once to initiate read
377
 
 * operations. Further read operations will be done automatically by the
378
 
 * active socket when \a on_data_read() callback returns non-zero.
379
 
 *
380
 
 * @param asock     The active socket.
381
 
 * @param pool      Pool used to allocate buffers for incoming data.
382
 
 * @param buff_size The size of each buffer, in bytes.
383
 
 * @param flags     Flags to be given to pj_ioqueue_recv().
384
 
 *
385
 
 * @return          PJ_SUCCESS if the operation has been successful,
386
 
 *                  or the appropriate error code on failure.
387
 
 */
388
 
PJ_DECL(pj_status_t) pj_activesock_start_read(pj_activesock_t *asock,
389
 
                                              pj_pool_t *pool,
390
 
                                              unsigned buff_size,
391
 
                                              pj_uint32_t flags);
392
 
 
393
 
/**
394
 
 * Same as #pj_activesock_start_read(), except that the application
395
 
 * supplies the buffers for the read operation so that the acive socket
396
 
 * does not have to allocate the buffers.
397
 
 *
398
 
 * @param asock     The active socket.
399
 
 * @param pool      Pool used to allocate buffers for incoming data.
400
 
 * @param buff_size The size of each buffer, in bytes.
401
 
 * @param readbuf   Array of packet buffers, each has buff_size size.
402
 
 * @param flags     Flags to be given to pj_ioqueue_recv().
403
 
 *
404
 
 * @return          PJ_SUCCESS if the operation has been successful,
405
 
 *                  or the appropriate error code on failure.
406
 
 */
407
 
PJ_DECL(pj_status_t) pj_activesock_start_read2(pj_activesock_t *asock,
408
 
                                               pj_pool_t *pool,
409
 
                                               unsigned buff_size,
410
 
                                               void *readbuf[],
411
 
                                               pj_uint32_t flags);
412
 
 
413
 
/**
414
 
 * Same as pj_activesock_start_read(), except that this function is used
415
 
 * only for datagram sockets, and it will trigger \a on_data_recvfrom()
416
 
 * callback instead.
417
 
 *
418
 
 * @param asock     The active socket.
419
 
 * @param pool      Pool used to allocate buffers for incoming data.
420
 
 * @param buff_size The size of each buffer, in bytes.
421
 
 * @param flags     Flags to be given to pj_ioqueue_recvfrom().
422
 
 *
423
 
 * @return          PJ_SUCCESS if the operation has been successful,
424
 
 *                  or the appropriate error code on failure.
425
 
 */
426
 
PJ_DECL(pj_status_t) pj_activesock_start_recvfrom(pj_activesock_t *asock,
427
 
                                                  pj_pool_t *pool,
428
 
                                                  unsigned buff_size,
429
 
                                                  pj_uint32_t flags);
430
 
 
431
 
/**
432
 
 * Same as #pj_activesock_start_recvfrom() except that the recvfrom()
433
 
 * operation takes the buffer from the argument rather than creating
434
 
 * new ones.
435
 
 *
436
 
 * @param asock     The active socket.
437
 
 * @param pool      Pool used to allocate buffers for incoming data.
438
 
 * @param buff_size The size of each buffer, in bytes.
439
 
 * @param readbuf   Array of packet buffers, each has buff_size size.
440
 
 * @param flags     Flags to be given to pj_ioqueue_recvfrom().
441
 
 *
442
 
 * @return          PJ_SUCCESS if the operation has been successful,
443
 
 *                  or the appropriate error code on failure.
444
 
 */
445
 
PJ_DECL(pj_status_t) pj_activesock_start_recvfrom2(pj_activesock_t *asock,
446
 
                                                   pj_pool_t *pool,
447
 
                                                   unsigned buff_size,
448
 
                                                   void *readbuf[],
449
 
                                                   pj_uint32_t flags);
450
 
 
451
 
/**
452
 
 * Send data using the socket.
453
 
 *
454
 
 * @param asock     The active socket.
455
 
 * @param send_key  The operation key to send the data, which is useful
456
 
 *                  if application wants to submit multiple pending
457
 
 *                  send operations and want to track which exact data
458
 
 *                  has been sent in the \a on_data_sent() callback.
459
 
 * @param data      The data to be sent. This data must remain valid
460
 
 *                  until the data has been sent.
461
 
 * @param size      The size of the data.
462
 
 * @param flags     Flags to be given to pj_ioqueue_send().
463
 
 *
464
 
 *
465
 
 * @return          PJ_SUCCESS if data has been sent immediately, or
466
 
 *                  PJ_EPENDING if data cannot be sent immediately. In
467
 
 *                  this case the \a on_data_sent() callback will be
468
 
 *                  called when data is actually sent. Any other return
469
 
 *                  value indicates error condition.
470
 
 */
471
 
PJ_DECL(pj_status_t) pj_activesock_send(pj_activesock_t *asock,
472
 
                                        pj_ioqueue_op_key_t *send_key,
473
 
                                        const void *data,
474
 
                                        pj_ssize_t *size,
475
 
                                        unsigned flags);
476
 
 
477
 
/**
478
 
 * Send datagram using the socket.
479
 
 *
480
 
 * @param asock     The active socket.
481
 
 * @param send_key  The operation key to send the data, which is useful
482
 
 *                  if application wants to submit multiple pending
483
 
 *                  send operations and want to track which exact data
484
 
 *                  has been sent in the \a on_data_sent() callback.
485
 
 * @param data      The data to be sent. This data must remain valid
486
 
 *                  until the data has been sent.
487
 
 * @param size      The size of the data.
488
 
 * @param flags     Flags to be given to pj_ioqueue_send().
489
 
 * @param addr      The destination address.
490
 
 * @param addr_len  The length of the address.
491
 
 *
492
 
 * @return          PJ_SUCCESS if data has been sent immediately, or
493
 
 *                  PJ_EPENDING if data cannot be sent immediately. In
494
 
 *                  this case the \a on_data_sent() callback will be
495
 
 *                  called when data is actually sent. Any other return
496
 
 *                  value indicates error condition.
497
 
 */
498
 
PJ_DECL(pj_status_t) pj_activesock_sendto(pj_activesock_t *asock,
499
 
                                          pj_ioqueue_op_key_t *send_key,
500
 
                                          const void *data,
501
 
                                          pj_ssize_t *size,
502
 
                                          unsigned flags,
503
 
                                          const pj_sockaddr_t *addr,
504
 
                                          int addr_len);
505
 
 
506
 
#if PJ_HAS_TCP
507
 
/**
508
 
 * Starts asynchronous socket accept() operations on this active socket.
509
 
 * Application must bind the socket before calling this function. This
510
 
 * function will issue \a async_cnt number of asynchronous \a accept()
511
 
 * operations to the socket and returns back to caller. Incoming
512
 
 * connection on the socket will be reported back to application via the
513
 
 * \a on_accept_complete() callback.
514
 
 *
515
 
 * Application only needs to call this function once to initiate accept()
516
 
 * operations. Further accept() operations will be done automatically by
517
 
 * the active socket when \a on_accept_complete() callback returns non-zero.
518
 
 *
519
 
 * @param asock     The active socket.
520
 
 * @param pool      Pool used to allocate some internal data for the
521
 
 *                  operation.
522
 
 *
523
 
 * @return          PJ_SUCCESS if the operation has been successful,
524
 
 *                  or the appropriate error code on failure.
525
 
 */
526
 
PJ_DECL(pj_status_t) pj_activesock_start_accept(pj_activesock_t *asock,
527
 
                                                pj_pool_t *pool);
528
 
 
529
 
/**
530
 
 * Starts asynchronous socket connect() operation for this socket. Once
531
 
 * the connection is done (either successfully or not), the
532
 
 * \a on_connect_complete() callback will be called.
533
 
 *
534
 
 * @param asock     The active socket.
535
 
 * @param pool      The pool to allocate some internal data for the
536
 
 *                  operation.
537
 
 * @param remaddr   Remote address.
538
 
 * @param addr_len  Length of the remote address.
539
 
 *
540
 
 * @return          PJ_SUCCESS if connection can be established immediately,
541
 
 *                  or PJ_EPENDING if connection cannot be established
542
 
 *                  immediately. In this case the \a on_connect_complete()
543
 
 *                  callback will be called when connection is complete.
544
 
 *                  Any other return value indicates error condition.
545
 
 */
546
 
PJ_DECL(pj_status_t) pj_activesock_start_connect(pj_activesock_t *asock,
547
 
                                                 pj_pool_t *pool,
548
 
                                                 const pj_sockaddr_t *remaddr,
549
 
                                                 int addr_len);
550
 
 
551
 
#endif  /* PJ_HAS_TCP */
552
 
 
553
 
/**
554
 
 * @}
555
 
 */
556
 
 
557
 
PJ_END_DECL
558
 
 
559
 
#endif  /* __PJ_ASYNCSOCK_H__ */