PageRenderTime 7ms CodeModel.GetById 11ms app.highlight 25ms RepoModel.GetById 1ms app.codeStats 0ms

/pjlib/include/pj/sock.h

https://bitbucket.org/secollab/pjsip-mikey-sakke
C Header | 1411 lines | 334 code | 188 blank | 889 comment | 7 complexity | 7cad325fbefc82c584b2dc758c2a903c MD5 | raw file
   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
  30PJ_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() */
  65extern const pj_uint16_t PJ_AF_UNSPEC;
  66
  67/** Unix domain socket.	@see pj_AF_UNIX() */
  68extern 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() */
  74extern const pj_uint16_t PJ_AF_INET;
  75
  76/** IP version 6. @see pj_AF_INET6() */
  77extern const pj_uint16_t PJ_AF_INET6;
  78
  79/** Packet family. @see pj_AF_PACKET() */
  80extern const pj_uint16_t PJ_AF_PACKET;
  81
  82/** IRDA sockets. @see pj_AF_IRDA() */
  83extern 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() */
 131extern const pj_uint16_t PJ_SOCK_STREAM;
 132
 133/** Connectionless, unreliable datagrams of fixed maximum lengths.
 134 *  @see pj_SOCK_DGRAM() */
 135extern const pj_uint16_t PJ_SOCK_DGRAM;
 136
 137/** Raw protocol interface. @see pj_SOCK_RAW() */
 138extern const pj_uint16_t PJ_SOCK_RAW;
 139
 140/** Reliably-delivered messages.  @see pj_SOCK_RDM() */
 141extern 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() */
 176extern const pj_uint16_t PJ_SOL_SOCKET;
 177/** IP level. @see pj_SOL_IP() */
 178extern const pj_uint16_t PJ_SOL_IP;
 179/** TCP level. @see pj_SOL_TCP() */
 180extern const pj_uint16_t PJ_SOL_TCP;
 181/** UDP level. @see pj_SOL_UDP() */
 182extern const pj_uint16_t PJ_SOL_UDP;
 183/** IP version 6. @see pj_SOL_IPV6() */
 184extern 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() */
 223extern 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() */
 233extern const pj_uint16_t PJ_IPTOS_LOWDELAY;
 234
 235/** Optimize throughput. @see pj_IPTOS_THROUGHPUT() */
 236extern const pj_uint16_t PJ_IPTOS_THROUGHPUT;
 237
 238/** Optimize for reliability. @see pj_IPTOS_RELIABILITY() */
 239extern const pj_uint16_t PJ_IPTOS_RELIABILITY;
 240
 241/** "filler data" where slow transmission does't matter.
 242 *  @see pj_IPTOS_MINCOST() */
 243extern 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() */
 285extern const pj_uint16_t PJ_SO_TYPE;
 286
 287/** Buffer size for receive. @see pj_SO_RCVBUF() */
 288extern const pj_uint16_t PJ_SO_RCVBUF;
 289
 290/** Buffer size for send. @see pj_SO_SNDBUF() */
 291extern const pj_uint16_t PJ_SO_SNDBUF;
 292
 293/** Disables the Nagle algorithm for send coalescing. @see pj_TCP_NODELAY */
 294extern 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 */
 298extern const pj_uint16_t PJ_SO_REUSEADDR;
 299
 300/** Do not generate SIGPIPE. @see pj_SO_NOSIGPIPE */
 301extern const pj_uint16_t PJ_SO_NOSIGPIPE;
 302
 303/** Set the protocol-defined priority for all packets to be sent on socket.
 304 */
 305extern const pj_uint16_t PJ_SO_PRIORITY;
 306
 307/** IP multicast interface. @see pj_IP_MULTICAST_IF() */
 308extern const pj_uint16_t PJ_IP_MULTICAST_IF;
 309 
 310/** IP multicast ttl. @see pj_IP_MULTICAST_TTL() */
 311extern const pj_uint16_t PJ_IP_MULTICAST_TTL;
 312
 313/** IP multicast loopback. @see pj_IP_MULTICAST_LOOP() */
 314extern const pj_uint16_t PJ_IP_MULTICAST_LOOP;
 315
 316/** Add an IP group membership. @see pj_IP_ADD_MEMBERSHIP() */
 317extern const pj_uint16_t PJ_IP_ADD_MEMBERSHIP;
 318
 319/** Drop an IP group membership. @see pj_IP_DROP_MEMBERSHIP() */
 320extern 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() */
 403extern const int PJ_MSG_OOB;
 404
 405/** Peek, don't remove from buffer. @see pj_MSG_PEEK() */
 406extern const int PJ_MSG_PEEK;
 407
 408/** Don't route. @see pj_MSG_DONTROUTE() */
 409extern 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 */
 436typedef 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 */
 480typedef 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 */
 512struct 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 */
 531typedef 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 */
 566typedef 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 */
 589typedef 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 */
 603typedef 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 */
 614typedef 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 */
 633PJ_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 */
 641PJ_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 */
 649PJ_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 */
 657PJ_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 */
 666PJ_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 */
 678PJ_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 */
 695PJ_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 */
 716PJ_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 */
 736PJ_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 */
 751PJ_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 */
 767PJ_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 */
 781PJ_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 */
 798PJ_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 */
 818PJ_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 */
 832PJ_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 */
 843PJ_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 */
 852PJ_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 */
 863PJ_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 */
 874PJ_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 */
 884PJ_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 */
 895PJ_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 */
 904PJ_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 */
 912PJ_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 */
 930PJ_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 */
 947PJ_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 */
 959PJ_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 */
 968PJ_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 */
 976PJ_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 */
 987PJ_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 */
1040PJ_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 */
1072PJ_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 */
1091PJ_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 */
1100PJ_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 */
1125PJ_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 */
1137PJ_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 */
1152PJ_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 */
1165PJ_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 */
1182PJ_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 */
1199PJ_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 */
1214PJ_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 */
1236PJ_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 */
1251PJ_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 */
1266PJ_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 */
1284PJ_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 */
1302PJ_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 */
1320PJ_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 */
1341PJ_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 */
1360PJ_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 */
1379PJ_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 */
1399PJ_DECL(pj_status_t) pj_sock_shutdown( pj_sock_t sockfd,
1400				       int how);
1401#endif
1402
1403/**
1404 * @}
1405 */
1406
1407
1408PJ_END_DECL
1409
1410#endif	/* __PJ_SOCK_H__ */
1411