← Back to branch summary

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

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.2.1/pjlib/include/pj/activesock.h
 
1
/* $Id: activesock.h 4461 2013-04-05 03:02:19Z riza $ */
 
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(). If the status of accept operation is
 
136
     * needed use on_accept_complete2 instead of this callback.
 
137
     *
 
138
     * @param asock     The active socket.
 
139
     * @param newsock   The new incoming socket.
 
140
     * @param src_addr  The source address of the connection.
 
141
     * @param addr_len  Length of the source address.
 
142
     *
 
143
     * @return          PJ_TRUE if further accept() is desired, and PJ_FALSE
 
144
     *                  when application no longer wants to accept incoming
 
145
     *                  connection. Application may destroy the active socket
 
146
     *                  in the callback and return PJ_FALSE here.
 
147
     */
 
148
    pj_bool_t (*on_accept_complete)(pj_activesock_t *asock,
 
149
                                    pj_sock_t newsock,
 
150
                                    const pj_sockaddr_t *src_addr,
 
151
                                    int src_addr_len);
 
152
 
 
153
    /**
 
154
     * This callback is called when new connection arrives as the result
 
155
     * of pj_activesock_start_accept().
 
156
     *
 
157
     * @param asock     The active socket.
 
158
     * @param newsock   The new incoming socket.
 
159
     * @param src_addr  The source address of the connection.
 
160
     * @param addr_len  Length of the source address.
 
161
     * @param status    The status of the accept operation. This may contain
 
162
     *                  non-PJ_SUCCESS for example when the TCP listener is in
 
163
     *                  bad state for example on iOS platform after the
 
164
     *                  application waking up from background.
 
165
     *
 
166
     * @return          PJ_TRUE if further accept() is desired, and PJ_FALSE
 
167
     *                  when application no longer wants to accept incoming
 
168
     *                  connection. Application may destroy the active socket
 
169
     *                  in the callback and return PJ_FALSE here.
 
170
     */
 
171
    pj_bool_t (*on_accept_complete2)(pj_activesock_t *asock,
 
172
                                     pj_sock_t newsock,
 
173
                                     const pj_sockaddr_t *src_addr,
 
174
                                     int src_addr_len, 
 
175
                                     pj_status_t status);
 
176
 
 
177
    /**
 
178
     * This callback is called when pending connect operation has been
 
179
     * completed.
 
180
     *
 
181
     * @param asock     The active  socket.
 
182
     * @param status    The connection result. If connection has been
 
183
     *                  successfully established, the status will contain
 
184
     *                  PJ_SUCCESS.
 
185
     *
 
186
     * @return          Application may destroy the active socket in the
 
187
     *                  callback and return PJ_FALSE here. 
 
188
     */
 
189
    pj_bool_t (*on_connect_complete)(pj_activesock_t *asock,
 
190
                                     pj_status_t status);
 
191
 
 
192
} pj_activesock_cb;
 
193
 
 
194
 
 
195
/**
 
196
 * Settings that can be given during active socket creation. Application
 
197
 * must initialize this structure with #pj_activesock_cfg_default().
 
198
 */
 
199
typedef struct pj_activesock_cfg
 
200
{
 
201
    /**
 
202
     * Optional group lock to be assigned to the ioqueue key.
 
203
     */
 
204
    pj_grp_lock_t *grp_lock;
 
205
 
 
206
    /**
 
207
     * Number of concurrent asynchronous operations that is to be supported
 
208
     * by the active socket. This value only affects socket receive and
 
209
     * accept operations -- the active socket will issue one or more 
 
210
     * asynchronous read and accept operations based on the value of this
 
211
     * field. Setting this field to more than one will allow more than one
 
212
     * incoming data or incoming connections to be processed simultaneously
 
213
     * on multiprocessor systems, when the ioqueue is polled by more than
 
214
     * one threads.
 
215
     *
 
216
     * The default value is 1.
 
217
     */
 
218
    unsigned async_cnt;
 
219
 
 
220
    /**
 
221
     * The ioqueue concurrency to be forced on the socket when it is 
 
222
     * registered to the ioqueue. See #pj_ioqueue_set_concurrency() for more
 
223
     * info about ioqueue concurrency.
 
224
     *
 
225
     * When this value is -1, the concurrency setting will not be forced for
 
226
     * this socket, and the socket will inherit the concurrency setting of 
 
227
     * the ioqueue. When this value is zero, the active socket will disable
 
228
     * concurrency for the socket. When this value is +1, the active socket
 
229
     * will enable concurrency for the socket.
 
230
     *
 
231
     * The default value is -1.
 
232
     */
 
233
    int concurrency;
 
234
 
 
235
    /**
 
236
     * If this option is specified, the active socket will make sure that
 
237
     * asynchronous send operation with stream oriented socket will only
 
238
     * call the callback after all data has been sent. This means that the
 
239
     * active socket will automatically resend the remaining data until
 
240
     * all data has been sent.
 
241
     *
 
242
     * Please note that when this option is specified, it is possible that
 
243
     * error is reported after partial data has been sent. Also setting
 
244
     * this will disable the ioqueue concurrency for the socket.
 
245
     *
 
246
     * Default value is 1.
 
247
     */
 
248
    pj_bool_t whole_data;
 
249
 
 
250
} pj_activesock_cfg;
 
