Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjlib / include / pj / sock.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_SOCK_H__
21 #define __PJ_SOCK_H__
22
23 /**
24  * @file sock.h
25  * @brief Socket Abstraction.
26  */
27
28 #include <pj/types.h>
29
30 PJ_BEGIN_DECL 
31
32
33 /**
34  * @defgroup PJ_SOCK Socket Abstraction
35  * @ingroup PJ_IO
36  * @{
37  *
38  * The PJLIB socket abstraction layer is a thin and very portable abstraction
39  * for socket API. It provides API similar to BSD socket API. The abstraction
40  * is needed because BSD socket API is not always available on all platforms,
41  * therefore it wouldn't be possible to create a trully portable network
42  * programs unless we provide such abstraction.
43  *
44  * Applications can use this API directly in their application, just
45  * as they would when using traditional BSD socket API, provided they
46  * call #pj_init() first.
47  *
48  * \section pj_sock_examples_sec Examples
49  *
50  * For some examples on how to use the socket API, please see:
51  *
52  *  - \ref page_pjlib_sock_test
53  *  - \ref page_pjlib_select_test
54  *  - \ref page_pjlib_sock_perf_test
55  */
56
57
58 /**
59  * Supported address families. 
60  * APPLICATION MUST USE THESE VALUES INSTEAD OF NORMAL AF_*, BECAUSE
61  * THE LIBRARY WILL DO TRANSLATION TO THE NATIVE VALUE.
62  */
63
64 /** Address family is unspecified. @see pj_AF_UNSPEC() */
65 extern const pj_uint16_t PJ_AF_UNSPEC;
66
67 /** Unix domain socket. @see pj_AF_UNIX() */
68 extern const pj_uint16_t PJ_AF_UNIX;
69
70 /** POSIX name for AF_UNIX      */
71 #define PJ_AF_LOCAL      PJ_AF_UNIX;
72
73 /** Internet IP protocol. @see pj_AF_INET() */
74 extern const pj_uint16_t PJ_AF_INET;
75
76 /** IP version 6. @see pj_AF_INET6() */
77 extern const pj_uint16_t PJ_AF_INET6;
78
79 /** Packet family. @see pj_AF_PACKET() */
80 extern const pj_uint16_t PJ_AF_PACKET;
81
82 /** IRDA sockets. @see pj_AF_IRDA() */
83 extern const pj_uint16_t PJ_AF_IRDA;
84
85 /*
86  * Accessor functions for various address family constants. These
87  * functions are provided because Symbian doesn't allow exporting
88  * global variables from a DLL.
89  */
90
91 #if defined(PJ_DLL)
92     /** Get #PJ_AF_UNSPEC value */
93     PJ_DECL(pj_uint16_t) pj_AF_UNSPEC(void);
94     /** Get #PJ_AF_UNIX value. */
95     PJ_DECL(pj_uint16_t) pj_AF_UNIX(void);
96     /** Get #PJ_AF_INET value. */
97     PJ_DECL(pj_uint16_t) pj_AF_INET(void);
98     /** Get #PJ_AF_INET6 value. */
99     PJ_DECL(pj_uint16_t) pj_AF_INET6(void);
100     /** Get #PJ_AF_PACKET value. */
101     PJ_DECL(pj_uint16_t) pj_AF_PACKET(void);
102     /** Get #PJ_AF_IRDA value. */
103     PJ_DECL(pj_uint16_t) pj_AF_IRDA(void);
104 #else
105     /* When pjlib is not built as DLL, these accessor functions are
106      * simply a macro to get their constants
107      */
108     /** Get #PJ_AF_UNSPEC value */
109 #   define pj_AF_UNSPEC()   PJ_AF_UNSPEC
110     /** Get #PJ_AF_UNIX value. */
111 #   define pj_AF_UNIX()     PJ_AF_UNIX
112     /** Get #PJ_AF_INET value. */
113 #   define pj_AF_INET()     PJ_AF_INET
114     /** Get #PJ_AF_INET6 value. */
115 #   define pj_AF_INET6()    PJ_AF_INET6
116     /** Get #PJ_AF_PACKET value. */
117 #   define pj_AF_PACKET()   PJ_AF_PACKET
118     /** Get #PJ_AF_IRDA value. */
119 #   define pj_AF_IRDA()     PJ_AF_IRDA
120 #endif
121
122
123 /**
124  * Supported types of sockets.
125  * APPLICATION MUST USE THESE VALUES INSTEAD OF NORMAL SOCK_*, BECAUSE
126  * THE LIBRARY WILL TRANSLATE THE VALUE TO THE NATIVE VALUE.
127  */
128
129 /** Sequenced, reliable, connection-based byte streams.
130  *  @see pj_SOCK_STREAM() */
131 extern const pj_uint16_t PJ_SOCK_STREAM;
132
133 /** Connectionless, unreliable datagrams of fixed maximum lengths.
134  *  @see pj_SOCK_DGRAM() */
135 extern const pj_uint16_t PJ_SOCK_DGRAM;
136
137 /** Raw protocol interface. @see pj_SOCK_RAW() */
138 extern const pj_uint16_t PJ_SOCK_RAW;
139
140 /** Reliably-delivered messages.  @see pj_SOCK_RDM() */
141 extern const pj_uint16_t PJ_SOCK_RDM;
142
143
144 /*
145  * Accessor functions for various constants. These functions are provided
146  * because Symbian doesn't allow exporting global variables from a DLL.
147  */
148
149 #if defined(PJ_DLL)
150     /** Get #PJ_SOCK_STREAM constant */
151     PJ_DECL(int) pj_SOCK_STREAM(void);
152     /** Get #PJ_SOCK_DGRAM constant */
153     PJ_DECL(int) pj_SOCK_DGRAM(void);
154     /** Get #PJ_SOCK_RAW constant */
155     PJ_DECL(int) pj_SOCK_RAW(void);
156     /** Get #PJ_SOCK_RDM constant */
157     PJ_DECL(int) pj_SOCK_RDM(void);
158 #else
159     /** Get #PJ_SOCK_STREAM constant */
160 #   define pj_SOCK_STREAM() PJ_SOCK_STREAM
161     /** Get #PJ_SOCK_DGRAM constant */
162 #   define pj_SOCK_DGRAM()  PJ_SOCK_DGRAM
163     /** Get #PJ_SOCK_RAW constant */
164 #   define pj_SOCK_RAW()    PJ_SOCK_RAW
165     /** Get #PJ_SOCK_RDM constant */
166 #   define pj_SOCK_RDM()    PJ_SOCK_RDM
167 #endif
168
169
170 /**
171  * Socket level specified in #pj_sock_setsockopt() or #pj_sock_getsockopt().
172  * APPLICATION MUST USE THESE VALUES INSTEAD OF NORMAL SOL_*, BECAUSE
173  * THE LIBRARY WILL TRANSLATE THE VALUE TO THE NATIVE VALUE.
174  */
175 /** Socket level. @see pj_SOL_SOCKET() */
176 extern const pj_uint16_t PJ_SOL_SOCKET;
177 /** IP level. @see pj_SOL_IP() */
178 extern const pj_uint16_t PJ_SOL_IP;
179 /** TCP level. @see pj_SOL_TCP() */
180 extern const pj_uint16_t PJ_SOL_TCP;
181 /** UDP level. @see pj_SOL_UDP() */
182 extern const pj_uint16_t PJ_SOL_UDP;
183 /** IP version 6. @see pj_SOL_IPV6() */
184 extern const pj_uint16_t PJ_SOL_IPV6;
185
186 /*
187  * Accessor functions for various constants. These functions are provided
188  * because Symbian doesn't allow exporting global variables from a DLL.
189  */
190
191 #if defined(PJ_DLL)
192     /** Get #PJ_SOL_SOCKET constant */
193     PJ_DECL(pj_uint16_t) pj_SOL_SOCKET(void);
194     /** Get #PJ_SOL_IP constant */
195     PJ_DECL(pj_uint16_t) pj_SOL_IP(void);
196     /** Get #PJ_SOL_TCP constant */
197     PJ_DECL(pj_uint16_t) pj_SOL_TCP(void);
198     /** Get #PJ_SOL_UDP constant */
199     PJ_DECL(pj_uint16_t) pj_SOL_UDP(void);
200     /** Get #PJ_SOL_IPV6 constant */
201     PJ_DECL(pj_uint16_t) pj_SOL_IPV6(void);
202 #else
203     /** Get #PJ_SOL_SOCKET constant */
204 #   define pj_SOL_SOCKET()  PJ_SOL_SOCKET
205     /** Get #PJ_SOL_IP constant */
206 #   define pj_SOL_IP()      PJ_SOL_IP
207     /** Get #PJ_SOL_TCP constant */
208 #   define pj_SOL_TCP()     PJ_SOL_TCP
209     /** Get #PJ_SOL_UDP constant */
210 #   define pj_SOL_UDP()     PJ_SOL_UDP
211     /** Get #PJ_SOL_IPV6 constant */
212 #   define pj_SOL_IPV6()    PJ_SOL_IPV6
213 #endif
214
215
216 /* IP_TOS 
217  *
218  * Note:
219  *  TOS CURRENTLY DOES NOT WORK IN Windows 2000 and above!
220  *  See http://support.microsoft.com/kb/248611
221  */
222 /** IP_TOS optname in setsockopt(). @see pj_IP_TOS() */
223 extern const pj_uint16_t PJ_IP_TOS;
224
225 /*
226  * IP TOS related constats.
227  *
228  * Note:
229  *  TOS CURRENTLY DOES NOT WORK IN Windows 2000 and above!
230  *  See http://support.microsoft.com/kb/248611
231  */
232 /** Minimize delays. @see pj_IPTOS_LOWDELAY() */
233 extern const pj_uint16_t PJ_IPTOS_LOWDELAY;
234
235 /** Optimize throughput. @see pj_IPTOS_THROUGHPUT() */
236 extern const pj_uint16_t PJ_IPTOS_THROUGHPUT;
237
238 /** Optimize for reliability. @see pj_IPTOS_RELIABILITY() */
239 extern const pj_uint16_t PJ_IPTOS_RELIABILITY;
240
241 /** "filler data" where slow transmission does't matter.
242  *  @see pj_IPTOS_MINCOST() */
243 extern const pj_uint16_t PJ_IPTOS_MINCOST;
244
245
246 #if defined(PJ_DLL)
247     /** Get #PJ_IP_TOS constant */
248     PJ_DECL(int) pj_IP_TOS(void);
249
250     /** Get #PJ_IPTOS_LOWDELAY constant */
251     PJ_DECL(int) pj_IPTOS_LOWDELAY(void);
252
253     /** Get #PJ_IPTOS_THROUGHPUT constant */
254     PJ_DECL(int) pj_IPTOS_THROUGHPUT(void);
255
256     /** Get #PJ_IPTOS_RELIABILITY constant */
257     PJ_DECL(int) pj_IPTOS_RELIABILITY(void);
258
259     /** Get #PJ_IPTOS_MINCOST constant */
260     PJ_DECL(int) pj_IPTOS_MINCOST(void);
261 #else
262     /** Get #PJ_IP_TOS constant */
263 #   define pj_IP_TOS()          PJ_IP_TOS
264
265     /** Get #PJ_IPTOS_LOWDELAY constant */
266 #   define pj_IPTOS_LOWDELAY()  PJ_IP_TOS_LOWDELAY
267
268     /** Get #PJ_IPTOS_THROUGHPUT constant */
269 #   define pj_IPTOS_THROUGHPUT() PJ_IP_TOS_THROUGHPUT
270
271     /** Get #PJ_IPTOS_RELIABILITY constant */
272 #   define pj_IPTOS_RELIABILITY() PJ_IP_TOS_RELIABILITY
273
274     /** Get #PJ_IPTOS_MINCOST constant */
275 #   define pj_IPTOS_MINCOST()   PJ_IP_TOS_MINCOST
276 #endif
277
278
279 /**
280  * Values to be specified as \c optname when calling #pj_sock_setsockopt() 
281  * or #pj_sock_getsockopt().
282  */
283
284 /** Socket type. @see pj_SO_TYPE() */
285 extern const pj_uint16_t PJ_SO_TYPE;
286
287 /** Buffer size for receive. @see pj_SO_RCVBUF() */
288 extern const pj_uint16_t PJ_SO_RCVBUF;
289
290 /** Buffer size for send. @see pj_SO_SNDBUF() */
291 extern const pj_uint16_t PJ_SO_SNDBUF;
292
293 /** Disables the Nagle algorithm for send coalescing. @see pj_TCP_NODELAY */
294 extern const pj_uint16_t PJ_TCP_NODELAY;
295
296 /** Allows the socket to be bound to an address that is already in use.
297  *  @see pj_SO_REUSEADDR */
298 extern const pj_uint16_t PJ_SO_REUSEADDR;
299
300 /** Do not generate SIGPIPE. @see pj_SO_NOSIGPIPE */
301 extern const pj_uint16_t PJ_SO_NOSIGPIPE;
302
303 /** Set the protocol-defined priority for all packets to be sent on socket.
304  */
305 extern const pj_uint16_t PJ_SO_PRIORITY;
306
307 /** IP multicast interface. @see pj_IP_MULTICAST_IF() */
308 extern const pj_uint16_t PJ_IP_MULTICAST_IF;
309  
310 /** IP multicast ttl. @see pj_IP_MULTICAST_TTL() */
311 extern const pj_uint16_t PJ_IP_MULTICAST_TTL;
312
313 /** IP multicast loopback. @see pj_IP_MULTICAST_LOOP() */
314 extern const pj_uint16_t PJ_IP_MULTICAST_LOOP;
315
316 /** Add an IP group membership. @see pj_IP_ADD_MEMBERSHIP() */
317 extern const pj_uint16_t PJ_IP_ADD_MEMBERSHIP;
318
319 /** Drop an IP group membership. @see pj_IP_DROP_MEMBERSHIP() */
320 extern const pj_uint16_t PJ_IP_DROP_MEMBERSHIP;
321
322
323 #if defined(PJ_DLL)
324     /** Get #PJ_SO_TYPE constant */
325     PJ_DECL(pj_uint16_t) pj_SO_TYPE(void);
326
327     /** Get #PJ_SO_RCVBUF constant */
328     PJ_DECL(pj_uint16_t) pj_SO_RCVBUF(void);
329
330     /** Get #PJ_SO_SNDBUF constant */
331     PJ_DECL(pj_uint16_t) pj_SO_SNDBUF(void);
332
333     /** Get #PJ_TCP_NODELAY constant */
334     PJ_DECL(pj_uint16_t) pj_TCP_NODELAY(void);
335
336     /** Get #PJ_SO_REUSEADDR constant */
337     PJ_DECL(pj_uint16_t) pj_SO_REUSEADDR(void);
338
339     /** Get #PJ_SO_NOSIGPIPE constant */
340     PJ_DECL(pj_uint16_t) pj_SO_NOSIGPIPE(void);
341
342     /** Get #PJ_SO_PRIORITY constant */
343     PJ_DECL(pj_uint16_t) pj_SO_PRIORITY(void);
344
345     /** Get #PJ_IP_MULTICAST_IF constant */
346     PJ_DECL(pj_uint16_t) pj_IP_MULTICAST_IF(void);
347
348     /** Get #PJ_IP_MULTICAST_TTL constant */
349     PJ_DECL(pj_uint16_t) pj_IP_MULTICAST_TTL(void);
350
351     /** Get #PJ_IP_MULTICAST_LOOP constant */
352     PJ_DECL(pj_uint16_t) pj_IP_MULTICAST_LOOP(void);
353
354     /** Get #PJ_IP_ADD_MEMBERSHIP constant */
355     PJ_DECL(pj_uint16_t) pj_IP_ADD_MEMBERSHIP(void);
356
357     /** Get #PJ_IP_DROP_MEMBERSHIP constant */
358     PJ_DECL(pj_uint16_t) pj_IP_DROP_MEMBERSHIP(void);
359 #else
360     /** Get #PJ_SO_TYPE constant */
361 #   define pj_SO_TYPE()     PJ_SO_TYPE
362
363     /** Get #PJ_SO_RCVBUF constant */
364 #   define pj_SO_RCVBUF()   PJ_SO_RCVBUF
365
366     /** Get #PJ_SO_SNDBUF constant */
367 #   define pj_SO_SNDBUF()   PJ_SO_SNDBUF
368
369     /** Get #PJ_TCP_NODELAY constant */
370 #   define pj_TCP_NODELAY() PJ_TCP_NODELAY
371
372     /** Get #PJ_SO_REUSEADDR constant */
373 #   define pj_SO_REUSEADDR() PJ_SO_REUSEADDR
374
375     /** Get #PJ_SO_NOSIGPIPE constant */
376 #   define pj_SO_NOSIGPIPE() PJ_SO_NOSIGPIPE
377
378     /** Get #PJ_SO_PRIORITY constant */
379 #   define pj_SO_PRIORITY() PJ_SO_PRIORITY
380
381     /** Get #PJ_IP_MULTICAST_IF constant */
382 #   define pj_IP_MULTICAST_IF()    PJ_IP_MULTICAST_IF
383
384     /** Get #PJ_IP_MULTICAST_TTL constant */
385 #   define pj_IP_MULTICAST_TTL()   PJ_IP_MULTICAST_TTL
386
387     /** Get #PJ_IP_MULTICAST_LOOP constant */
388 #   define pj_IP_MULTICAST_LOOP()  PJ_IP_MULTICAST_LOOP
389
390     /** Get #PJ_IP_ADD_MEMBERSHIP constant */
391 #   define pj_IP_ADD_MEMBERSHIP()  PJ_IP_ADD_MEMBERSHIP
392
393     /** Get #PJ_IP_DROP_MEMBERSHIP constant */
394 #   define pj_IP_DROP_MEMBERSHIP() PJ_IP_DROP_MEMBERSHIP
395 #endif
396
397
398 /*
399  * Flags to be specified in #pj_sock_recv, #pj_sock_send, etc.
400  */
401
402 /** Out-of-band messages. @see pj_MSG_OOB() */
403 extern const int PJ_MSG_OOB;
404
405 /** Peek, don't remove from buffer. @see pj_MSG_PEEK() */
406 extern const int PJ_MSG_PEEK;
407
408 /** Don't route. @see pj_MSG_DONTROUTE() */
409 extern const int PJ_MSG_DONTROUTE;
410
411
412 #if defined(PJ_DLL)
413     /** Get #PJ_MSG_OOB constant */
414     PJ_DECL(int) pj_MSG_OOB(void);
415
416     /** Get #PJ_MSG_PEEK constant */
417     PJ_DECL(int) pj_MSG_PEEK(void);
418
419     /** Get #PJ_MSG_DONTROUTE constant */
420     PJ_DECL(int) pj_MSG_DONTROUTE(void);
421 #else
422     /** Get #PJ_MSG_OOB constant */
423 #   define pj_MSG_OOB()         PJ_MSG_OOB
424
425     /** Get #PJ_MSG_PEEK constant */
426 #   define pj_MSG_PEEK()        PJ_MSG_PEEK
427
428     /** Get #PJ_MSG_DONTROUTE constant */
429 #   define pj_MSG_DONTROUTE()   PJ_MSG_DONTROUTE
430 #endif
431
432
433 /**
434  * Flag to be specified in #pj_sock_shutdown().
435  */
436 typedef enum pj_socket_sd_type
437 {
438     PJ_SD_RECEIVE   = 0,    /**< No more receive.           */
439     PJ_SHUT_RD      = 0,    /**< Alias for SD_RECEIVE.      */
440     PJ_SD_SEND      = 1,    /**< No more sending.           */
441     PJ_SHUT_WR      = 1,    /**< Alias for SD_SEND.         */
442     PJ_SD_BOTH      = 2,    /**< No more send and receive.  */
443     PJ_SHUT_RDWR    = 2     /**< Alias for SD_BOTH.         */
444 } pj_socket_sd_type;
445
446
447
448 /** Address to accept any incoming messages. */
449 #define PJ_INADDR_ANY       ((pj_uint32_t)0)
450
451 /** Address indicating an error return */
452 #define PJ_INADDR_NONE      ((pj_uint32_t)0xffffffff)
453
454 /** Address to send to all hosts. */
455 #define PJ_INADDR_BROADCAST ((pj_uint32_t)0xffffffff)
456
457
458 /** 
459  * Maximum length specifiable by #pj_sock_listen().
460  * If the build system doesn't override this value, then the lowest 
461  * denominator (five, in Win32 systems) will be used.
462  */
463 #if !defined(PJ_SOMAXCONN)
464 #  define PJ_SOMAXCONN  5
465 #endif
466
467
468 /**
469  * Constant for invalid socket returned by #pj_sock_socket() and
470  * #pj_sock_accept().
471  */
472 #define PJ_INVALID_SOCKET   (-1)
473
474 /* Must undefine s_addr because of pj_in_addr below */
475 #undef s_addr
476
477 /**
478  * This structure describes Internet address.
479  */
480 typedef struct pj_in_addr
481 {
482     pj_uint32_t s_addr;         /**< The 32bit IP address.          */
483 } pj_in_addr;
484
485
486 /**
487  * Maximum length of text representation of an IPv4 address.
488  */
489 #define PJ_INET_ADDRSTRLEN      16
490
491 /**
492  * Maximum length of text representation of an IPv6 address.
493  */
494 #define PJ_INET6_ADDRSTRLEN     46
495
496 /**
497  * The size of sin_zero field in pj_sockaddr_in structure. Most OSes
498  * use 8, but others such as the BSD TCP/IP stack in eCos uses 24.
499  */
500 #ifndef PJ_SOCKADDR_IN_SIN_ZERO_LEN
501 #   define PJ_SOCKADDR_IN_SIN_ZERO_LEN  8
502 #endif
503
504 /**
505  * This structure describes Internet socket address.
506  * If PJ_SOCKADDR_HAS_LEN is not zero, then sin_zero_len member is added
507  * to this struct. As far the application is concerned, the value of
508  * this member will always be zero. Internally, PJLIB may modify the value
509  * before calling OS socket API, and reset the value back to zero before
510  * returning the struct to application.
511  */
512 struct pj_sockaddr_in
513 {
514 #if defined(PJ_SOCKADDR_HAS_LEN) && PJ_SOCKADDR_HAS_LEN!=0
515     pj_uint8_t  sin_zero_len;   /**< Just ignore this.              */
516     pj_uint8_t  sin_family;     /**< Address family.                */
517 #else
518     pj_uint16_t sin_family;     /**< Address family.                */
519 #endif
520     pj_uint16_t sin_port;       /**< Transport layer port number.   */
521     pj_in_addr  sin_addr;       /**< IP address.                    */
522     char        sin_zero[PJ_SOCKADDR_IN_SIN_ZERO_LEN]; /**< Padding.*/
523 };
524
525
526 #undef s6_addr
527
528 /**
529  * This structure describes IPv6 address.
530  */
531 typedef union pj_in6_addr
532 {
533     /* This is the main entry */
534     pj_uint8_t  s6_addr[16];   /**< 8-bit array */
535
536     /* While these are used for proper alignment */
537     pj_uint32_t u6_addr32[4];
538
539     /* Do not use this with Winsock2, as this will align pj_sockaddr_in6
540      * to 64-bit boundary and Winsock2 doesn't like it!
541      * Update 26/04/2010:
542      *  This is now disabled, see http://trac.pjsip.org/repos/ticket/1058
543      */
544 #if 0 && defined(PJ_HAS_INT64) && PJ_HAS_INT64!=0 && \
545     (!defined(PJ_WIN32) || PJ_WIN32==0)
546     pj_int64_t  u6_addr64[2];
547 #endif
548
549 } pj_in6_addr;
550
551
552 /** Initializer value for pj_in6_addr. */
553 #define PJ_IN6ADDR_ANY_INIT { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } } }
554
555 /** Initializer value for pj_in6_addr. */
556 #define PJ_IN6ADDR_LOOPBACK_INIT { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 } } }
557
558 /**
559  * This structure describes IPv6 socket address.
560  * If PJ_SOCKADDR_HAS_LEN is not zero, then sin_zero_len member is added
561  * to this struct. As far the application is concerned, the value of
562  * this member will always be zero. Internally, PJLIB may modify the value
563  * before calling OS socket API, and reset the value back to zero before
564  * returning the struct to application.
565  */
566 typedef struct pj_sockaddr_in6
567 {
568 #if defined(PJ_SOCKADDR_HAS_LEN) && PJ_SOCKADDR_HAS_LEN!=0
569     pj_uint8_t  sin6_zero_len;      /**< Just ignore this.         */
570     pj_uint8_t  sin6_family;        /**< Address family.           */
571 #else
572     pj_uint16_t sin6_family;        /**< Address family             */
573 #endif
574     pj_uint16_t sin6_port;          /**< Transport layer port number. */
575     pj_uint32_t sin6_flowinfo;      /**< IPv6 flow information      */
576     pj_in6_addr sin6_addr;          /**< IPv6 address.              */
577     pj_uint32_t sin6_scope_id;      /**< Set of interfaces for a scope  */
578 } pj_sockaddr_in6;
579
580
581 /**
582  * This structure describes common attributes found in transport addresses.
583  * If PJ_SOCKADDR_HAS_LEN is not zero, then sa_zero_len member is added
584  * to this struct. As far the application is concerned, the value of
585  * this member will always be zero. Internally, PJLIB may modify the value
586  * before calling OS socket API, and reset the value back to zero before
587  * returning the struct to application.
588  */
589 typedef struct pj_addr_hdr
590 {
591 #if defined(PJ_SOCKADDR_HAS_LEN) && PJ_SOCKADDR_HAS_LEN!=0
592     pj_uint8_t  sa_zero_len;
593     pj_uint8_t  sa_family;
594 #else
595     pj_uint16_t sa_family;      /**< Common data: address family.   */
596 #endif
597 } pj_addr_hdr;
598
599
600 /**
601  * This union describes a generic socket address.
602  */
603 typedef union pj_sockaddr
604 {
605     pj_addr_hdr     addr;       /**< Generic transport address.     */
606     pj_sockaddr_in  ipv4;       /**< IPv4 transport address.        */
607     pj_sockaddr_in6 ipv6;       /**< IPv6 transport address.        */
608 } pj_sockaddr;
609
610
611 /**
612  * This structure provides multicast group information for IPv4 addresses.
613  */
614 typedef struct pj_ip_mreq {
615     pj_in_addr imr_multiaddr;   /**< IP multicast address of group. */
616     pj_in_addr imr_interface;   /**< local IP address of interface. */
617 } pj_ip_mreq;
618
619
620 /*****************************************************************************
621  *
622  * SOCKET ADDRESS MANIPULATION.
623  *
624  *****************************************************************************
625  */
626
627 /**
628  * Convert 16-bit value from network byte order to host byte order.
629  *
630  * @param netshort  16-bit network value.
631  * @return          16-bit host value.
632  */
633 PJ_DECL(pj_uint16_t) pj_ntohs(pj_uint16_t netshort);
634
635 /**
636  * Convert 16-bit value from host byte order to network byte order.
637  *
638  * @param hostshort 16-bit host value.
639  * @return          16-bit network value.
640  */
641 PJ_DECL(pj_uint16_t) pj_htons(pj_uint16_t hostshort);
642
643 /**
644  * Convert 32-bit value from network byte order to host byte order.
645  *
646  * @param netlong   32-bit network value.
647  * @return          32-bit host value.
648  */
649 PJ_DECL(pj_uint32_t) pj_ntohl(pj_uint32_t netlong);
650
651 /**
652  * Convert 32-bit value from host byte order to network byte order.
653  *
654  * @param hostlong  32-bit host value.
655  * @return          32-bit network value.
656  */
657 PJ_DECL(pj_uint32_t) pj_htonl(pj_uint32_t hostlong);
658
659 /**
660  * Convert an Internet host address given in network byte order
661  * to string in standard numbers and dots notation.
662  *
663  * @param inaddr    The host address.
664  * @return          The string address.
665  */
666 PJ_DECL(char*) pj_inet_ntoa(pj_in_addr inaddr);
667
668 /**
669  * This function converts the Internet host address cp from the standard
670  * numbers-and-dots notation into binary data and stores it in the structure
671  * that inp points to. 
672  *
673  * @param cp    IP address in standard numbers-and-dots notation.
674  * @param inp   Structure that holds the output of the conversion.
675  *
676  * @return      nonzero if the address is valid, zero if not.
677  */
678 PJ_DECL(int) pj_inet_aton(const pj_str_t *cp, struct pj_in_addr *inp);
679
680 /**
681  * This function converts an address in its standard text presentation form
682  * into its numeric binary form. It supports both IPv4 and IPv6 address
683  * conversion.
684  *
685  * @param af    Specify the family of the address.  The PJ_AF_INET and 
686  *              PJ_AF_INET6 address families shall be supported.  
687  * @param src   Points to the string being passed in. 
688  * @param dst   Points to a buffer into which the function stores the 
689  *              numeric address; this shall be large enough to hold the
690  *              numeric address (32 bits for PJ_AF_INET, 128 bits for
691  *              PJ_AF_INET6).  
692  *
693  * @return      PJ_SUCCESS if conversion was successful.
694  */
695 PJ_DECL(pj_status_t) pj_inet_pton(int af, const pj_str_t *src, void *dst);
696
697 /**
698  * This function converts a numeric address into a text string suitable
699  * for presentation. It supports both IPv4 and IPv6 address
700  * conversion. 
701  * @see pj_sockaddr_print()
702  *
703  * @param af    Specify the family of the address. This can be PJ_AF_INET
704  *              or PJ_AF_INET6.
705  * @param src   Points to a buffer holding an IPv4 address if the af argument
706  *              is PJ_AF_INET, or an IPv6 address if the af argument is
707  *              PJ_AF_INET6; the address must be in network byte order.  
708  * @param dst   Points to a buffer where the function stores the resulting
709  *              text string; it shall not be NULL.  
710  * @param size  Specifies the size of this buffer, which shall be large 
711  *              enough to hold the text string (PJ_INET_ADDRSTRLEN characters
712  *              for IPv4, PJ_INET6_ADDRSTRLEN characters for IPv6).
713  *
714  * @return      PJ_SUCCESS if conversion was successful.
715  */
716 PJ_DECL(pj_status_t) pj_inet_ntop(int af, const void *src,
717                                   char *dst, int size);
718
719 /**
720  * Converts numeric address into its text string representation.
721  * @see pj_sockaddr_print()
722  *
723  * @param af    Specify the family of the address. This can be PJ_AF_INET
724  *              or PJ_AF_INET6.
725  * @param src   Points to a buffer holding an IPv4 address if the af argument
726  *              is PJ_AF_INET, or an IPv6 address if the af argument is
727  *              PJ_AF_INET6; the address must be in network byte order.  
728  * @param dst   Points to a buffer where the function stores the resulting
729  *              text string; it shall not be NULL.  
730  * @param size  Specifies the size of this buffer, which shall be large 
731  *              enough to hold the text string (PJ_INET_ADDRSTRLEN characters
732  *              for IPv4, PJ_INET6_ADDRSTRLEN characters for IPv6).
733  *
734  * @return      The address string or NULL if failed.
735  */
736 PJ_DECL(char*) pj_inet_ntop2(int af, const void *src,
737                              char *dst, int size);
738
739 /**
740  * Print socket address.
741  *
742  * @param addr  The socket address.
743  * @param buf   Text buffer.
744  * @param size  Size of buffer.
745  * @param flags Bitmask combination of these value:
746  *                - 1: port number is included.
747  *                - 2: square bracket is included for IPv6 address.
748  *
749  * @return      The address string.
750  */
751 PJ_DECL(char*) pj_sockaddr_print(const pj_sockaddr_t *addr,
752                                  char *buf, int size,
753                                  unsigned flags);
754
755 /**
756  * Convert address string with numbers and dots to binary IP address.
757  * 
758  * @param cp        The IP address in numbers and dots notation.
759  * @return          If success, the IP address is returned in network
760  *                  byte order. If failed, PJ_INADDR_NONE will be
761  *                  returned.
762  * @remark
763  * This is an obsolete interface to #pj_inet_aton(); it is obsolete
764  * because -1 is a valid address (255.255.255.255), and #pj_inet_aton()
765  * provides a cleaner way to indicate error return.
766  */
767 PJ_DECL(pj_in_addr) pj_inet_addr(const pj_str_t *cp);
768
769 /**
770  * Convert address string with numbers and dots to binary IP address.
771  * 
772  * @param cp        The IP address in numbers and dots notation.
773  * @return          If success, the IP address is returned in network
774  *                  byte order. If failed, PJ_INADDR_NONE will be
775  *                  returned.
776  * @remark
777  * This is an obsolete interface to #pj_inet_aton(); it is obsolete
778  * because -1 is a valid address (255.255.255.255), and #pj_inet_aton()
779  * provides a cleaner way to indicate error return.
780  */
781 PJ_DECL(pj_in_addr) pj_inet_addr2(const char *cp);
782
783 /**
784  * Initialize IPv4 socket address based on the address and port info.
785  * The string address may be in a standard numbers and dots notation or 
786  * may be a hostname. If hostname is specified, then the function will 
787  * resolve the host into the IP address.
788  *
789  * @see pj_sockaddr_init()
790  *
791  * @param addr      The IP socket address to be set.
792  * @param cp        The address string, which can be in a standard 
793  *                  dotted numbers or a hostname to be resolved.
794  * @param port      The port number, in host byte order.
795  *
796  * @return          Zero on success.
797  */
798 PJ_DECL(pj_status_t) pj_sockaddr_in_init( pj_sockaddr_in *addr,
799                                           const pj_str_t *cp,
800                                           pj_uint16_t port);
801
802 /**
803  * Initialize IP socket address based on the address and port info.
804  * The string address may be in a standard numbers and dots notation or 
805  * may be a hostname. If hostname is specified, then the function will 
806  * resolve the host into the IP address.
807  *
808  * @see pj_sockaddr_in_init()
809  *
810  * @param af        Internet address family.
811  * @param addr      The IP socket address to be set.
812  * @param cp        The address string, which can be in a standard 
813  *                  dotted numbers or a hostname to be resolved.
814  * @param port      The port number, in host byte order.
815  *
816  * @return          Zero on success.
817  */
818 PJ_DECL(pj_status_t) pj_sockaddr_init(int af, 
819                                       pj_sockaddr *addr,
820                                       const pj_str_t *cp,
821                                       pj_uint16_t port);
822
823 /**
824  * Compare two socket addresses.
825  *
826  * @param addr1     First address.
827  * @param addr2     Second address.
828  *
829  * @return          Zero on equal, -1 if addr1 is less than addr2,
830  *                  and +1 if addr1 is more than addr2.
831  */
832 PJ_DECL(int) pj_sockaddr_cmp(const pj_sockaddr_t *addr1,
833                              const pj_sockaddr_t *addr2);
834
835 /**
836  * Get pointer to the address part of a socket address.
837  * 
838  * @param addr      Socket address.
839  *
840  * @return          Pointer to address part (sin_addr or sin6_addr,
841  *                  depending on address family)
842  */
843 PJ_DECL(void*) pj_sockaddr_get_addr(const pj_sockaddr_t *addr);
844
845 /**
846  * Check that a socket address contains a non-zero address part.
847  *
848  * @param addr      Socket address.
849  *
850  * @return          Non-zero if address is set to non-zero.
851  */
852 PJ_DECL(pj_bool_t) pj_sockaddr_has_addr(const pj_sockaddr_t *addr);
853
854 /**
855  * Get the address part length of a socket address, based on its address
856  * family. For PJ_AF_INET, the length will be sizeof(pj_in_addr), and
857  * for PJ_AF_INET6, the length will be sizeof(pj_in6_addr).
858  * 
859  * @param addr      Socket address.
860  *
861  * @return          Length in bytes.
862  */
863 PJ_DECL(unsigned) pj_sockaddr_get_addr_len(const pj_sockaddr_t *addr);
864
865 /**
866  * Get the socket address length, based on its address
867  * family. For PJ_AF_INET, the length will be sizeof(pj_sockaddr_in), and
868  * for PJ_AF_INET6, the length will be sizeof(pj_sockaddr_in6).
869  * 
870  * @param addr      Socket address.
871  *
872  * @return          Length in bytes.
873  */
874 PJ_DECL(unsigned) pj_sockaddr_get_len(const pj_sockaddr_t *addr);
875
876 /** 
877  * Copy only the address part (sin_addr/sin6_addr) of a socket address.
878  *
879  * @param dst       Destination socket address.
880  * @param src       Source socket address.
881  *
882  * @see @pj_sockaddr_cp()
883  */
884 PJ_DECL(void) pj_sockaddr_copy_addr(pj_sockaddr *dst,
885                                     const pj_sockaddr *src);
886 /**
887  * Copy socket address. This will copy the whole structure depending
888  * on the address family of the source socket address.
889  *
890  * @param dst       Destination socket address.
891  * @param src       Source socket address.
892  *
893  * @see @pj_sockaddr_copy_addr()
894  */
895 PJ_DECL(void) pj_sockaddr_cp(pj_sockaddr_t *dst, const pj_sockaddr_t *src);
896
897 /**
898  * Get the IP address of an IPv4 socket address.
899  * The address is returned as 32bit value in host byte order.
900  *
901  * @param addr      The IP socket address.
902  * @return          32bit address, in host byte order.
903  */
904 PJ_DECL(pj_in_addr) pj_sockaddr_in_get_addr(const pj_sockaddr_in *addr);
905
906 /**
907  * Set the IP address of an IPv4 socket address.
908  *
909  * @param addr      The IP socket address.
910  * @param hostaddr  The host address, in host byte order.
911  */
912 PJ_DECL(void) pj_sockaddr_in_set_addr(pj_sockaddr_in *addr,
913                                       pj_uint32_t hostaddr);
914
915 /**
916  * Set the IP address of an IP socket address from string address, 
917  * with resolving the host if necessary. The string address may be in a
918  * standard numbers and dots notation or may be a hostname. If hostname
919  * is specified, then the function will resolve the host into the IP
920  * address.
921  *
922  * @see pj_sockaddr_set_str_addr()
923  *
924  * @param addr      The IP socket address to be set.
925  * @param cp        The address string, which can be in a standard 
926  *                  dotted numbers or a hostname to be resolved.
927  *
928  * @return          PJ_SUCCESS on success.
929  */
930 PJ_DECL(pj_status_t) pj_sockaddr_in_set_str_addr( pj_sockaddr_in *addr,
931                                                   const pj_str_t *cp);
932
933 /**
934  * Set the IP address of an IPv4 or IPv6 socket address from string address,
935  * with resolving the host if necessary. The string address may be in a
936  * standard IPv6 or IPv6 address or may be a hostname. If hostname
937  * is specified, then the function will resolve the host into the IP
938  * address according to the address family.
939  *
940  * @param af        Address family.
941  * @param addr      The IP socket address to be set.
942  * @param cp        The address string, which can be in a standard 
943  *                  IP numbers (IPv4 or IPv6) or a hostname to be resolved.
944  *
945  * @return          PJ_SUCCESS on success.
946  */
947 PJ_DECL(pj_status_t) pj_sockaddr_set_str_addr(int af,
948                                               pj_sockaddr *addr,
949                                               const pj_str_t *cp);
950
951 /**
952  * Get the port number of a socket address, in host byte order. 
953  * This function can be used for both IPv4 and IPv6 socket address.
954  * 
955  * @param addr      Socket address.
956  *
957  * @return          Port number, in host byte order.
958  */
959 PJ_DECL(pj_uint16_t) pj_sockaddr_get_port(const pj_sockaddr_t *addr);
960
961 /**
962  * Get the transport layer port number of an Internet socket address.
963  * The port is returned in host byte order.
964  *
965  * @param addr      The IP socket address.
966  * @return          Port number, in host byte order.
967  */
968 PJ_DECL(pj_uint16_t) pj_sockaddr_in_get_port(const pj_sockaddr_in *addr);
969
970 /**
971  * Set the port number of an Internet socket address.
972  *
973  * @param addr      The socket address.
974  * @param hostport  The port number, in host byte order.
975  */
976 PJ_DECL(pj_status_t) pj_sockaddr_set_port(pj_sockaddr *addr, 
977                                           pj_uint16_t hostport);
978
979 /**
980  * Set the port number of an IPv4 socket address.
981  *
982  * @see pj_sockaddr_set_port()
983  *
984  * @param addr      The IP socket address.
985  * @param hostport  The port number, in host byte order.
986  */
987 PJ_DECL(void) pj_sockaddr_in_set_port(pj_sockaddr_in *addr, 
988                                       pj_uint16_t hostport);
989
990 /**
991  * Parse string containing IP address and optional port into socket address,
992  * possibly also with address family detection. This function supports both
993  * IPv4 and IPv6 parsing, however IPv6 parsing may only be done if IPv6 is
994  * enabled during compilation.
995  *
996  * This function supports parsing several formats. Sample IPv4 inputs and
997  * their default results::
998  *  - "10.0.0.1:80": address 10.0.0.1 and port 80.
999  *  - "10.0.0.1": address 10.0.0.1 and port zero.
1000  *  - "10.0.0.1:": address 10.0.0.1 and port zero.
1001  *  - "10.0.0.1:0": address 10.0.0.1 and port zero.
1002  *  - ":80": address 0.0.0.0 and port 80.
1003  *  - ":": address 0.0.0.0 and port 0.
1004  *  - "localhost": address 127.0.0.1 and port 0.
1005  *  - "localhost:": address 127.0.0.1 and port 0.
1006  *  - "localhost:80": address 127.0.0.1 and port 80.
1007  *
1008  * Sample IPv6 inputs and their default results:
1009  *  - "[fec0::01]:80": address fec0::01 and port 80
1010  *  - "[fec0::01]": address fec0::01 and port 0
1011  *  - "[fec0::01]:": address fec0::01 and port 0
1012  *  - "[fec0::01]:0": address fec0::01 and port 0
1013  *  - "fec0::01": address fec0::01 and port 0
1014  *  - "fec0::01:80": address fec0::01:80 and port 0
1015  *  - "::": address zero (::) and port 0
1016  *  - "[::]": address zero (::) and port 0
1017  *  - "[::]:": address zero (::) and port 0
1018  *  - ":::": address zero (::) and port 0
1019  *  - "[::]:80": address zero (::) and port 0
1020  *  - ":::80": address zero (::) and port 80
1021  *
1022  * Note: when the IPv6 socket address contains port number, the IP 
1023  * part of the socket address should be enclosed with square brackets, 
1024  * otherwise the port number will be included as part of the IP address
1025  * (see "fec0::01:80" example above).
1026  *
1027  * @param af        Optionally specify the address family to be used. If the
1028  *                  address family is to be deducted from the input, specify
1029  *                  pj_AF_UNSPEC() here. Other supported values are
1030  *                  #pj_AF_INET() and #pj_AF_INET6()
1031  * @param options   Additional options to assist the parsing, must be zero
1032  *                  for now.
1033  * @param str       The input string to be parsed.
1034  * @param addr      Pointer to store the result.
1035  *
1036  * @return          PJ_SUCCESS if the parsing is successful.
1037  *
1038  * @see pj_sockaddr_parse2()
1039  */
1040 PJ_DECL(pj_status_t) pj_sockaddr_parse(int af, unsigned options,
1041                                        const pj_str_t *str,
1042                                        pj_sockaddr *addr);
1043
1044 /**
1045  * This function is similar to #pj_sockaddr_parse(), except that it will not
1046  * convert the hostpart into IP address (thus possibly resolving the hostname
1047  * into a #pj_sockaddr. 
1048  *
1049  * Unlike #pj_sockaddr_parse(), this function has a limitation that if port 
1050  * number is specified in an IPv6 input string, the IP part of the IPv6 socket
1051  * address MUST be enclosed in square brackets, otherwise the port number will
1052  * be considered as part of the IPv6 IP address.
1053  *
1054  * @param af        Optionally specify the address family to be used. If the
1055  *                  address family is to be deducted from the input, specify
1056  *                  #pj_AF_UNSPEC() here. Other supported values are
1057  *                  #pj_AF_INET() and #pj_AF_INET6()
1058  * @param options   Additional options to assist the parsing, must be zero
1059  *                  for now.
1060  * @param str       The input string to be parsed.
1061  * @param hostpart  Optional pointer to store the host part of the socket 
1062  *                  address, with any brackets removed.
1063  * @param port      Optional pointer to store the port number. If port number
1064  *                  is not found, this will be set to zero upon return.
1065  * @param raf       Optional pointer to store the detected address family of
1066  *                  the input address.
1067  *
1068  * @return          PJ_SUCCESS if the parsing is successful.
1069  *
1070  * @see pj_sockaddr_parse()
1071  */
1072 PJ_DECL(pj_status_t) pj_sockaddr_parse2(int af, unsigned options,
1073                                         const pj_str_t *str,
1074                                         pj_str_t *hostpart,
1075                                         pj_uint16_t *port,
1076                                         int *raf);
1077
1078 /*****************************************************************************
1079  *
1080  * HOST NAME AND ADDRESS.
1081  *
1082  *****************************************************************************
1083  */
1084
1085 /**
1086  * Get system's host name.
1087  *
1088  * @return          The hostname, or empty string if the hostname can not
1089  *                  be identified.
1090  */
1091 PJ_DECL(const pj_str_t*) pj_gethostname(void);
1092
1093 /**
1094  * Get host's IP address, which the the first IP address that is resolved
1095  * from the hostname.
1096  *
1097  * @return          The host's IP address, PJ_INADDR_NONE if the host
1098  *                  IP address can not be identified.
1099  */
1100 PJ_DECL(pj_in_addr) pj_gethostaddr(void);
1101
1102
1103 /*****************************************************************************
1104  *
1105  * SOCKET API.
1106  *
1107  *****************************************************************************
1108  */
1109
1110 /**
1111  * Create new socket/endpoint for communication.
1112  *
1113  * @param family    Specifies a communication domain; this selects the
1114  *                  protocol family which will be used for communication.
1115  * @param type      The socket has the indicated type, which specifies the 
1116  *                  communication semantics.
1117  * @param protocol  Specifies  a  particular  protocol  to  be used with the
1118  *                  socket.  Normally only a single protocol exists to support 
1119  *                  a particular socket  type  within  a given protocol family, 
1120  *                  in which a case protocol can be specified as 0.
1121  * @param sock      New socket descriptor, or PJ_INVALID_SOCKET on error.
1122  *
1123  * @return          Zero on success.
1124  */
1125 PJ_DECL(pj_status_t) pj_sock_socket(int family, 
1126                                     int type, 
1127                                     int protocol,
1128                                     pj_sock_t *sock);
1129
1130 /**
1131  * Close the socket descriptor.
1132  *
1133  * @param sockfd    The socket descriptor.
1134  *
1135  * @return          Zero on success.
1136  */
1137 PJ_DECL(pj_status_t) pj_sock_close(pj_sock_t sockfd);
1138
1139
1140 /**
1141  * This function gives the socket sockfd the local address my_addr. my_addr is
1142  * addrlen bytes long.  Traditionally, this is called assigning a name to
1143  * a socket. When a socket is created with #pj_sock_socket(), it exists in a
1144  * name space (address family) but has no name assigned.
1145  *
1146  * @param sockfd    The socket desriptor.
1147  * @param my_addr   The local address to bind the socket to.
1148  * @param addrlen   The length of the address.
1149  *
1150  * @return          Zero on success.
1151  */
1152 PJ_DECL(pj_status_t) pj_sock_bind( pj_sock_t sockfd, 
1153                                    const pj_sockaddr_t *my_addr,
1154                                    int addrlen);
1155
1156 /**
1157  * Bind the IP socket sockfd to the given address and port.
1158  *
1159  * @param sockfd    The socket descriptor.
1160  * @param addr      Local address to bind the socket to, in host byte order.
1161  * @param port      The local port to bind the socket to, in host byte order.
1162  *
1163  * @return          Zero on success.
1164  */
1165 PJ_DECL(pj_status_t) pj_sock_bind_in( pj_sock_t sockfd, 
1166                                       pj_uint32_t addr,
1167                                       pj_uint16_t port);
1168
1169 #if PJ_HAS_TCP
1170 /**
1171  * Listen for incoming connection. This function only applies to connection
1172  * oriented sockets (such as PJ_SOCK_STREAM or PJ_SOCK_SEQPACKET), and it
1173  * indicates the willingness to accept incoming connections.
1174  *
1175  * @param sockfd        The socket descriptor.
1176  * @param backlog       Defines the maximum length the queue of pending
1177  *                      connections may grow to.
1178  *
1179  * @return              Zero on success.
1180  */
1181 PJ_DECL(pj_status_t) pj_sock_listen( pj_sock_t sockfd, 
1182                                      int backlog );
1183
1184 /**
1185  * Accept new connection on the specified connection oriented server socket.
1186  *
1187  * @param serverfd  The server socket.
1188  * @param newsock   New socket on success, of PJ_INVALID_SOCKET if failed.
1189  * @param addr      A pointer to sockaddr type. If the argument is not NULL,
1190  *                  it will be filled by the address of connecting entity.
1191  * @param addrlen   Initially specifies the length of the address, and upon
1192  *                  return will be filled with the exact address length.
1193  *
1194  * @return          Zero on success, or the error number.
1195  */
1196 PJ_DECL(pj_status_t) pj_sock_accept( pj_sock_t serverfd,
1197                                      pj_sock_t *newsock,
1198                                      pj_sockaddr_t *addr,
1199                                      int *addrlen);
1200 #endif
1201
1202 /**
1203  * The file descriptor sockfd must refer to a socket.  If the socket is of
1204  * type PJ_SOCK_DGRAM  then the serv_addr address is the address to which
1205  * datagrams are sent by default, and the only address from which datagrams
1206  * are received. If the socket is of type PJ_SOCK_STREAM or PJ_SOCK_SEQPACKET,
1207  * this call attempts to make a connection to another socket.  The
1208  * other socket is specified by serv_addr, which is an address (of length
1209  * addrlen) in the communications space of the  socket.  Each  communications
1210  * space interprets the serv_addr parameter in its own way.
1211  *
1212  * @param sockfd        The socket descriptor.
1213  * @param serv_addr     Server address to connect to.
1214  * @param addrlen       The length of server address.
1215  *
1216  * @return              Zero on success.
1217  */
1218 PJ_DECL(pj_status_t) pj_sock_connect( pj_sock_t sockfd,
1219                                       const pj_sockaddr_t *serv_addr,
1220                                       int addrlen);
1221
1222 /**
1223  * Return the address of peer which is connected to socket sockfd.
1224  *
1225  * @param sockfd        The socket descriptor.
1226  * @param addr          Pointer to sockaddr structure to which the address
1227  *                      will be returned.
1228  * @param namelen       Initially the length of the addr. Upon return the value
1229  *                      will be set to the actual length of the address.
1230  *
1231  * @return              Zero on success.
1232  */
1233 PJ_DECL(pj_status_t) pj_sock_getpeername(pj_sock_t sockfd,
1234                                           pj_sockaddr_t *addr,
1235                                           int *namelen);
1236
1237 /**
1238  * Return the current name of the specified socket.
1239  *
1240  * @param sockfd        The socket descriptor.
1241  * @param addr          Pointer to sockaddr structure to which the address
1242  *                      will be returned.
1243  * @param namelen       Initially the length of the addr. Upon return the value
1244  *                      will be set to the actual length of the address.
1245  *
1246  * @return              Zero on success.
1247  */
1248 PJ_DECL(pj_status_t) pj_sock_getsockname( pj_sock_t sockfd,
1249                                           pj_sockaddr_t *addr,
1250                                           int *namelen);
1251
1252 /**
1253  * Get socket option associated with a socket. Options may exist at multiple
1254  * protocol levels; they are always present at the uppermost socket level.
1255  *
1256  * @param sockfd        The socket descriptor.
1257  * @param level         The level which to get the option from.
1258  * @param optname       The option name.
1259  * @param optval        Identifies the buffer which the value will be
1260  *                      returned.
1261  * @param optlen        Initially contains the length of the buffer, upon
1262  *                      return will be set to the actual size of the value.
1263  *
1264  * @return              Zero on success.
1265  */
1266 PJ_DECL(pj_status_t) pj_sock_getsockopt( pj_sock_t sockfd,
1267                                          pj_uint16_t level,
1268                                          pj_uint16_t optname,
1269                                          void *optval,
1270                                          int *optlen);
1271 /**
1272  * Manipulate the options associated with a socket. Options may exist at 
1273  * multiple protocol levels; they are always present at the uppermost socket 
1274  * level.
1275  *
1276  * @param sockfd        The socket descriptor.
1277  * @param level         The level which to get the option from.
1278  * @param optname       The option name.
1279  * @param optval        Identifies the buffer which contain the value.
1280  * @param optlen        The length of the value.
1281  *
1282  * @return              PJ_SUCCESS or the status code.
1283  */
1284 PJ_DECL(pj_status_t) pj_sock_setsockopt( pj_sock_t sockfd,
1285                                          pj_uint16_t level,
1286                                          pj_uint16_t optname,
1287                                          const void *optval,
1288                                          int optlen);
1289
1290
1291 /**
1292  * Receives data stream or message coming to the specified socket.
1293  *
1294  * @param sockfd        The socket descriptor.
1295  * @param buf           The buffer to receive the data or message.
1296  * @param len           On input, the length of the buffer. On return,
1297  *                      contains the length of data received.
1298  * @param flags         Flags (such as pj_MSG_PEEK()).
1299  *
1300  * @return              PJ_SUCCESS or the error code.
1301  */
1302 PJ_DECL(pj_status_t) pj_sock_recv(pj_sock_t sockfd,
1303                                   void *buf,
1304                                   pj_ssize_t *len,
1305                                   unsigned flags);
1306
1307 /**
1308  * Receives data stream or message coming to the specified socket.
1309  *
1310  * @param sockfd        The socket descriptor.
1311  * @param buf           The buffer to receive the data or message.
1312  * @param len           On input, the length of the buffer. On return,
1313  *                      contains the length of data received.
1314  * @param flags         Flags (such as pj_MSG_PEEK()).
1315  * @param from          If not NULL, it will be filled with the source
1316  *                      address of the connection.
1317  * @param fromlen       Initially contains the length of from address,
1318  *                      and upon return will be filled with the actual
1319  *                      length of the address.
1320  *
1321  * @return              PJ_SUCCESS or the error code.
1322  */
1323 PJ_DECL(pj_status_t) pj_sock_recvfrom( pj_sock_t sockfd,
1324                                       void *buf,
1325                                       pj_ssize_t *len,
1326                                       unsigned flags,
1327                                       pj_sockaddr_t *from,
1328                                       int *fromlen);
1329
1330 /**
1331  * Transmit data to the socket.
1332  *
1333  * @param sockfd        Socket descriptor.
1334  * @param buf           Buffer containing data to be sent.
1335  * @param len           On input, the length of the data in the buffer.
1336  *                      Upon return, it will be filled with the length
1337  *                      of data sent.
1338  * @param flags         Flags (such as pj_MSG_DONTROUTE()).
1339  *
1340  * @return              PJ_SUCCESS or the status code.
1341  */
1342 PJ_DECL(pj_status_t) pj_sock_send(pj_sock_t sockfd,
1343                                   const void *buf,
1344                                   pj_ssize_t *len,
1345                                   unsigned flags);
1346
1347 /**
1348  * Transmit data to the socket to the specified address.
1349  *
1350  * @param sockfd        Socket descriptor.
1351  * @param buf           Buffer containing data to be sent.
1352  * @param len           On input, the length of the data in the buffer.
1353  *                      Upon return, it will be filled with the length
1354  *                      of data sent.
1355  * @param flags         Flags (such as pj_MSG_DONTROUTE()).
1356  * @param to            The address to send.
1357  * @param tolen         The length of the address in bytes.
1358  *
1359  * @return              PJ_SUCCESS or the status code.
1360  */
1361 PJ_DECL(pj_status_t) pj_sock_sendto(pj_sock_t sockfd,
1362                                     const void *buf,
1363                                     pj_ssize_t *len,
1364                                     unsigned flags,
1365                                     const pj_sockaddr_t *to,
1366                                     int tolen);
1367
1368 #if PJ_HAS_TCP
1369 /**
1370  * The shutdown call causes all or part of a full-duplex connection on the
1371  * socket associated with sockfd to be shut down.
1372  *
1373  * @param sockfd        The socket descriptor.
1374  * @param how           If how is PJ_SHUT_RD, further receptions will be 
1375  *                      disallowed. If how is PJ_SHUT_WR, further transmissions
1376  *                      will be disallowed. If how is PJ_SHUT_RDWR, further 
1377  *                      receptions andtransmissions will be disallowed.
1378  *
1379  * @return              Zero on success.
1380  */
1381 PJ_DECL(pj_status_t) pj_sock_shutdown( pj_sock_t sockfd,
1382                                        int how);
1383 #endif
1384
1385 /**
1386  * @}
1387  */
1388
1389
1390 PJ_END_DECL
1391
1392 #endif  /* __PJ_SOCK_H__ */
1393