Mon Jun 27 16:50:54 2011

Asterisk developer's documentation


netsock2.h

Go to the documentation of this file.
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 */

Generated on Mon Jun 27 16:50:54 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7