00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2010, Digium, Inc. 00005 * 00006 * Viagénie <asteriskv6@viagenie.ca> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief Network socket handling 00021 */ 00022 00023 #ifndef _ASTERISK_NETSOCK2_H 00024 #define _ASTERISK_NETSOCK2_H 00025 00026 #if defined(__cplusplus) || defined(c_plusplus) 00027 extern "C" { 00028 #endif 00029 00030 #include <sys/socket.h> 00031 00032 #include <netinet/in.h> 00033 00034 /*! 00035 * Values for address families that we support. This is reproduced from socket.h 00036 * because we do not want users to include that file. Only netsock2.c should 00037 * ever include socket.h. 00038 */ 00039 enum { 00040 AST_AF_UNSPEC = 0, 00041 AST_AF_INET = 2, 00042 AST_AF_INET6 = 10, 00043 }; 00044 00045 /*! 00046 * \brief Socket address structure. 00047 * 00048 * \details 00049 * The first member is big enough to contain addresses of any 00050 * family. The second member contains the length (in bytes) used 00051 * in the first member. 00052 * 00053 * \note 00054 * Some BSDs have the length embedded in sockaddr structs. We 00055 * ignore them. (This is the right thing to do.) 00056 * 00057 * \note 00058 * It is important to always initialize ast_sockaddr before use 00059 * -- even if they are passed to ast_sockaddr_copy() as the 00060 * underlying storage could be bigger than what ends up being 00061 * copied -- leaving part of the data unitialized. 00062 */ 00063 struct ast_sockaddr { 00064 struct sockaddr_storage ss; 00065 socklen_t len; 00066 }; 00067 00068 /*! 00069 * \brief 00070 * Convert an IPv4-mapped IPv6 address into an IPv4 address. 00071 * 00072 * \warning You should rarely need this function. Only call this 00073 * if you know what you're doing. 00074 * 00075 * \param addr The IPv4-mapped address to convert 00076 * \param mapped_addr The resulting IPv4 address 00077 * \retval 0 Unable to make the conversion 00078 * \retval 1 Successful conversion 00079 */ 00080 int ast_sockaddr_ipv4_mapped(const struct ast_sockaddr *addr, struct ast_sockaddr *ast_mapped); 00081 00082 /*! 00083 * \since 1.8 00084 * 00085 * \brief 00086 * Checks if the ast_sockaddr is null. "null" in this sense essentially 00087 * means uninitialized, or having a 0 length. 00088 * 00089 * \param addr Pointer to the ast_sockaddr we wish to check 00090 * \retval 1 \a addr is null 00091 * \retval 0 \a addr is non-null. 00092 */ 00093 static inline int ast_sockaddr_isnull(const struct ast_sockaddr *addr) 00094 { 00095 return !addr || addr->len == 0; 00096 } 00097 00098 /*! 00099 * \since 1.8 00100 * 00101 * \brief 00102 * Sets address \a addr to null. 00103 * 00104 * \retval void 00105 */ 00106 static inline void ast_sockaddr_setnull(struct ast_sockaddr *addr) 00107 { 00108 addr->len = 0; 00109 } 00110 00111 /*! 00112 * \since 1.8 00113 * 00114 * \brief 00115 * Copies the data from one ast_sockaddr to another 00116 * 00117 * \param dst The destination ast_sockaddr 00118 * \param src The source ast_sockaddr 00119 * \retval void 00120 */ 00121 static inline void ast_sockaddr_copy(struct ast_sockaddr *dst, 00122 const struct ast_sockaddr *src) 00123 { 00124 memcpy(dst, src, src->len); 00125 dst->len = src->len; 00126 }; 00127 00128 /*! 00129 * \since 1.8 00130 * 00131 * \brief 00132 * Compares two ast_sockaddr structures 00133 * 00134 * \retval -1 \a a is lexicographically smaller than \a b 00135 * \retval 0 \a a is equal to \a b 00136 * \retval 1 \a b is lexicographically smaller than \a a 00137 */ 00138 int ast_sockaddr_cmp(const struct ast_sockaddr *a, const struct ast_sockaddr *b); 00139 00140 /*! 00141 * \since 1.8 00142 * 00143 * \brief 00144 * Compares the addresses of two ast_sockaddr structures. 00145 * 00146 * \retval -1 \a a is lexicographically smaller than \a b 00147 * \retval 0 \a a is equal to \a b 00148 * \retval 1 \a b is lexicographically smaller than \a a 00149 */ 00150 int ast_sockaddr_cmp_addr(const struct ast_sockaddr *a, const struct ast_sockaddr *b); 00151 00152 #define AST_SOCKADDR_STR_ADDR (1 << 0) 00153 #define AST_SOCKADDR_STR_PORT (1 << 1) 00154 #define AST_SOCKADDR_STR_BRACKETS (1 << 2) 00155 #define AST_SOCKADDR_STR_REMOTE (1 << 3) 00156 #define AST_SOCKADDR_STR_HOST (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_BRACKETS) 00157 #define AST_SOCKADDR_STR_DEFAULT (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT) 00158 #define AST_SOCKADDR_STR_ADDR_REMOTE (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_REMOTE) 00159 #define AST_SOCKADDR_STR_HOST_REMOTE (AST_SOCKADDR_STR_HOST | AST_SOCKADDR_STR_REMOTE) 00160 #define AST_SOCKADDR_STR_DEFAULT_REMOTE (AST_SOCKADDR_STR_DEFAULT | AST_SOCKADDR_STR_REMOTE) 00161 #define AST_SOCKADDR_STR_FORMAT_MASK (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT | AST_SOCKADDR_STR_BRACKETS) 00162 00163 /*! 00164 * \since 1.8 00165 * 00166 * \brief 00167 * Convert a socket address to a string. 00168 * 00169 * \details 00170 * This will be of the form a.b.c.d:xyz 00171 * for IPv4 and [a:b:c:...:d]:xyz for IPv6. 00172 * 00173 * This function is thread-safe. The returned string is on static 00174 * thread-specific storage. 00175 * 00176 * \param addr The input to be stringified 00177 * \param format one of the following: 00178 * AST_SOCKADDR_STR_DEFAULT: 00179 * a.b.c.d:xyz for IPv4 00180 * [a:b:c:...:d]:xyz for IPv6. 00181 * AST_SOCKADDR_STR_ADDR: address only 00182 * a.b.c.d for IPv4 00183 * a:b:c:...:d for IPv6. 00184 * AST_SOCKADDR_STR_HOST: address only, suitable for a URL 00185 * a.b.c.d for IPv4 00186 * [a:b:c:...:d] for IPv6. 00187 * AST_SOCKADDR_STR_PORT: port only 00188 * 00189 * \note The string pointer returned by this function will point to a string that 00190 * will be changed whenever any form of ast_sockaddr_stringify_fmt is called on that 00191 * thread. Because of this, it is important that if you use this function, you use the 00192 * string before another use of this function is made elsewhere in the same thread. 00193 * The easiest way to accomplish this is by immediately copying the string to a buffer 00194 * with something like ast_strdupa. 00195 * 00196 * \retval "(null)" \a addr is null 00197 * \retval "" An error occurred during processing 00198 * \retval string The stringified form of the address 00199 */ 00200 char *ast_sockaddr_stringify_fmt(const struct ast_sockaddr *addr, int format); 00201 00202 /*! 00203 * \since 1.8 00204 * 00205 * \brief 00206 * Wrapper around ast_sockaddr_stringify_fmt() with default format 00207 * 00208 * \return same as ast_sockaddr_stringify_fmt() 00209 */ 00210 static inline char *ast_sockaddr_stringify(const struct ast_sockaddr *addr) 00211 { 00212 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT); 00213 } 00214 00215 /*! 00216 * \since 1.8 00217 * 00218 * \brief 00219 * Wrapper around ast_sockaddr_stringify_fmt() with default format 00220 * 00221 * \note This address will be suitable for passing to a remote machine via the 00222 * application layer. For example, the scope-id on a link-local IPv6 address 00223 * will be stripped. 00224 * 00225 * \return same as ast_sockaddr_stringify_fmt() 00226 */ 00227 static inline char *ast_sockaddr_stringify_remote(const struct ast_sockaddr *addr) 00228 { 00229 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT_REMOTE); 00230 } 00231 00232 /*! 00233 * \since 1.8 00234 * 00235 * \brief 00236 * Wrapper around ast_sockaddr_stringify_fmt() to return an address only 00237 * 00238 * \return same as ast_sockaddr_stringify_fmt() 00239 */ 00240 static inline char *ast_sockaddr_stringify_addr(const struct ast_sockaddr *addr) 00241 { 00242 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR); 00243 } 00244 00245 /*! 00246 * \since 1.8 00247 * 00248 * \brief 00249 * Wrapper around ast_sockaddr_stringify_fmt() to return an address only 00250 * 00251 * \note This address will be suitable for passing to a remote machine via the 00252 * application layer. For example, the scope-id on a link-local IPv6 address 00253 * will be stripped. 00254 * 00255 * \return same as ast_sockaddr_stringify_fmt() 00256 */ 00257 static inline char *ast_sockaddr_stringify_addr_remote(const struct ast_sockaddr *addr) 00258 { 00259 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR_REMOTE); 00260 } 00261 00262 /*! 00263 * \since 1.8 00264 * 00265 * \brief 00266 * Wrapper around ast_sockaddr_stringify_fmt() to return an address only, 00267 * suitable for a URL (with brackets for IPv6). 00268 * 00269 * \return same as ast_sockaddr_stringify_fmt() 00270 */ 00271 static inline char *ast_sockaddr_stringify_host(const struct ast_sockaddr *addr) 00272 { 00273 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST); 00274 } 00275 00276 /*! 00277 * \since 1.8 00278 * 00279 * \brief 00280 * Wrapper around ast_sockaddr_stringify_fmt() to return an address only, 00281 * suitable for a URL (with brackets for IPv6). 00282 * 00283 * \note This address will be suitable for passing to a remote machine via the 00284 * application layer. For example, the scope-id on a link-local IPv6 address 00285 * will be stripped. 00286 * 00287 * \return same as ast_sockaddr_stringify_fmt() 00288 */ 00289 static inline char *ast_sockaddr_stringify_host_remote(const struct ast_sockaddr *addr) 00290 { 00291 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST_REMOTE); 00292 } 00293 00294 /*! 00295 * \since 1.8 00296 * 00297 * \brief 00298 * Wrapper around ast_sockaddr_stringify_fmt() to return a port only 00299 * 00300 * \return same as ast_sockaddr_stringify_fmt() 00301 */ 00302 static inline char *ast_sockaddr_stringify_port(const struct ast_sockaddr *addr) 00303 { 00304 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_PORT); 00305 } 00306 00307 /*! 00308 * \since 1.8 00309 * 00310 * \brief 00311 * Splits a string into its host and port components 00312 * 00313 * \param str[in] The string to parse. May be modified by writing a NUL at the end of 00314 * the host part. 00315 * \param host[out] Pointer to the host component within \a str. 00316 * \param port[out] Pointer to the port component within \a str. 00317 * \param flags If set to zero, a port MAY be present. If set to PARSE_PORT_IGNORE, a 00318 * port MAY be present but will be ignored. If set to PARSE_PORT_REQUIRE, 00319 * a port MUST be present. If set to PARSE_PORT_FORBID, a port MUST NOT 00320 * be present. 00321 * 00322 * \retval 1 Success 00323 * \retval 0 Failure 00324 */ 00325 int ast_sockaddr_split_hostport(char *str, char **host, char **port, int flags); 00326 00327 /*! 00328 * \since 1.8 00329 * 00330 * \brief 00331 * Parse an IPv4 or IPv6 address string. 00332 * 00333 * \details 00334 * Parses a string containing an IPv4 or IPv6 address followed by an optional 00335 * port (separated by a colon) into a struct ast_sockaddr. The allowed formats 00336 * are the following: 00337 * 00338 * a.b.c.d 00339 * a.b.c.d:port 00340 * a:b:c:...:d 00341 * [a:b:c:...:d] 00342 * [a:b:c:...:d]:port 00343 * 00344 * Host names are NOT allowed. 00345 * 00346 * \param[out] addr The resulting ast_sockaddr 00347 * \param str The string to parse 00348 * \param flags If set to zero, a port MAY be present. If set to 00349 * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to 00350 * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a 00351 * port MUST NOT be present. 00352 * 00353 * \retval 1 Success 00354 * \retval 0 Failure 00355 */ 00356 int ast_sockaddr_parse(struct ast_sockaddr *addr, const char *str, int flags); 00357 00358 /*! 00359 * \since 1.8 00360 * 00361 * \brief 00362 * Parses a string with an IPv4 or IPv6 address and place results into an array 00363 * 00364 * \details 00365 * Parses a string containing a host name or an IPv4 or IPv6 address followed 00366 * by an optional port (separated by a colon). The result is returned into a 00367 * array of struct ast_sockaddr. Allowed formats for str are the following: 00368 * 00369 * hostname:port 00370 * host.example.com:port 00371 * a.b.c.d 00372 * a.b.c.d:port 00373 * a:b:c:...:d 00374 * [a:b:c:...:d] 00375 * [a:b:c:...:d]:port 00376 * 00377 * \param[out] addrs The resulting array of ast_sockaddrs 00378 * \param str The string to parse 00379 * \param flags If set to zero, a port MAY be present. If set to 00380 * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to 00381 * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a 00382 * port MUST NOT be present. 00383 * 00384 * \param family Only addresses of the given family will be returned. Use 0 or 00385 * AST_SOCKADDR_UNSPEC to get addresses of all families. 00386 * 00387 * \retval 0 Failure 00388 * \retval non-zero The number of elements in addrs array. 00389 */ 00390 int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str, 00391 int flags, int family); 00392 00393 /*! 00394 * \since 1.8 00395 * 00396 * \brief 00397 * Get the port number of a socket address. 00398 * 00399 * \warning Do not use this function unless you really know what you are doing. 00400 * And "I want the port number" is not knowing what you are doing. 00401 * 00402 * \retval 0 Address is null 00403 * \retval non-zero The port number of the ast_sockaddr 00404 */ 00405 #define ast_sockaddr_port(addr) _ast_sockaddr_port(addr, __FILE__, __LINE__, __PRETTY_FUNCTION__) 00406 uint16_t _ast_sockaddr_port(const struct ast_sockaddr *addr, const char *file, int line, const char *func); 00407 00408 /*! 00409 * \since 1.8 00410 * 00411 * \brief 00412 * Sets the port number of a socket address. 00413 * 00414 * \warning Do not use this function unless you really know what you are doing. 00415 * And "I want the port number" is not knowing what you are doing. 00416 * 00417 * \param addr Address on which to set the port 00418 * \param port The port you wish to set the address to use 00419 * \retval void 00420 */ 00421 #define ast_sockaddr_set_port(addr,port) _ast_sockaddr_set_port(addr,port,__FILE__,__LINE__,__PRETTY_FUNCTION__) 00422 void _ast_sockaddr_set_port(struct ast_sockaddr *addr, uint16_t port, const char *file, int line, const char *func); 00423 00424 /*! 00425 * \since 1.8 00426 * 00427 * \brief 00428 * Get an IPv4 address of an ast_sockaddr 00429 * 00430 * \warning You should rarely need this function. Only use if you know what 00431 * you're doing. 00432 * \return IPv4 address in network byte order 00433 */ 00434 uint32_t ast_sockaddr_ipv4(const struct ast_sockaddr *addr); 00435 00436 /*! 00437 * \since 1.8 00438 * 00439 * \brief 00440 * Determine if the address is an IPv4 address 00441 * 00442 * \warning You should rarely need this function. Only use if you know what 00443 * you're doing. 00444 * \retval 1 This is an IPv4 address 00445 * \retval 0 This is an IPv6 or IPv4-mapped IPv6 address 00446 */ 00447 int ast_sockaddr_is_ipv4(const struct ast_sockaddr *addr); 00448 00449 /*! 00450 * \since 1.8 00451 * 00452 * \brief 00453 * Determine if this is an IPv4-mapped IPv6 address 00454 * 00455 * \warning You should rarely need this function. Only use if you know what 00456 * you're doing. 00457 * 00458 * \retval 1 This is an IPv4-mapped IPv6 address. 00459 * \retval 0 This is not an IPv4-mapped IPv6 address. 00460 */ 00461 int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr); 00462 00463 /*! 00464 * \since 1.8 00465 * 00466 * \brief 00467 * Determine if this is a link-local IPv6 address 00468 * 00469 * \warning You should rarely need this function. Only use if you know what 00470 * you're doing. 00471 * 00472 * \retval 1 This is a link-local IPv6 address. 00473 * \retval 0 This is link-local IPv6 address. 00474 */ 00475 int ast_sockaddr_is_ipv6_link_local(const struct ast_sockaddr *addr); 00476 00477 /*! 00478 * \since 1.8 00479 * 00480 * \brief 00481 * Determine if this is an IPv6 address 00482 * 00483 * \warning You should rarely need this function. Only use if you know what 00484 * you're doing. 00485 * 00486 * \retval 1 This is an IPv6 or IPv4-mapped IPv6 address. 00487 * \retval 0 This is an IPv4 address. 00488 */ 00489 int ast_sockaddr_is_ipv6(const struct ast_sockaddr *addr); 00490 00491 /*! 00492 * \since 1.8 00493 * 00494 * \brief 00495 * Determine if the address type is unspecified, or "any" address. 00496 * 00497 * \details 00498 * For IPv4, this would be the address 0.0.0.0, and for IPv6, 00499 * this would be the address ::. The port number is ignored. 00500 * 00501 * \retval 1 This is an "any" address 00502 * \retval 0 This is not an "any" address 00503 */ 00504 int ast_sockaddr_is_any(const struct ast_sockaddr *addr); 00505 00506 /*! 00507 * \since 1.8 00508 * 00509 * \brief 00510 * Computes a hash value from the address. The port is ignored. 00511 * 00512 * \retval 0 Unknown address family 00513 * \retval other A 32-bit hash derived from the address 00514 */ 00515 int ast_sockaddr_hash(const struct ast_sockaddr *addr); 00516 00517 /*! 00518 * \since 1.8 00519 * 00520 * \brief 00521 * Wrapper around accept(2) that uses struct ast_sockaddr. 00522 * 00523 * \details 00524 * For parameter and return information, see the man page for 00525 * accept(2). 00526 */ 00527 int ast_accept(int sockfd, struct ast_sockaddr *addr); 00528 00529 /*! 00530 * \since 1.8 00531 * 00532 * \brief 00533 * Wrapper around bind(2) that uses struct ast_sockaddr. 00534 * 00535 * \details 00536 * For parameter and return information, see the man page for 00537 * bind(2). 00538 */ 00539 int ast_bind(int sockfd, const struct ast_sockaddr *addr); 00540 00541 /*! 00542 * \since 1.8 00543 * 00544 * \brief 00545 * Wrapper around connect(2) that uses struct ast_sockaddr. 00546 * 00547 * \details 00548 * For parameter and return information, see the man page for 00549 * connect(2). 00550 */ 00551 int ast_connect(int sockfd, const struct ast_sockaddr *addr); 00552 00553 /*! 00554 * \since 1.8 00555 * 00556 * \brief 00557 * Wrapper around getsockname(2) that uses struct ast_sockaddr. 00558 * 00559 * \details 00560 * For parameter and return information, see the man page for 00561 * getsockname(2). 00562 */ 00563 int ast_getsockname(int sockfd, struct ast_sockaddr *addr); 00564 00565 /*! 00566 * \since 1.8 00567 * 00568 * \brief 00569 * Wrapper around recvfrom(2) that uses struct ast_sockaddr. 00570 * 00571 * \details 00572 * For parameter and return information, see the man page for 00573 * recvfrom(2). 00574 */ 00575 ssize_t ast_recvfrom(int sockfd, void *buf, size_t len, int flags, 00576 struct ast_sockaddr *src_addr); 00577 00578 /*! 00579 * \since 1.8 00580 * 00581 * \brief 00582 * Wrapper around sendto(2) that uses ast_sockaddr. 00583 * 00584 * \details 00585 * For parameter and 00586 * return information, see the man page for sendto(2) 00587 */ 00588 ssize_t ast_sendto(int sockfd, const void *buf, size_t len, int flags, 00589 const struct ast_sockaddr *dest_addr); 00590 00591 /*! 00592 * \since 1.8 00593 * 00594 * \brief 00595 * Set type of service 00596 * 00597 * \details 00598 * Set ToS ("Type of Service for IPv4 and "Traffic Class for IPv6) and 00599 * CoS (Linux's SO_PRIORITY) 00600 * 00601 * \param sockfd File descriptor for socket on which to set the parameters 00602 * \param tos The type of service for the socket 00603 * \param cos The cost of service for the socket 00604 * \param desc A text description of the socket in question. 00605 * \retval 0 Success 00606 * \retval -1 Error, with errno set to an appropriate value 00607 */ 00608 int ast_set_qos(int sockfd, int tos, int cos, const char *desc); 00609 00610 /*! 00611 * These are backward compatibility functions that may be used by subsystems 00612 * that have not yet been converted to IPv6. They will be removed when all 00613 * subsystems are IPv6-ready. 00614 */ 00615 /*@{*/ 00616 00617 /*! 00618 * \since 1.8 00619 * 00620 * \brief 00621 * Converts a struct ast_sockaddr to a struct sockaddr_in. 00622 * 00623 * \param addr The ast_sockaddr to convert 00624 * \param[out] sin The resulting sockaddr_in struct 00625 * \retval nonzero Success 00626 * \retval zero Failure 00627 */ 00628 #define ast_sockaddr_to_sin(addr,sin) _ast_sockaddr_to_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__) 00629 int _ast_sockaddr_to_sin(const struct ast_sockaddr *addr, 00630 struct sockaddr_in *sin, const char *file, int line, const char *func); 00631 00632 /*! 00633 * \since 1.8 00634 * 00635 * \brief 00636 * Converts a struct sockaddr_in to a struct ast_sockaddr. 00637 * 00638 * \param sin The sockaddr_in to convert 00639 * \return an ast_sockaddr structure 00640 */ 00641 #define ast_sockaddr_from_sin(addr,sin) _ast_sockaddr_from_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__) 00642 void _ast_sockaddr_from_sin(struct ast_sockaddr *addr, const struct sockaddr_in *sin, 00643 const char *file, int line, const char *func); 00644 00645 /*@}*/ 00646 00647 #if defined(__cplusplus) || defined(c_plusplus) 00648 } 00649 #endif 00650 00651 #endif /* _ASTERISK_NETSOCK2_H */