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. This MAY be NULL from 00347 * functions that are performing validity checks only, e.g. ast_parse_arg(). 00348 * \param str The string to parse 00349 * \param flags If set to zero, a port MAY be present. If set to 00350 * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to 00351 * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a 00352 * port MUST NOT be present. 00353 * 00354 * \retval 1 Success 00355 * \retval 0 Failure 00356 */ 00357 int ast_sockaddr_parse(struct ast_sockaddr *addr, const char *str, int flags); 00358 00359 /*! 00360 * \since 1.8 00361 * 00362 * \brief 00363 * Parses a string with an IPv4 or IPv6 address and place results into an array 00364 * 00365 * \details 00366 * Parses a string containing a host name or an IPv4 or IPv6 address followed 00367 * by an optional port (separated by a colon). The result is returned into a 00368 * array of struct ast_sockaddr. Allowed formats for str are the following: 00369 * 00370 * hostname:port 00371 * host.example.com:port 00372 * a.b.c.d 00373 * a.b.c.d:port 00374 * a:b:c:...:d 00375 * [a:b:c:...:d] 00376 * [a:b:c:...:d]:port 00377 * 00378 * \param[out] addrs The resulting array of ast_sockaddrs 00379 * \param str The string to parse 00380 * \param flags If set to zero, a port MAY be present. If set to 00381 * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to 00382 * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a 00383 * port MUST NOT be present. 00384 * 00385 * \param family Only addresses of the given family will be returned. Use 0 or 00386 * AST_SOCKADDR_UNSPEC to get addresses of all families. 00387 * 00388 * \retval 0 Failure 00389 * \retval non-zero The number of elements in addrs array. 00390 */ 00391 int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str, 00392 int flags, int family); 00393 00394 /*! 00395 * \since 1.8 00396 * 00397 * \brief 00398 * Get the port number of a socket address. 00399 * 00400 * \warning Do not use this function unless you really know what you are doing. 00401 * And "I want the port number" is not knowing what you are doing. 00402 * 00403 * \retval 0 Address is null 00404 * \retval non-zero The port number of the ast_sockaddr 00405 */ 00406 #define ast_sockaddr_port(addr) _ast_sockaddr_port(addr, __FILE__, __LINE__, __PRETTY_FUNCTION__) 00407 uint16_t _ast_sockaddr_port(const struct ast_sockaddr *addr, const char *file, int line, const char *func); 00408 00409 /*! 00410 * \since 1.8 00411 * 00412 * \brief 00413 * Sets the port number of a socket address. 00414 * 00415 * \warning Do not use this function unless you really know what you are doing. 00416 * And "I want the port number" is not knowing what you are doing. 00417 * 00418 * \param addr Address on which to set the port 00419 * \param port The port you wish to set the address to use 00420 * \retval void 00421 */ 00422 #define ast_sockaddr_set_port(addr,port) _ast_sockaddr_set_port(addr,port,__FILE__,__LINE__,__PRETTY_FUNCTION__) 00423 void _ast_sockaddr_set_port(struct ast_sockaddr *addr, uint16_t port, const char *file, int line, const char *func); 00424 00425 /*! 00426 * \since 1.8 00427 * 00428 * \brief 00429 * Get an IPv4 address of an ast_sockaddr 00430 * 00431 * \warning You should rarely need this function. Only use if you know what 00432 * you're doing. 00433 * \return IPv4 address in network byte order 00434 */ 00435 uint32_t ast_sockaddr_ipv4(const struct ast_sockaddr *addr); 00436 00437 /*! 00438 * \since 1.8 00439 * 00440 * \brief 00441 * Determine if the address is an IPv4 address 00442 * 00443 * \warning You should rarely need this function. Only use if you know what 00444 * you're doing. 00445 * \retval 1 This is an IPv4 address 00446 * \retval 0 This is an IPv6 or IPv4-mapped IPv6 address 00447 */ 00448 int ast_sockaddr_is_ipv4(const struct ast_sockaddr *addr); 00449 00450 /*! 00451 * \since 1.8 00452 * 00453 * \brief 00454 * Determine if this is an IPv4-mapped IPv6 address 00455 * 00456 * \warning You should rarely need this function. Only use if you know what 00457 * you're doing. 00458 * 00459 * \retval 1 This is an IPv4-mapped IPv6 address. 00460 * \retval 0 This is not an IPv4-mapped IPv6 address. 00461 */ 00462 int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr); 00463 00464 /*! 00465 * \since 1.8 00466 * 00467 * \brief 00468 * Determine if this is a link-local IPv6 address 00469 * 00470 * \warning You should rarely need this function. Only use if you know what 00471 * you're doing. 00472 * 00473 * \retval 1 This is a link-local IPv6 address. 00474 * \retval 0 This is link-local IPv6 address. 00475 */ 00476 int ast_sockaddr_is_ipv6_link_local(const struct ast_sockaddr *addr); 00477 00478 /*! 00479 * \since 1.8 00480 * 00481 * \brief 00482 * Determine if this is an IPv6 address 00483 * 00484 * \warning You should rarely need this function. Only use if you know what 00485 * you're doing. 00486 * 00487 * \retval 1 This is an IPv6 or IPv4-mapped IPv6 address. 00488 * \retval 0 This is an IPv4 address. 00489 */ 00490 int ast_sockaddr_is_ipv6(const struct ast_sockaddr *addr); 00491 00492 /*! 00493 * \since 1.8 00494 * 00495 * \brief 00496 * Determine if the address type is unspecified, or "any" address. 00497 * 00498 * \details 00499 * For IPv4, this would be the address 0.0.0.0, and for IPv6, 00500 * this would be the address ::. The port number is ignored. 00501 * 00502 * \retval 1 This is an "any" address 00503 * \retval 0 This is not an "any" address 00504 */ 00505 int ast_sockaddr_is_any(const struct ast_sockaddr *addr); 00506 00507 /*! 00508 * \since 1.8 00509 * 00510 * \brief 00511 * Computes a hash value from the address. The port is ignored. 00512 * 00513 * \retval 0 Unknown address family 00514 * \retval other A 32-bit hash derived from the address 00515 */ 00516 int ast_sockaddr_hash(const struct ast_sockaddr *addr); 00517 00518 /*! 00519 * \since 1.8 00520 * 00521 * \brief 00522 * Wrapper around accept(2) that uses struct ast_sockaddr. 00523 * 00524 * \details 00525 * For parameter and return information, see the man page for 00526 * accept(2). 00527 */ 00528 int ast_accept(int sockfd, struct ast_sockaddr *addr); 00529 00530 /*! 00531 * \since 1.8 00532 * 00533 * \brief 00534 * Wrapper around bind(2) that uses struct ast_sockaddr. 00535 * 00536 * \details 00537 * For parameter and return information, see the man page for 00538 * bind(2). 00539 */ 00540 int ast_bind(int sockfd, const struct ast_sockaddr *addr); 00541 00542 /*! 00543 * \since 1.8 00544 * 00545 * \brief 00546 * Wrapper around connect(2) that uses struct ast_sockaddr. 00547 * 00548 * \details 00549 * For parameter and return information, see the man page for 00550 * connect(2). 00551 */ 00552 int ast_connect(int sockfd, const struct ast_sockaddr *addr); 00553 00554 /*! 00555 * \since 1.8 00556 * 00557 * \brief 00558 * Wrapper around getsockname(2) that uses struct ast_sockaddr. 00559 * 00560 * \details 00561 * For parameter and return information, see the man page for 00562 * getsockname(2). 00563 */ 00564 int ast_getsockname(int sockfd, struct ast_sockaddr *addr); 00565 00566 /*! 00567 * \since 1.8 00568 * 00569 * \brief 00570 * Wrapper around recvfrom(2) that uses struct ast_sockaddr. 00571 * 00572 * \details 00573 * For parameter and return information, see the man page for 00574 * recvfrom(2). 00575 */ 00576 ssize_t ast_recvfrom(int sockfd, void *buf, size_t len, int flags, 00577 struct ast_sockaddr *src_addr); 00578 00579 /*! 00580 * \since 1.8 00581 * 00582 * \brief 00583 * Wrapper around sendto(2) that uses ast_sockaddr. 00584 * 00585 * \details 00586 * For parameter and 00587 * return information, see the man page for sendto(2) 00588 */ 00589 ssize_t ast_sendto(int sockfd, const void *buf, size_t len, int flags, 00590 const struct ast_sockaddr *dest_addr); 00591 00592 /*! 00593 * \since 1.8 00594 * 00595 * \brief 00596 * Set type of service 00597 * 00598 * \details 00599 * Set ToS ("Type of Service for IPv4 and "Traffic Class for IPv6) and 00600 * CoS (Linux's SO_PRIORITY) 00601 * 00602 * \param sockfd File descriptor for socket on which to set the parameters 00603 * \param tos The type of service for the socket 00604 * \param cos The cost of service for the socket 00605 * \param desc A text description of the socket in question. 00606 * \retval 0 Success 00607 * \retval -1 Error, with errno set to an appropriate value 00608 */ 00609 int ast_set_qos(int sockfd, int tos, int cos, const char *desc); 00610 00611 /*! 00612 * These are backward compatibility functions that may be used by subsystems 00613 * that have not yet been converted to IPv6. They will be removed when all 00614 * subsystems are IPv6-ready. 00615 */ 00616 /*@{*/ 00617 00618 /*! 00619 * \since 1.8 00620 * 00621 * \brief 00622 * Converts a struct ast_sockaddr to a struct sockaddr_in. 00623 * 00624 * \param addr The ast_sockaddr to convert 00625 * \param[out] sin The resulting sockaddr_in struct 00626 * \retval nonzero Success 00627 * \retval zero Failure 00628 */ 00629 #define ast_sockaddr_to_sin(addr,sin) _ast_sockaddr_to_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__) 00630 int _ast_sockaddr_to_sin(const struct ast_sockaddr *addr, 00631 struct sockaddr_in *sin, const char *file, int line, const char *func); 00632 00633 /*! 00634 * \since 1.8 00635 * 00636 * \brief 00637 * Converts a struct sockaddr_in to a struct ast_sockaddr. 00638 * 00639 * \param sin The sockaddr_in to convert 00640 * \return an ast_sockaddr structure 00641 */ 00642 #define ast_sockaddr_from_sin(addr,sin) _ast_sockaddr_from_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__) 00643 void _ast_sockaddr_from_sin(struct ast_sockaddr *addr, const struct sockaddr_in *sin, 00644 const char *file, int line, const char *func); 00645 00646 /*@}*/ 00647 00648 #if defined(__cplusplus) || defined(c_plusplus) 00649 } 00650 #endif 00651 00652 #endif /* _ASTERISK_NETSOCK2_H */