← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/pjlib/include/pj/sock.h

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

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjlib/include/pj/sock.h
 
1
/* $Id: sock.h 4343 2013-02-07 09:35:34Z nanang $ */
 
2
/* 
 
3
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 
4
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
 
5
 *
 
6
 * This program is free software; you can redistribute it and/or modify
 
7
 * it under the terms of the GNU General Public License as published by
 
8
 * the Free Software Foundation; either version 2 of the License, or
 
9
 * (at your option) any later version.
 
10
 *
 
11
 * This program is distributed in the hope that it will be useful,
 
12
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
13
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
14
 * GNU General Public License for more details.
 
15
 *
 
16
 * You should have received a copy of the GNU General Public License
 
17
 * along with this program; if not, write to the Free Software
 
18
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 
19
 */
 
20
#ifndef __PJ_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
/**
 
1170
 * Bind the IP socket sockfd to the given address and a random port in the
 
1171
 * specified range.
 
1172
 *
 
1173
 * @param sockfd        The socket desriptor.
 
1174
 * @param addr          The local address and port to bind the socket to.
 
1175
 * @param port_range    The port range, relative the to start port number
 
1176
 *                      specified in port field in #addr. Note that if the
 
1177
 *                      port is zero, this param will be ignored.
 
1178
 * @param max_try       Maximum retries.
 
1179
 *
 
1180
 * @return              Zero on success.
 
1181
 */
 
1182
PJ_DECL(pj_status_t) pj_sock_bind_random( pj_sock_t sockfd,
 
1183
                                          const pj_sockaddr_t *addr,
 
1184
                                          pj_uint16_t port_range,
 
1185
                                          pj_uint16_t max_try);
 
1186
 
 
1187
#if PJ_HAS_TCP
 
1188
/**
 
1189
 * Listen for incoming connection. This function only applies to connection
 
1190
 * oriented sockets (such as PJ_SOCK_STREAM or PJ_SOCK_SEQPACKET), and it
 
1191
 * indicates the willingness to accept incoming connections.
 
1192
 *
 
1193
 * @param sockfd        The socket descriptor.
 
1194
 * @param backlog       Defines the maximum length the queue of pending
 
1195
 *                      connections may grow to.
 
1196
 *
 
1197
 * @return              Zero on success.
 
1198
 */
 
1199
PJ_DECL(pj_status_t) pj_sock_listen( pj_sock_t sockfd, 
 
1200
                                     int backlog );
 
1201
 
 
1202
/**
 
1203
 * Accept new connection on the specified connection oriented server socket.
 
1204
 *
 
1205
 * @param serverfd  The server socket.
 
1206
 * @param newsock   New socket on success, of PJ_INVALID_SOCKET if failed.
 
1207
 * @param addr      A pointer to sockaddr type. If the argument is not NULL,
 
1208
 *                  it will be filled by the address of connecting entity.
 
1209
 * @param addrlen   Initially specifies the length of the address, and upon
 
1210
 *                  return will be filled with the exact address length.
 
1211
 *
 
1212
 * @return          Zero on success, or the error number.
 
1213
 */
 
1214
PJ_DECL(pj_status_t) pj_sock_accept( pj_sock_t serverfd,
 
1215
                                     pj_sock_t *newsock,
 
1216
                                     pj_sockaddr_t *addr,
 
1217
                                     int *addrlen);
 
1218
#endif
 
1219
 
 
1220
/**
 
1221
 * The file descriptor sockfd must refer to a socket.  If the socket is of
 
1222
 * type PJ_SOCK_DGRAM  then the serv_addr address is the address to which
 
1223
 * datagrams are sent by default, and the only address from which datagrams
 
1224
 * are received. If the socket is of type PJ_SOCK_STREAM or PJ_SOCK_SEQPACKET,
 
1225
 * this call attempts to make a connection to another socket.  The
 
1226
 * other socket is specified by serv_addr, which is an address (of length
 
1227
 * addrlen) in the communications space of the  socket.  Each  communications
 
1228
 * space interprets the serv_addr parameter in its own way.
 
1229
 *
 
1230
 * @param sockfd        The socket descriptor.
 
1231
 * @param serv_addr     Server address to connect to.
 
1232
 * @param addrlen       The length of server address.
 
1233
 *
 
1234
 * @return              Zero on success.
 
1235
 */
 