251
 
 
252
 
 
253
/**
 
254
 * Initialize the active socket configuration with the default values.
 
255
 *
 
256
 * @param cfg           The configuration to be initialized.
 
257
 */
 
258
PJ_DECL(void) pj_activesock_cfg_default(pj_activesock_cfg *cfg);
 
259
 
 
260
 
 
261
/**
 
262
 * Create the active socket for the specified socket. This will register
 
263
 * the socket to the specified ioqueue. 
 
264
 *
 
265
 * @param pool          Pool to allocate memory from.
 
266
 * @param sock          The socket handle.
 
267
 * @param sock_type     Specify socket type, either pj_SOCK_DGRAM() or
 
268
 *                      pj_SOCK_STREAM(). The active socket needs this
 
269
 *                      information to handle connection closure for
 
270
 *                      connection oriented sockets.
 
271
 * @param ioqueue       The ioqueue to use.
 
272
 * @param opt           Optional settings. When this setting is not specifed,
 
273
 *                      the default values will be used.
 
274
 * @param cb            Pointer to structure containing application
 
275
 *                      callbacks.
 
276
 * @param user_data     Arbitrary user data to be associated with this
 
277
 *                      active socket.
 
278
 * @param p_asock       Pointer to receive the active socket instance.
 
279
 *
 
280
 * @return              PJ_SUCCESS if the operation has been successful,
 
281
 *                      or the appropriate error code on failure.
 
282
 */
 
283
PJ_DECL(pj_status_t) pj_activesock_create(pj_pool_t *pool,
 
284
                                          pj_sock_t sock,
 
285
                                          int sock_type,
 
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
 
 
292
/**
 
293
 * Create UDP socket descriptor, bind it to the specified address, and 
 
294
 * create the active socket for the socket descriptor.
 
295
 *
 
296
 * @param pool          Pool to allocate memory from.
 
297
 * @param addr          Specifies the address family of the socket and the
 
298
 *                      address where the socket should be bound to. If
 
299
 *                      this argument is NULL, then AF_INET is assumed and
 
300
 *                      the socket will be bound to any addresses and port.
 
301
 * @param opt           Optional settings. When this setting is not specifed,
 
302
 *                      the default values will be used.
 
303
 * @param cb            Pointer to structure containing application
 
304
 *                      callbacks.
 
305
 * @param user_data     Arbitrary user data to be associated with this
 
306
 *                      active socket.
 
307
 * @param p_asock       Pointer to receive the active socket instance.
 
308
 * @param bound_addr    If this argument is specified, it will be filled with
 
309
 *                      the bound address on return.
 
310
 *
 
311
 * @return              PJ_SUCCESS if the operation has been successful,
 
312
 *                      or the appropriate error code on failure.
 
313
 */
 
314
PJ_DECL(pj_status_t) pj_activesock_create_udp(pj_pool_t *pool,
 
315
                                              const pj_sockaddr *addr,
 
316
                                              const pj_activesock_cfg *opt,
 
317
                                              pj_ioqueue_t *ioqueue,
 
318
                                              const pj_activesock_cb *cb,
 
319
                                              void *user_data,
 
320
                                              pj_activesock_t **p_asock,
 
321
                                              pj_sockaddr *bound_addr);
 
322
 
 
323
/**
 
324
 * Close the active socket. This will unregister the socket from the
 
325
 * ioqueue and ultimately close the socket.
 
326
 *
 
327
 * @param asock     The active socket.
 
328
 *
 
329
 * @return          PJ_SUCCESS if the operation has been successful,
 
330
 *                  or the appropriate error code on failure.
 
331
 */
 
332
PJ_DECL(pj_status_t) pj_activesock_close(pj_activesock_t *asock);
 
333
 
 
334
#if (defined(PJ_IPHONE_OS_HAS_MULTITASKING_SUPPORT) && \
 
335
     PJ_IPHONE_OS_HAS_MULTITASKING_SUPPORT!=0) || \
 
