Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjlib / include / pj / sock_select.h
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_SELECT_H__
21 #define __PJ_SELECT_H__
22
23 /**
24  * @file sock_select.h
25  * @brief Socket select().
26  */
27
28 #include <pj/types.h>
29
30 PJ_BEGIN_DECL 
31
32 /**
33  * @defgroup PJ_SOCK_SELECT Socket select() API.
34  * @ingroup PJ_IO
35  * @{
36  * This module provides portable abstraction for \a select() like API.
37  * The abstraction is needed so that it can utilize various event
38  * dispatching mechanisms that are available across platforms.
39  *
40  * The API is very similar to normal \a select() usage. 
41  *
42  * \section pj_sock_select_examples_sec Examples
43  *
44  * For some examples on how to use the select API, please see:
45  *
46  *  - \ref page_pjlib_select_test
47  */
48
49 /**
50  * Portable structure declarations for pj_fd_set.
51  * The implementation of pj_sock_select() does not use this structure 
52  * per-se, but instead it will use the native fd_set structure. However,
53  * we must make sure that the size of pj_fd_set_t can accomodate the
54  * native fd_set structure.
55  */
56 typedef struct pj_fd_set_t
57 {
58     pj_sock_t data[PJ_IOQUEUE_MAX_HANDLES+ 4]; /**< Opaque buffer for fd_set */
59 } pj_fd_set_t;
60
61
62 /**
63  * Initialize the descriptor set pointed to by fdsetp to the null set.
64  *
65  * @param fdsetp    The descriptor set.
66  */
67 PJ_DECL(void) PJ_FD_ZERO(pj_fd_set_t *fdsetp);
68
69
70 /**
71  * This is an internal function, application shouldn't use this.
72  * 
73  * Get the number of descriptors in the set. This is defined in sock_select.c
74  * This function will only return the number of sockets set from PJ_FD_SET
75  * operation. When the set is modified by other means (such as by select()),
76  * the count will not be reflected here.
77  *
78  * @param fdsetp    The descriptor set.
79  *
80  * @return          Number of descriptors in the set.
81  */
82 PJ_DECL(pj_size_t) PJ_FD_COUNT(const pj_fd_set_t *fdsetp);
83
84
85 /**
86  * Add the file descriptor fd to the set pointed to by fdsetp. 
87  * If the file descriptor fd is already in this set, there shall be no effect
88  * on the set, nor will an error be returned.
89  *
90  * @param fd        The socket descriptor.
91  * @param fdsetp    The descriptor set.
92  */
93 PJ_DECL(void) PJ_FD_SET(pj_sock_t fd, pj_fd_set_t *fdsetp);
94
95 /**
96  * Remove the file descriptor fd from the set pointed to by fdsetp. 
97  * If fd is not a member of this set, there shall be no effect on the set, 
98  * nor will an error be returned.
99  *
100  * @param fd        The socket descriptor.
101  * @param fdsetp    The descriptor set.
102  */
103 PJ_DECL(void) PJ_FD_CLR(pj_sock_t fd, pj_fd_set_t *fdsetp);
104
105
106 /**
107  * Evaluate to non-zero if the file descriptor fd is a member of the set 
108  * pointed to by fdsetp, and shall evaluate to zero otherwise.
109  *
110  * @param fd        The socket descriptor.
111  * @param fdsetp    The descriptor set.
112  *
113  * @return          Nonzero if fd is member of the descriptor set.
114  */
115 PJ_DECL(pj_bool_t) PJ_FD_ISSET(pj_sock_t fd, const pj_fd_set_t *fdsetp);
116
117
118 /**
119  * This function wait for a number of file  descriptors to change status.
120  * The behaviour is the same as select() function call which appear in
121  * standard BSD socket libraries.
122  *
123  * @param n         On Unices, this specifies the highest-numbered
124  *                  descriptor in any of the three set, plus 1. On Windows,
125  *                  the value is ignored.
126  * @param readfds   Optional pointer to a set of sockets to be checked for 
127  *                  readability.
128  * @param writefds  Optional pointer to a set of sockets to be checked for 
129  *                  writability.
130  * @param exceptfds Optional pointer to a set of sockets to be checked for 
131  *                  errors.
132  * @param timeout   Maximum time for select to wait, or null for blocking 
133  *                  operations.
134  *
135  * @return          The total number of socket handles that are ready, or
136  *                  zero if the time limit expired, or -1 if an error occurred.
137  */
138 PJ_DECL(int) pj_sock_select( int n, 
139                              pj_fd_set_t *readfds, 
140                              pj_fd_set_t *writefds,
141                              pj_fd_set_t *exceptfds, 
142                              const pj_time_val *timeout);
143
144
145 /**
146  * @}
147  */
148
149
150 PJ_END_DECL
151
152 #endif  /* __PJ_SELECT_H__ */