1236
PJ_DECL(pj_status_t) pj_sock_connect( pj_sock_t sockfd,
 
1237
                                      const pj_sockaddr_t *serv_addr,
 
1238
                                      int addrlen);
 
1239
 
 
1240
/**
 
1241
 * Return the address of peer which is connected to socket sockfd.
 
1242
 *
 
1243
 * @param sockfd        The socket descriptor.
 
1244
 * @param addr          Pointer to sockaddr structure to which the address
 
1245
 *                      will be returned.
 
1246
 * @param namelen       Initially the length of the addr. Upon return the value
 
1247
 *                      will be set to the actual length of the address.
 
1248
 *
 
1249
 * @return              Zero on success.
 
1250
 */
 
1251
PJ_DECL(pj_status_t) pj_sock_getpeername(pj_sock_t sockfd,
 
1252
                                          pj_sockaddr_t *addr,
 
1253
                                          int *namelen);
 
1254
 
 
1255
/**
 
1256
 * Return the current name of the specified socket.
 
1257
 *
 
1258
 * @param sockfd        The socket descriptor.
 
1259
 * @param addr          Pointer to sockaddr structure to which the address
 
1260
 *                      will be returned.
 
1261
 * @param namelen       Initially the length of the addr. Upon return the value
 
1262
 *                      will be set to the actual length of the address.
 
1263
 *
 
1264
 * @return              Zero on success.
 
1265
 */
 
1266
PJ_DECL(pj_status_t) pj_sock_getsockname( pj_sock_t sockfd,
 
1267
                                          pj_sockaddr_t *addr,
 
1268
                                          int *namelen);
 
1269
 
 
1270
/**
 
1271
 * Get socket option associated with a socket. Options may exist at multiple
 
1272
 * protocol levels; they are always present at the uppermost socket level.
 
1273
 *
 
1274
 * @param sockfd        The socket descriptor.
 
1275
 * @param level         The level which to get the option from.
 
1276
 * @param optname       The option name.
 
1277
 * @param optval        Identifies the buffer which the value will be
 
1278
 *                      returned.
 
1279
 * @param optlen        Initially contains the length of the buffer, upon
 
1280
 *                      return will be set to the actual size of the value.
 
1281
 *
 
1282
 * @return              Zero on success.
 
1283
 */
 
1284
PJ_DECL(pj_status_t) pj_sock_getsockopt( pj_sock_t sockfd,
 
1285
                                         pj_uint16_t level,
 
1286
                                         pj_uint16_t optname,
 
1287
                                         void *optval,
 
1288
                                         int *optlen);
 
1289
/**
 
1290
 * Manipulate the options associated with a socket. Options may exist at 
 
1291
 * multiple protocol levels; they are always present at the uppermost socket 
 
1292
 * level.
 
1293
 *
 
1294
 * @param sockfd        The socket descriptor.
 
1295
 * @param level         The level which to get the option from.
 
1296
 * @param optname       The option name.
 
1297
 * @param optval        Identifies the buffer which contain the value.
 
1298
 * @param optlen        The length of the value.
 
1299
 *
 
1300
 * @return              PJ_SUCCESS or the status code.
 
1301
 */
 
1302
PJ_DECL(pj_status_t) pj_sock_setsockopt( pj_sock_t sockfd,
 
1303
                                         pj_uint16_t level,
 
1304
                                         pj_uint16_t optname,
 
1305
                                         const void *optval,
 
1306
                                         int optlen);
 
1307
 
 
1308
 
 
1309
/**
 
1310
 * Receives data stream or message coming to the specified socket.
 
1311
 *
 
1312
 * @param sockfd        The socket descriptor.
 
1313
 * @param buf           The buffer to receive the data or message.
 
1314
 * @param len           On input, the length of the buffer. On return,
 
1315
 *                      contains the length of data received.
 
1316
 * @param flags         Flags (such as pj_MSG_PEEK()).
 
1317
 *
 
1318
 * @return              PJ_SUCCESS or the error code.
 
1319
 */
 
