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