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