336
     defined(DOXYGEN)
 
337
/**
 
338
 * Set iPhone OS background mode setting. Setting to 1 will enable TCP
 
339
 * active socket to receive incoming data when application is in the
 
340
 * background. Setting to 0 will disable it. Default value of this
 
341
 * setting is PJ_ACTIVESOCK_TCP_IPHONE_OS_BG.
 
342
 *
 
343
 * This API is only available if PJ_IPHONE_OS_HAS_MULTITASKING_SUPPORT
 
344
 * is set to non-zero.
 
345
 *
 
346
 * @param asock     The active socket.
 
347
 * @param val       The value of background mode setting.
 
348
 *
 
349
 */
 
350
PJ_DECL(void) pj_activesock_set_iphone_os_bg(pj_activesock_t *asock,
 
351
                                             int val);
 
352
 
 
353
/**
 
354
 * Enable/disable support for iPhone OS background mode. This setting
 
355
 * will apply globally and will affect any active sockets created
 
356
 * afterwards, if you want to change the setting for a particular
 
357
 * active socket, use #pj_activesock_set_iphone_os_bg() instead.
 
358
 * By default, this setting is enabled.
 
359
 *
 
360
 * This API is only available if PJ_IPHONE_OS_HAS_MULTITASKING_SUPPORT
 
361
 * is set to non-zero.
 
362
 *
 
363
 * @param val       The value of global background mode setting.
 
364
 *
 
365
 */
 
366
PJ_DECL(void) pj_activesock_enable_iphone_os_bg(pj_bool_t val);
 
367
#endif
 
368
 
 
369
/**
 
370
 * Associate arbitrary data with the active socket. Application may
 
371
 * inspect this data in the callbacks and associate it with higher
 
372
 * level processing.
 
373
 *
 
374
 * @param asock     The active socket.
 
375
 * @param user_data The user data to be associated with the active
 
376
 *                  socket.
 
377
 *
 
378
 * @return          PJ_SUCCESS if the operation has been successful,
 
379
 *                  or the appropriate error code on failure.
 
380
 */
 
381
PJ_DECL(pj_status_t) pj_activesock_set_user_data(pj_activesock_t *asock,
 
382
                                                 void *user_data);
 
383
 
 
384
/**
 
385
 * Retrieve the user data previously associated with this active
 
386
 * socket.
 
387
 *
 
388
 * @param asock     The active socket.
 
389
 *
 
390
 * @return          The user data.
 
391
 */
 
392
PJ_DECL(void*) pj_activesock_get_user_data(pj_activesock_t *asock);
 
393
 
 
394
 
 
395
/**
 
396
 * Starts read operation on this active socket. This function will create
 
397
 * \a async_cnt number of buffers (the \a async_cnt parameter was given
 
398
 * in \a pj_activesock_create() function) where each buffer is \a buff_size
 
399
 * long. The buffers are allocated from the specified \a pool. Once the 
 
400
 * buffers are created, it then issues \a async_cnt number of asynchronous
 
401
 * \a recv() operations to the socket and returns back to caller. Incoming
 
402
 * data on the socket will be reported back to application via the 
 
403
 * \a on_data_read() callback.
 
404
 *
 
405
 * Application only needs to call this function once to initiate read
 
406
 * operations. Further read operations will be done automatically by the
 
407
 * active socket when \a on_data_read() callback returns non-zero. 
 
408
 *
 
409
 * @param asock     The active socket.
 
410
 * @param pool      Pool used to allocate buffers for incoming data.
 
411
 * @param buff_size The size of each buffer, in bytes.
 
412
 * @param flags     Flags to be given to pj_ioqueue_recv().
 
413
 *
 
414
 * @return          PJ_SUCCESS if the operation has been successful,
 
415
 *                  or the appropriate error code on failure.
 
416
 */
 
