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 * Socket address structure. The first member is big enough to contain addresses 00047 * of any family. The second member contains the length (in bytes) used in the 00048 * first member. 00049 * 00050 * Some BSDs have the length embedded in sockaddr structs. We ignore them. 00051 * (This is the right thing to do.) 00052 */ 00053 struct ast_sockaddr { 00054 struct sockaddr_storage ss; 00055 socklen_t len; 00056 }; 00057 00058 /*! 00059 * \brief 00060 * Convert an IPv4-mapped IPv6 address into an IPv4 address. 00061 * 00062 * \warning You should rarely need this function. Only call this 00063 * if you know what you're doing. 00064 * 00065 * \param addr The IPv4-mapped address to convert 00066 * \param mapped_addr The resulting IPv4 address 00067 * \retval 0 Unable to make the conversion 00068 * \retval 1 Successful conversion 00069 */ 00070 int ast_sockaddr_ipv4_mapped(const struct ast_sockaddr *addr, struct ast_sockaddr *ast_mapped); 00071 00072 /*! 00073 * \since 1.8 00074 * 00075 * \brief 00076 * Checks if the ast_sockaddr is null. "null" in this sense essentially 00077 * means uninitialized, or having a 0 length. 00078 * 00079 * \param addr Pointer to the ast_sockaddr we wish to check 00080 * \retval 1 \a addr is null 00081 * \retval 0 \a addr is non-null. 00082 */ 00083 static inline int ast_sockaddr_isnull(const struct ast_sockaddr *addr) 00084 { 00085 return !addr || addr->len == 0; 00086 } 00087 00088 /*! 00089 * \since 1.8 00090 * 00091 * \brief 00092 * Sets address \a addr to null. 00093 * 00094 * \retval void 00095 */ 00096 static inline void ast_sockaddr_setnull(struct ast_sockaddr *addr) 00097 { 00098 addr->len = 0; 00099 } 00100 00101 /*! 00102 * \since 1.8 00103 * 00104 * \brief 00105 * Copies the data from one ast_sockaddr to another 00106 * 00107 * \param dst The destination ast_sockaddr 00108 * \param src The source ast_sockaddr 00109 * \retval void 00110 */ 00111 static inline void ast_sockaddr_copy(struct ast_sockaddr *dst, 00112 const struct ast_sockaddr *src) 00113 { 00114 memcpy(dst, src, src->len); 00115 dst->len = src->len; 00116 }; 00117 00118 /*! 00119 * \since 1.8 00120 * 00121 * \brief 00122 * Compares two ast_sockaddr structures 00123 * 00124 * \retval -1 \a a is lexicographically smaller than \a b 00125 * \retval 0 \a a is equal to \a b 00126 * \retval 1 \a b is lexicographically smaller than \a a 00127 */ 00128 int ast_sockaddr_cmp(const struct ast_sockaddr *a, const struct ast_sockaddr *b); 00129 00130 /*! 00131 * \since 1.8 00132 * 00133 * \brief 00134 * Compares the addresses of two ast_sockaddr structures. 00135 * 00136 * \retval -1 \a a is lexicographically smaller than \a b 00137 * \retval 0 \a a is equal to \a b 00138 * \retval 1 \a b is lexicographically smaller than \a a 00139 */ 00140 int ast_sockaddr_cmp_addr(const struct ast_sockaddr *a, const struct ast_sockaddr *b); 00141 00142 #define AST_SOCKADDR_STR_ADDR (1 << 0) 00143 #define AST_SOCKADDR_STR_PORT (1 << 1) 00144 #define AST_SOCKADDR_STR_BRACKETS (1 << 2) 00145 #define AST_SOCKADDR_STR_HOST AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_BRACKETS 00146 #define AST_SOCKADDR_STR_DEFAULT AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT 00147 00148 /*! 00149 * \since 1.8 00150 * 00151 * \brief 00152 * Convert a socket address to a string. 00153 * 00154 * \details 00155 * This will be of the form a.b.c.d:xyz 00156 * for IPv4 and [a:b:c:...:d]:xyz for IPv6. 00157 * 00158 * This function is thread-safe. The returned string is on static 00159 * thread-specific storage. 00160 * 00161 * \param addr The input to be stringified 00162 * \param format one of the following: 00163 * AST_SOCKADDR_STR_DEFAULT: 00164 * a.b.c.d:xyz for IPv4 00165 * [a:b:c:...:d]:xyz for IPv6. 00166 * AST_SOCKADDR_STR_ADDR: address only 00167 * a.b.c.d for IPv4 00168 * a:b:c:...:d for IPv6. 00169 * AST_SOCKADDR_STR_HOST: address only, suitable for a URL 00170 * a.b.c.d for IPv4 00171 * [a:b:c:...:d] for IPv6. 00172 * AST_SOCKADDR_STR_PORT: port only 00173 * \retval "(null)" \a addr is null 00174 * \retval "" An error occurred during processing 00175 * \retval string The stringified form of the address 00176 */ 00177 char *ast_sockaddr_stringify_fmt(const struct ast_sockaddr *addr, int format); 00178 00179 /*! 00180 * \since 1.8 00181 * 00182 * \brief 00183 * Wrapper around ast_sockaddr_stringify_fmt() with default format 00184 * 00185 * \return same as ast_sockaddr_stringify_fmt() 00186 */ 00187 static inline char *ast_sockaddr_stringify(const struct ast_sockaddr *addr) 00188 { 00189 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT); 00190 } 00191 00192 /*! 00193 * \since 1.8 00194 * 00195 * \brief 00196 * Wrapper around ast_sockaddr_stringify_fmt() to return an address only 00197 * 00198 * \return same as ast_sockaddr_stringify_fmt() 00199 */ 00200 static inline char *ast_sockaddr_stringify_addr(const struct ast_sockaddr *addr) 00201 { 00202 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR); 00203 } 00204 00205 /*! 00206 * \since 1.8 00207 * 00208 * \brief 00209 * Wrapper around ast_sockaddr_stringify_fmt() to return an address only, 00210 * suitable for a URL (with brackets for IPv6). 00211 * 00212 * \return same as ast_sockaddr_stringify_fmt() 00213 */ 00214 static inline char *ast_sockaddr_stringify_host(const struct ast_sockaddr *addr) 00215 { 00216 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST); 00217 } 00218 00219 /*! 00220 * \since 1.8 00221 * 00222 * \brief 00223 * Wrapper around ast_sockaddr_stringify_fmt() to return a port only 00224 * 00225 * \return same as ast_sockaddr_stringify_fmt() 00226 */ 00227 static inline char *ast_sockaddr_stringify_port(const struct ast_sockaddr *addr) 00228 { 00229 return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_PORT); 00230 } 00231 00232 /*! 00233 * \since 1.8 00234 * 00235 * \brief 00236 * Splits a string into its host and port components 00237 * 00238 * \param str[in] The string to parse. May be modified by writing a NUL at the end of 00239 * the host part. 00240 * \param host[out] Pointer to the host component within \a str. 00241 * \param port[out] Pointer to the port component within \a str. 00242 * \param flags If set to zero, a port MAY be present. If set to PARSE_PORT_IGNORE, a 00243 * port MAY be present but will be ignored. If set to PARSE_PORT_REQUIRE, 00244 * a port MUST be present. If set to PARSE_PORT_FORBID, a port MUST NOT 00245 * be present. 00246 * 00247 * \retval 1 Success 00248 * \retval 0 Failure 00249 */ 00250 int ast_sockaddr_split_hostport(char *str, char **host, char **port, int flags); 00251 00252 /*! 00253 * \since 1.8 00254 * 00255 * \brief 00256 * Parse an IPv4 or IPv6 address string. 00257 * 00258 * \details 00259 * Parses a string containing an IPv4 or IPv6 address followed by an optional 00260 * port (separated by a colon) into a struct ast_sockaddr. The allowed formats 00261 * are the following: 00262 * 00263 * a.b.c.d 00264 * a.b.c.d:port 00265 * a:b:c:...:d 00266 * [a:b:c:...:d] 00267 * [a:b:c:...:d]:port 00268 * 00269 * Host names are NOT allowed. 00270 * 00271 * \param[out] addr The resulting ast_sockaddr 00272 * \param str The string to parse 00273 * \param flags If set to zero, a port MAY be present. If set to 00274 * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to 00275 * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a 00276 * port MUST NOT be present. 00277 * 00278 * \retval 1 Success 00279 * \retval 0 Failure 00280 */ 00281 int ast_sockaddr_parse(struct ast_sockaddr *addr, const char *str, int flags); 00282 00283 /*! 00284 * \since 1.8 00285 * 00286 * \brief 00287 * Parses a string with an IPv4 or IPv6 address and place results into an array 00288 * 00289 * \details 00290 * Parses a string containing a host name or an IPv4 or IPv6 address followed 00291 * by an optional port (separated by a colon). The result is returned into a 00292 * array of struct ast_sockaddr. Allowed formats for str are the following: 00293 * 00294 * hostname:port 00295 * host.example.com:port 00296 * a.b.c.d 00297 * a.b.c.d:port 00298 * a:b:c:...:d 00299 * [a:b:c:...:d] 00300 * [a:b:c:...:d]:port 00301 * 00302 * \param[out] addrs The resulting array of ast_sockaddrs 00303 * \param str The string to parse 00304 * \param flags If set to zero, a port MAY be present. If set to 00305 * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to 00306 * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a 00307 * port MUST NOT be present. 00308 * 00309 * \param family Only addresses of the given family will be returned. Use 0 or 00310 * AST_SOCKADDR_UNSPEC to get addresses of all families. 00311 * 00312 * \retval 0 Failure 00313 * \retval non-zero The number of elements in addrs array. 00314 */ 00315 int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str, 00316 int flags, int family); 00317 00318 /*! 00319 * \since 1.8 00320 * 00321 * \brief 00322 * Get the port number of a socket address. 00323 * 00324 * \warning Do not use this function unless you really know what you are doing. 00325 * And "I want the port number" is not knowing what you are doing. 00326 * 00327 * \retval 0 Address is null 00328 * \retval non-zero The port number of the ast_sockaddr 00329 */ 00330 #define ast_sockaddr_port(addr) _ast_sockaddr_port(addr, __FILE__, __LINE__, __PRETTY_FUNCTION__) 00331 uint16_t _ast_sockaddr_port(const struct ast_sockaddr *addr, const char *file, int line, const char *func); 00332 00333 /*! 00334 * \since 1.8 00335 * 00336 * \brief 00337 * Sets the port number of a socket address. 00338 * 00339 * \warning Do not use this function unless you really know what you are doing. 00340 * And "I want the port number" is not knowing what you are doing. 00341 * 00342 * \param addr Address on which to set the port 00343 * \param port The port you wish to set the address to use 00344 * \retval void 00345 */ 00346 #define ast_sockaddr_set_port(addr,port) _ast_sockaddr_set_port(addr,port,__FILE__,__LINE__,__PRETTY_FUNCTION__) 00347 void _ast_sockaddr_set_port(struct ast_sockaddr *addr, uint16_t port, const char *file, int line, const char *func); 00348 00349 /*! 00350 * \since 1.8 00351 * 00352 * \brief 00353 * Get an IPv4 address of an ast_sockaddr 00354 * 00355 * \warning You should rarely need this function. Only use if you know what 00356 * you're doing. 00357 * \return IPv4 address in network byte order 00358 */ 00359 uint32_t ast_sockaddr_ipv4(const struct ast_sockaddr *addr); 00360 00361 /*! 00362 * \since 1.8 00363 * 00364 * \brief 00365 * Determine if the address is an IPv4 address 00366 * 00367 * \warning You should rarely need this function. Only use if you know what 00368 * you're doing. 00369 * \retval 1 This is an IPv4 address 00370 * \retval 0 This is an IPv6 or IPv4-mapped IPv6 address 00371 */ 00372 int ast_sockaddr_is_ipv4(const struct ast_sockaddr *addr); 00373 00374 /*! 00375 * \since 1.8 00376 * 00377 * \brief 00378 * Determine if this is an IPv4-mapped IPv6 address 00379 * 00380 * \warning You should rarely need this function. Only use if you know what 00381 * you're doing. 00382 * 00383 * \retval 1 This is an IPv4-mapped IPv6 address. 00384 * \retval 0 This is not an IPv4-mapped IPv6 address. 00385 */ 00386 int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr); 00387 00388 /*! 00389 * \since 1.8 00390 * 00391 * \brief 00392 * Determine if this is an IPv6 address 00393 * 00394 * \warning You should rarely need this function. Only use if you know what 00395 * you're doing. 00396 * 00397 * \retval 1 This is an IPv6 or IPv4-mapped IPv6 address. 00398 * \retval 0 This is an IPv4 address. 00399 */ 00400 int ast_sockaddr_is_ipv6(const struct ast_sockaddr *addr); 00401 00402 /*! 00403 * \since 1.8 00404 * 00405 * \brief 00406 * Determine if the address type is unspecified, or "any" address. 00407 * 00408 * \details 00409 * For IPv4, this would be the address 0.0.0.0, and for IPv6, 00410 * this would be the address ::. The port number is ignored. 00411 * 00412 * \retval 1 This is an "any" address 00413 * \retval 0 This is not an "any" address 00414 */ 00415 int ast_sockaddr_is_any(const struct ast_sockaddr *addr); 00416 00417 /*! 00418 * \since 1.8 00419 * 00420 * \brief 00421 * Computes a hash value from the address. The port is ignored. 00422 * 00423 * \retval 0 Unknown address family 00424 * \retval other A 32-bit hash derived from the address 00425 */ 00426 int ast_sockaddr_hash(const struct ast_sockaddr *addr); 00427 00428 /*! 00429 * \since 1.8 00430 * 00431 * \brief 00432 * Wrapper around accept(2) that uses struct ast_sockaddr. 00433 * 00434 * \details 00435 * For parameter and return information, see the man page for 00436 * accept(2). 00437 */ 00438 int ast_accept(int sockfd, struct ast_sockaddr *addr); 00439 00440 /*! 00441 * \since 1.8 00442 * 00443 * \brief 00444 * Wrapper around bind(2) that uses struct ast_sockaddr. 00445 * 00446 * \details 00447 * For parameter and return information, see the man page for 00448 * bind(2). 00449 */ 00450 int ast_bind(int sockfd, const struct ast_sockaddr *addr); 00451 00452 /*! 00453 * \since 1.8 00454 * 00455 * \brief 00456 * Wrapper around connect(2) that uses struct ast_sockaddr. 00457 * 00458 * \details 00459 * For parameter and return information, see the man page for 00460 * connect(2). 00461 */ 00462 int ast_connect(int sockfd, const struct ast_sockaddr *addr); 00463 00464 /*! 00465 * \since 1.8 00466 * 00467 * \brief 00468 * Wrapper around getsockname(2) that uses struct ast_sockaddr. 00469 * 00470 * \details 00471 * For parameter and return information, see the man page for 00472 * getsockname(2). 00473 */ 00474 int ast_getsockname(int sockfd, struct ast_sockaddr *addr); 00475 00476 /*! 00477 * \since 1.8 00478 * 00479 * \brief 00480 * Wrapper around recvfrom(2) that uses struct ast_sockaddr. 00481 * 00482 * \details 00483 * For parameter and return information, see the man page for 00484 * recvfrom(2). 00485 */ 00486 ssize_t ast_recvfrom(int sockfd, void *buf, size_t len, int flags, 00487 struct ast_sockaddr *src_addr); 00488 00489 /*! 00490 * \since 1.8 00491 * 00492 * \brief 00493 * Wrapper around sendto(2) that uses ast_sockaddr. 00494 * 00495 * \details 00496 * For parameter and 00497 * return information, see the man page for sendto(2) 00498 */ 00499 ssize_t ast_sendto(int sockfd, const void *buf, size_t len, int flags, 00500 const struct ast_sockaddr *dest_addr); 00501 00502 /*! 00503 * \since 1.8 00504 * 00505 * \brief 00506 * Set type of service 00507 * 00508 * \details 00509 * Set ToS ("Type of Service for IPv4 and "Traffic Class for IPv6) and 00510 * CoS (Linux's SO_PRIORITY) 00511 * 00512 * \param sockfd File descriptor for socket on which to set the parameters 00513 * \param tos The type of service for the socket 00514 * \param cos The cost of service for the socket 00515 * \param desc A text description of the socket in question. 00516 * \retval 0 Success 00517 * \retval -1 Error, with errno set to an appropriate value 00518 */ 00519 int ast_set_qos(int sockfd, int tos, int cos, const char *desc); 00520 00521 /*! 00522 * These are backward compatibility functions that may be used by subsystems 00523 * that have not yet been converted to IPv6. They will be removed when all 00524 * subsystems are IPv6-ready. 00525 */ 00526 /*@{*/ 00527 00528 /*! 00529 * \since 1.8 00530 * 00531 * \brief 00532 * Converts a struct ast_sockaddr to a struct sockaddr_in. 00533 * 00534 * \param addr The ast_sockaddr to convert 00535 * \param[out] sin The resulting sockaddr_in struct 00536 * \retval nonzero Success 00537 * \retval zero Failure 00538 */ 00539 #define ast_sockaddr_to_sin(addr,sin) _ast_sockaddr_to_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__) 00540 int _ast_sockaddr_to_sin(const struct ast_sockaddr *addr, 00541 struct sockaddr_in *sin, const char *file, int line, const char *func); 00542 00543 /*! 00544 * \since 1.8 00545 * 00546 * \brief 00547 * Converts a struct sockaddr_in to a struct ast_sockaddr. 00548 * 00549 * \param sin The sockaddr_in to convert 00550 * \return an ast_sockaddr structure 00551 */ 00552 #define ast_sockaddr_from_sin(addr,sin) _ast_sockaddr_from_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__) 00553 void _ast_sockaddr_from_sin(struct ast_sockaddr *addr, const struct sockaddr_in *sin, 00554 const char *file, int line, const char *func); 00555 00556 /*@}*/ 00557 00558 #if defined(__cplusplus) || defined(c_plusplus) 00559 } 00560 #endif 00561 00562 #endif /* _ASTERISK_NETSOCK2_H */