res/pjproject/pjlib/include/pj/sock.h

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