417
PJ_DECL(pj_status_t) pj_activesock_start_read(pj_activesock_t *asock,
 
418
                                              pj_pool_t *pool,
 
419
                                              unsigned buff_size,
 
420
                                              pj_uint32_t flags);
 
421
 
 
422
/**
 
423
 * Same as #pj_activesock_start_read(), except that the application
 
424
 * supplies the buffers for the read operation so that the acive socket
 
425
 * does not have to allocate the buffers.
 
426
 *
 
427
 * @param asock     The active socket.
 
428
 * @param pool      Pool used to allocate buffers for incoming data.
 
429
 * @param buff_size The size of each buffer, in bytes.
 
430
 * @param readbuf   Array of packet buffers, each has buff_size size.
 
431
 * @param flags     Flags to be given to pj_ioqueue_recv().
 
432
 *
 
433
 * @return          PJ_SUCCESS if the operation has been successful,
 
434
 *                  or the appropriate error code on failure.
 
435
 */
 
436
PJ_DECL(pj_status_t) pj_activesock_start_read2(pj_activesock_t *asock,
 
437
                                               pj_pool_t *pool,
 
438
                                               unsigned buff_size,
 
439
                                               void *readbuf[],
 
440
                                               pj_uint32_t flags);
 
441
 
 
442
/**
 
443
 * Same as pj_activesock_start_read(), except that this function is used
 
444
 * only for datagram sockets, and it will trigger \a on_data_recvfrom()
 
445
 * callback instead.
 
446
 *
 
447
 * @param asock     The active socket.
 
448
 * @param pool      Pool used to allocate buffers for incoming data.
 
449
 * @param buff_size The size of each buffer, in bytes.
 
450
 * @param flags     Flags to be given to pj_ioqueue_recvfrom().
 
451
 *
 
452
 * @return          PJ_SUCCESS if the operation has been successful,
 
453
 *                  or the appropriate error code on failure.
 
454
 */
 
455
PJ_DECL(pj_status_t) pj_activesock_start_recvfrom(pj_activesock_t *asock,
 
456
                                                  pj_pool_t *pool,
 
457
                                                  unsigned buff_size,
 
458
                                                  pj_uint32_t flags);
 
459
 
 
460
/**
 
461
 * Same as #pj_activesock_start_recvfrom() except that the recvfrom() 
 
462
 * operation takes the buffer from the argument rather than creating
 
463
 * new ones.
 
464
 *
 
465
 * @param asock     The active socket.
 
466
 * @param pool      Pool used to allocate buffers for incoming data.
 
467
 * @param buff_size The size of each buffer, in bytes.
 
468
 * @param readbuf   Array of packet buffers, each has buff_size size.
 
469
 * @param flags     Flags to be given to pj_ioqueue_recvfrom().
 
470
 *
 
471
 * @return          PJ_SUCCESS if the operation has been successful,
 
472
 *                  or the appropriate error code on failure.
 
473
 */
 
474
PJ_DECL(pj_status_t) pj_activesock_start_recvfrom2(pj_activesock_t *asock,
 
475
                                                   pj_pool_t *pool,
 
476
                                                   unsigned buff_size,
 
477
                                                   void *readbuf[],
 
478
                                                   pj_uint32_t flags);
 
479
 
 
480
/**
 
481
 * Send data using the socket.
 
482
 *
 
483
 * @param asock     The active socket.
 
484
 * @param send_key  The operation key to send the data, which is useful
 
485
 *                  if application wants to submit multiple pending
 
486
 *                  send operations and want to track which exact data 
 
487
 *                  has been sent in the \a on_data_sent() callback.
 
488
 * @param data      The data to be sent. This data must remain valid
 
489
 *                  until the data has been sent.
 
490
 * @param size      The size of the data.
 
491
 * @param flags     Flags to be given to pj_ioqueue_send().
 
492
 *
 
493
 *
 
494
 * @return          PJ_SUCCESS if data has been sent immediately, or
 
495
 *                  PJ_EPENDING if data cannot be sent immediately. In
 
496
 *                  this case the \a on_data_sent() callback will be
 
497
 *                  called when data is actually sent. Any other return
 
498
 *                  value indicates error condition.
 
499
 */
 
