1 /* $Id$ */ 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 591