1320
PJ_DECL(pj_status_t) pj_sock_recv(pj_sock_t sockfd,
 
1321
                                  void *buf,
 
1322
                                  pj_ssize_t *len,
 
1323
                                  unsigned flags);
 
1324
 
 
1325
/**
 
1326
 * Receives data stream or message coming to the specified socket.
 
1327
 *
 
1328
 * @param sockfd        The socket descriptor.
 
1329
 * @param buf           The buffer to receive the data or message.
 
1330
 * @param len           On input, the length of the buffer. On return,
 
1331
 *                      contains the length of data received.
 
1332
 * @param flags         Flags (such as pj_MSG_PEEK()).
 
1333
 * @param from          If not NULL, it will be filled with the source
 
1334
 *                      address of the connection.
 
1335
 * @param fromlen       Initially contains the length of from address,
 
1336
 *                      and upon return will be filled with the actual
 
1337
 *                      length of the address.
 
1338
 *
 
1339
 * @return              PJ_SUCCESS or the error code.
 
1340
 */
 
1341
PJ_DECL(pj_status_t) pj_sock_recvfrom( pj_sock_t sockfd,
 
1342
                                      void *buf,
 
1343
                                      pj_ssize_t *len,
 
1344
                                      unsigned flags,
 
1345
                                      pj_sockaddr_t *from,
 
1346
                                      int *fromlen);
 
1347
 
 
1348
/**
 
1349
 * Transmit data to the socket.
 
1350
 *
 
1351
 * @param sockfd        Socket descriptor.
 
1352
 * @param buf           Buffer containing data to be sent.
 
1353
 * @param len           On input, the length of the data in the buffer.
 
1354
 *                      Upon return, it will be filled with the length
 
1355
 *                      of data sent.
 
1356
 * @param flags         Flags (such as pj_MSG_DONTROUTE()).
 
1357
 *
 
1358
 * @return              PJ_SUCCESS or the status code.
 
1359
 */
 
1360
PJ_DECL(pj_status_t) pj_sock_send(pj_sock_t sockfd,
 
1361
                                  const void *buf,
 
1362
                                  pj_ssize_t *len,
 
1363
                                  unsigned flags);
 
1364
 
 
1365
/**
 
1366
 * Transmit data to the socket to the specified address.
 
1367
 *
 
1368
 * @param sockfd        Socket descriptor.
 
1369
 * @param buf           Buffer containing data to be sent.
 
1370
 * @param len           On input, the length of the data in the buffer.
 
1371
 *                      Upon return, it will be filled with the length
 
1372
 *                      of data sent.
 
1373
 * @param flags         Flags (such as pj_MSG_DONTROUTE()).
 
1374
 * @param to            The address to send.
 
1375
 * @param tolen         The length of the address in bytes.
 
1376
 *
 
1377
 * @return              PJ_SUCCESS or the status code.
 
1378
 */
 
1379
PJ_DECL(pj_status_t) pj_sock_sendto(pj_sock_t sockfd,
 
1380
                                    const void *buf,
 
1381
                                    pj_ssize_t *len,
 
1382
                                    unsigned flags,
 
1383
                                    const pj_sockaddr_t *to,
 
1384
                                    int tolen);
 
1385
 
 
1386
#if PJ_HAS_TCP
 
1387
/**
 
1388
 * The shutdown call causes all or part of a full-duplex connection on the
 
1389
 * socket associated with sockfd to be shut down.
 
1390
 *
 
1391
 * @param sockfd        The socket descriptor.
 
1392
 * @param how           If how is PJ_SHUT_RD, further receptions will be 
 
1393
 *                      disallowed. If how is PJ_SHUT_WR, further transmissions
 
1394
 *                      will be disallowed. If how is PJ_SHUT_RDWR, further 
 
1395
 *                      receptions andtransmissions will be disallowed.
 
1396
 *
 
1397
 * @return              Zero on success.
 
1398
 */
 
1399
PJ_DECL(pj_status_t) pj_sock_shutdown( pj_sock_t sockfd,
 
1400
                                       int how);
 
1401
#endif
 
1402
 
 
1403
/**
 
1404
 * @}
 
1405
 */
 
1406
 
 
1407
 
 
1408
PJ_END_DECL
 
1409
 
 
1410
#endif  /* __PJ_SOCK_H__ */
 
1411