500
PJ_DECL(pj_status_t) pj_activesock_send(pj_activesock_t *asock,
 
501
                                        pj_ioqueue_op_key_t *send_key,
 
502
                                        const void *data,
 
503
                                        pj_ssize_t *size,
 
504
                                        unsigned flags);
 
505
 
 
506
/**
 
507
 * Send datagram using the socket.
 
508
 *
 
509
 * @param asock     The active socket.
 
510
 * @param send_key  The operation key to send the data, which is useful
 
511
 *                  if application wants to submit multiple pending
 
512
 *                  send operations and want to track which exact data 
 
513
 *                  has been sent in the \a on_data_sent() callback.
 
514
 * @param data      The data to be sent. This data must remain valid
 
515
 *                  until the data has been sent.
 
516
 * @param size      The size of the data.
 
517
 * @param flags     Flags to be given to pj_ioqueue_send().
 
518
 * @param addr      The destination address.
 
519
 * @param addr_len  The length of the address.
 
520
 *
 
521
 * @return          PJ_SUCCESS if data has been sent immediately, or
 
522
 *                  PJ_EPENDING if data cannot be sent immediately. In
 
523
 *                  this case the \a on_data_sent() callback will be
 
524
 *                  called when data is actually sent. Any other return
 
525
 *                  value indicates error condition.
 
526
 */
 
527
PJ_DECL(pj_status_t) pj_activesock_sendto(pj_activesock_t *asock,
 
528
                                          pj_ioqueue_op_key_t *send_key,
 
529
                                          const void *data,
 
530
                                          pj_ssize_t *size,
 
531
                                          unsigned flags,
 
532
                                          const pj_sockaddr_t *addr,
 
533
                                          int addr_len);
 
534
 
 
535
#if PJ_HAS_TCP
 
536
/**
 
537
 * Starts asynchronous socket accept() operations on this active socket. 
 
538
 * Application must bind the socket before calling this function. This 
 
539
 * function will issue \a async_cnt number of asynchronous \a accept() 
 
540
 * operations to the socket and returns back to caller. Incoming
 
541
 * connection on the socket will be reported back to application via the
 
542
 * \a on_accept_complete() callback.
 
543
 *
 
544
 * Application only needs to call this function once to initiate accept()
 
545
 * operations. Further accept() operations will be done automatically by 
 
546
 * the active socket when \a on_accept_complete() callback returns non-zero.
 
547
 *
 
548
 * @param asock     The active socket.
 
549
 * @param pool      Pool used to allocate some internal data for the
 
550
 *                  operation.
 
551
 *
 
552
 * @return          PJ_SUCCESS if the operation has been successful,
 
553
 *                  or the appropriate error code on failure.
 
554
 */
 
555
PJ_DECL(pj_status_t) pj_activesock_start_accept(pj_activesock_t *asock,
 
556
                                                pj_pool_t *pool);
 
557
 
 
558
/**
 
559
 * Starts asynchronous socket connect() operation for this socket. Once
 
560
 * the connection is done (either successfully or not), the 
 
561
 * \a on_connect_complete() callback will be called.
 
562
 *
 
563
 * @param asock     The active socket.
 
564
 * @param pool      The pool to allocate some internal data for the
 
565
 *                  operation.
 
566
 * @param remaddr   Remote address.
 
567
 * @param addr_len  Length of the remote address.
 
568
 *
 
569
 * @return          PJ_SUCCESS if connection can be established immediately,
 
570
 *                  or PJ_EPENDING if connection cannot be established 
 
571
 *                  immediately. In this case the \a on_connect_complete()
 
572
 *                  callback will be called when connection is complete. 
 
573
 *                  Any other return value indicates error condition.
 
574
 */
 
575
PJ_DECL(pj_status_t) pj_activesock_start_connect(pj_activesock_t *asock,
 
576
                                                 pj_pool_t *pool,
 
577
                                                 const pj_sockaddr_t *remaddr,
 
578
                                                 int addr_len);
 
579
 
 
580
 
 
581
#endif  /* PJ_HAS_TCP */
 
582
 
 
583
/**
 
584
 * @}
 
585
 */
 
586
 
 
587
PJ_END_DECL
 
588
 
 
589
#endif  /* __PJ_ASYNCSOCK_H__ */
 
590