include/asterisk/netsock2.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2010, Digium, Inc.
   5  *
   6  * Viagénie <asteriskv6@viagenie.ca>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief Network socket handling
  21  */
  22
  23 #ifndef _ASTERISK_NETSOCK2_H
  24 #define _ASTERISK_NETSOCK2_H
  25
  26 #if defined(__cplusplus) || defined(c_plusplus)
  27 extern "C" {
  28 #endif
  29
  30 #include <sys/socket.h>
  31
  32 #include <netinet/in.h>
  33
  34 /*!
  35  * Values for address families that we support. This is reproduced from socket.h
  36  * because we do not want users to include that file. Only netsock2.c should
  37  * ever include socket.h.
  38  */
  39 enum {
  40         AST_AF_UNSPEC   = 0,
  41         AST_AF_INET     = 2,
  42         AST_AF_INET6    = 10,
  43 };
  44
  45 /*!
  46  * Socket address structure. The first member is big enough to contain addresses
  47  * of any family. The second member contains the length (in bytes) used in the
  48  * first member.
  49  *
  50  * Some BSDs have the length embedded in sockaddr structs. We ignore them.
  51  * (This is the right thing to do.)
  52  */
  53 struct ast_sockaddr {
  54         struct sockaddr_storage  ss;
  55         socklen_t len;
  56 };
  57
  58 /*!
  59  * \brief
  60  * Convert an IPv4-mapped IPv6 address into an IPv4 address.
  61  *
  62  * \warning You should rarely need this function. Only call this
  63  * if you know what you're doing.
  64  *
  65  * \param addr The IPv4-mapped address to convert
  66  * \param mapped_addr The resulting IPv4 address
  67  * \retval 0 Unable to make the conversion
  68  * \retval 1 Successful conversion
  69  */
  70 int ast_sockaddr_ipv4_mapped(const struct ast_sockaddr *addr, struct ast_sockaddr *ast_mapped);
  71
  72 /*!
  73  * \since 1.8
  74  *
  75  * \brief
  76  * Checks if the ast_sockaddr is null. "null" in this sense essentially
  77  * means uninitialized, or having a 0 length.
  78  *
  79  * \param addr Pointer to the ast_sockaddr we wish to check
  80  * \retval 1 \a addr is null
  81  * \retval 0 \a addr is non-null.
  82  */
  83 static inline int ast_sockaddr_isnull(const struct ast_sockaddr *addr)
  84 {
  85         return !addr || addr->len == 0;
  86 }
  87
  88 /*!
  89  * \since 1.8
  90  *
  91  * \brief
  92  * Sets address \a addr to null.
  93  *
  94  * \retval void
  95  */
  96 static inline void ast_sockaddr_setnull(struct ast_sockaddr *addr)
  97 {
  98         addr->len = 0;
  99 }
 100
 101 /*!
 102  * \since 1.8
 103  *
 104  * \brief
 105  * Copies the data from one ast_sockaddr to another
 106  *
 107  * \param dst The destination ast_sockaddr
 108  * \param src The source ast_sockaddr
 109  * \retval void
 110  */
 111 static inline void ast_sockaddr_copy(struct ast_sockaddr *dst,
 112                 const struct ast_sockaddr *src)
 113 {
 114         memcpy(dst, src, src->len);
 115         dst->len = src->len;
 116 };
 117
 118 /*!
 119  * \since 1.8
 120  *
 121  * \brief
 122  * Compares two ast_sockaddr structures
 123  *
 124  * \retval -1 \a a is lexicographically smaller than \a b
 125  * \retval 0 \a a is equal to \a b
 126  * \retval 1 \a b is lexicographically smaller than \a a
 127  */
 128 int ast_sockaddr_cmp(const struct ast_sockaddr *a, const struct ast_sockaddr *b);
 129
 130 /*!
 131  * \since 1.8
 132  *
 133  * \brief
 134  * Compares the addresses of two ast_sockaddr structures.
 135  *
 136  * \retval -1 \a a is lexicographically smaller than \a b
 137  * \retval 0 \a a is equal to \a b
 138  * \retval 1 \a b is lexicographically smaller than \a a
 139  */
 140 int ast_sockaddr_cmp_addr(const struct ast_sockaddr *a, const struct ast_sockaddr *b);
 141
 142 #define AST_SOCKADDR_STR_ADDR           (1 << 0)
 143 #define AST_SOCKADDR_STR_PORT           (1 << 1)
 144 #define AST_SOCKADDR_STR_BRACKETS       (1 << 2)
 145 #define AST_SOCKADDR_STR_HOST           AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_BRACKETS
 146 #define AST_SOCKADDR_STR_DEFAULT        AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT
 147
 148 /*!
 149  * \since 1.8
 150  *
 151  * \brief
 152  * Convert a socket address to a string.
 153  *
 154  * \details
 155  * This will be of the form a.b.c.d:xyz
 156  * for IPv4 and [a:b:c:...:d]:xyz for IPv6.
 157  *
 158  * This function is thread-safe. The returned string is on static
 159  * thread-specific storage.
 160  *
 161  * \param addr The input to be stringified
 162  * \param format one of the following:
 163  * AST_SOCKADDR_STR_DEFAULT:
 164  *    a.b.c.d:xyz for IPv4
 165  *    [a:b:c:...:d]:xyz for IPv6.
 166  * AST_SOCKADDR_STR_ADDR: address only
 167  *    a.b.c.d for IPv4
 168  *    a:b:c:...:d for IPv6.
 169  * AST_SOCKADDR_STR_HOST: address only, suitable for a URL
 170  *    a.b.c.d for IPv4
 171  *    [a:b:c:...:d] for IPv6.
 172  * AST_SOCKADDR_STR_PORT: port only
 173  * \retval "(null)" \a addr is null
 174  * \retval "" An error occurred during processing
 175  * \retval string The stringified form of the address
 176  */
 177 char *ast_sockaddr_stringify_fmt(const struct ast_sockaddr *addr, int format);
 178
 179 /*!
 180  * \since 1.8
 181  *
 182  * \brief
 183  * Wrapper around ast_sockaddr_stringify_fmt() with default format
 184  *
 185  * \return same as ast_sockaddr_stringify_fmt()
 186  */
 187 static inline char *ast_sockaddr_stringify(const struct ast_sockaddr *addr)
 188 {
 189         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT);
 190 }
 191
 192 /*!
 193  * \since 1.8
 194  *
 195  * \brief
 196  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only
 197  *
 198  * \return same as ast_sockaddr_stringify_fmt()
 199  */
 200 static inline char *ast_sockaddr_stringify_addr(const struct ast_sockaddr *addr)
 201 {
 202         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR);
 203 }
 204
 205 /*!
 206  * \since 1.8
 207  *
 208  * \brief
 209  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only,
 210  * suitable for a URL (with brackets for IPv6).
 211  *
 212  * \return same as ast_sockaddr_stringify_fmt()
 213  */
 214 static inline char *ast_sockaddr_stringify_host(const struct ast_sockaddr *addr)
 215 {
 216         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST);
 217 }
 218
 219 /*!
 220  * \since 1.8
 221  *
 222  * \brief
 223  * Wrapper around ast_sockaddr_stringify_fmt() to return a port only
 224  *
 225  * \return same as ast_sockaddr_stringify_fmt()
 226  */
 227 static inline char *ast_sockaddr_stringify_port(const struct ast_sockaddr *addr)
 228 {
 229         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_PORT);
 230 }
 231
 232 /*!
 233  * \since 1.8
 234  *
 235  * \brief
 236  * Parse an IPv4 or IPv6 address string.
 237  *
 238  * \details
 239  * Parses a string containing an IPv4 or IPv6 address followed by an optional
 240  * port (separated by a colon) into a struct ast_sockaddr. The allowed formats
 241  * are the following:
 242  *
 243  * a.b.c.d
 244  * a.b.c.d:port
 245  * a:b:c:...:d
 246  * [a:b:c:...:d]
 247  * [a:b:c:...:d]:port
 248  *
 249  * Host names are NOT allowed.
 250  *
 251  * \param[out] addr The resulting ast_sockaddr
 252  * \param str The string to parse
 253  * \param flags If set to zero, a port MAY be present. If set to
 254  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
 255  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
 256  * port MUST NOT be present.
 257  *
 258  * \retval 1 Success
 259  * \retval 0 Failure
 260  */
 261 int ast_sockaddr_parse(struct ast_sockaddr *addr, const char *str, int flags);
 262
 263 /*!
 264  * \since 1.8
 265  *
 266  * \brief
 267  * Parses a string with an IPv4 or IPv6 address and place results into an array
 268  *
 269  * \details
 270  * Parses a string containing a host name or an IPv4 or IPv6 address followed
 271  * by an optional port (separated by a colon).  The result is returned into a
 272  * array of struct ast_sockaddr. Allowed formats for str are the following:
 273  *
 274  * hostname:port
 275  * host.example.com:port
 276  * a.b.c.d
 277  * a.b.c.d:port
 278  * a:b:c:...:d
 279  * [a:b:c:...:d]
 280  * [a:b:c:...:d]:port
 281  *
 282  * \param[out] addrs The resulting array of ast_sockaddrs
 283  * \param str The string to parse
 284  * \param flags If set to zero, a port MAY be present. If set to
 285  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
 286  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
 287  * port MUST NOT be present.
 288  *
 289  * \param family Only addresses of the given family will be returned. Use 0 or
 290  * AST_SOCKADDR_UNSPEC to get addresses of all families.
 291  *
 292  * \retval 0 Failure
 293  * \retval non-zero The number of elements in addrs array.
 294  */
 295 int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str,
 296                          int flags, int family);
 297
 298 /*!
 299  * \since 1.8
 300  *
 301  * \brief
 302  * Get the port number of a socket address.
 303  *
 304  * \warning Do not use this function unless you really know what you are doing.
 305  * And "I want the port number" is not knowing what you are doing.
 306  *
 307  * \retval 0 Address is null
 308  * \retval non-zero The port number of the ast_sockaddr
 309  */
 310 #define ast_sockaddr_port(addr) _ast_sockaddr_port(addr, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 311 uint16_t _ast_sockaddr_port(const struct ast_sockaddr *addr, const char *file, int line, const char *func);
 312
 313 /*!
 314  * \since 1.8
 315  *
 316  * \brief
 317  * Sets the port number of a socket address.
 318  *
 319  * \warning Do not use this function unless you really know what you are doing.
 320  * And "I want the port number" is not knowing what you are doing.
 321  *
 322  * \param addr Address on which to set the port
 323  * \param port The port you wish to set the address to use
 324  * \retval void
 325  */
 326 #define ast_sockaddr_set_port(addr,port)        _ast_sockaddr_set_port(addr,port,__FILE__,__LINE__,__PRETTY_FUNCTION__)
 327 void _ast_sockaddr_set_port(struct ast_sockaddr *addr, uint16_t port, const char *file, int line, const char *func);
 328
 329 /*!
 330  * \since 1.8
 331  *
 332  * \brief
 333  * Get an IPv4 address of an ast_sockaddr
 334  *
 335  * \warning You should rarely need this function. Only use if you know what
 336  * you're doing.
 337  * \return IPv4 address in network byte order
 338  */
 339 uint32_t ast_sockaddr_ipv4(const struct ast_sockaddr *addr);
 340
 341 /*!
 342  * \since 1.8
 343  *
 344  * \brief
 345  * Determine if the address is an IPv4 address
 346  *
 347  * \warning You should rarely need this function. Only use if you know what
 348  * you're doing.
 349  * \retval 1 This is an IPv4 address
 350  * \retval 0 This is an IPv6 or IPv4-mapped IPv6 address
 351  */
 352 int ast_sockaddr_is_ipv4(const struct ast_sockaddr *addr);
 353
 354 /*!
 355  * \since 1.8
 356  *
 357  * \brief
 358  * Determine if this is an IPv4-mapped IPv6 address
 359  *
 360  * \warning You should rarely need this function. Only use if you know what
 361  * you're doing.
 362  *
 363  * \retval 1 This is an IPv4-mapped IPv6 address.
 364  * \retval 0 This is not an IPv4-mapped IPv6 address.
 365  */
 366 int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr);
 367
 368 /*!
 369  * \since 1.8
 370  *
 371  * \brief
 372  * Determine if this is an IPv6 address
 373  *
 374  * \warning You should rarely need this function. Only use if you know what
 375  * you're doing.
 376  *
 377  * \retval 1 This is an IPv6 or IPv4-mapped IPv6 address.
 378  * \retval 0 This is an IPv4 address.
 379  */
 380 int ast_sockaddr_is_ipv6(const struct ast_sockaddr *addr);
 381
 382 /*!
 383  * \since 1.8
 384  *
 385  * \brief
 386  * Determine if the address type is unspecified, or "any" address.
 387  *
 388  * \details
 389  * For IPv4, this would be the address 0.0.0.0, and for IPv6,
 390  * this would be the address ::. The port number is ignored.
 391  *
 392  * \retval 1 This is an "any" address
 393  * \retval 0 This is not an "any" address
 394  */
 395 int ast_sockaddr_is_any(const struct ast_sockaddr *addr);
 396
 397 /*!
 398  * \since 1.8
 399  *
 400  * \brief
 401  * Computes a hash value from the address. The port is ignored.
 402  *
 403  * \retval 0 Unknown address family
 404  * \retval other A 32-bit hash derived from the address
 405  */
 406 int ast_sockaddr_hash(const struct ast_sockaddr *addr);
 407
 408 /*!
 409  * \since 1.8
 410  *
 411  * \brief
 412  * Wrapper around accept(2) that uses struct ast_sockaddr.
 413  *
 414  * \details
 415  * For parameter and return information, see the man page for
 416  * accept(2).
 417  */
 418 int ast_accept(int sockfd, struct ast_sockaddr *addr);
 419
 420 /*!
 421  * \since 1.8
 422  *
 423  * \brief
 424  * Wrapper around bind(2) that uses struct ast_sockaddr.
 425  *
 426  * \details
 427  * For parameter and return information, see the man page for
 428  * bind(2).
 429  */
 430 int ast_bind(int sockfd, const struct ast_sockaddr *addr);
 431
 432 /*!
 433  * \since 1.8
 434  *
 435  * \brief
 436  * Wrapper around connect(2) that uses struct ast_sockaddr.
 437  *
 438  * \details
 439  * For parameter and return information, see the man page for
 440  * connect(2).
 441  */
 442 int ast_connect(int sockfd, const struct ast_sockaddr *addr);
 443
 444 /*!
 445  * \since 1.8
 446  *
 447  * \brief
 448  * Wrapper around getsockname(2) that uses struct ast_sockaddr.
 449  *
 450  * \details
 451  * For parameter and return information, see the man page for
 452  * getsockname(2).
 453  */
 454 int ast_getsockname(int sockfd, struct ast_sockaddr *addr);
 455
 456 /*!
 457  * \since 1.8
 458  *
 459  * \brief
 460  * Wrapper around recvfrom(2) that uses struct ast_sockaddr.
 461  *
 462  * \details
 463  * For parameter and return information, see the man page for
 464  * recvfrom(2).
 465  */
 466 ssize_t ast_recvfrom(int sockfd, void *buf, size_t len, int flags,
 467                      struct ast_sockaddr *src_addr);
 468
 469 /*!
 470  * \since 1.8
 471  *
 472  * \brief
 473  * Wrapper around sendto(2) that uses ast_sockaddr.
 474  *
 475  * \details
 476  * For parameter and
 477  * return information, see the man page for sendto(2)
 478  */
 479 ssize_t ast_sendto(int sockfd, const void *buf, size_t len, int flags,
 480                    const struct ast_sockaddr *dest_addr);
 481
 482 /*!
 483  * \since 1.8
 484  *
 485  * \brief
 486  * Set type of service
 487  *
 488  * \details
 489  * Set ToS ("Type of Service for IPv4 and "Traffic Class for IPv6) and
 490  * CoS (Linux's SO_PRIORITY)
 491  *
 492  * \param sockfd File descriptor for socket on which to set the parameters
 493  * \param tos The type of service for the socket
 494  * \param cos The cost of service for the socket
 495  * \param desc A text description of the socket in question.
 496  * \retval 0 Success
 497  * \retval -1 Error, with errno set to an appropriate value
 498  */
 499 int ast_set_qos(int sockfd, int tos, int cos, const char *desc);
 500
 501 /*!
 502  * These are backward compatibility functions that may be used by subsystems
 503  * that have not yet been converted to IPv6. They will be removed when all
 504  * subsystems are IPv6-ready.
 505  */
 506 /*@{*/
 507
 508 /*!
 509  * \since 1.8
 510  *
 511  * \brief
 512  * Converts a struct ast_sockaddr to a struct sockaddr_in.
 513  *
 514  * \param addr The ast_sockaddr to convert
 515  * \param[out] sin The resulting sockaddr_in struct
 516  * \retval nonzero Success
 517  * \retval zero Failure
 518  */
 519 #define ast_sockaddr_to_sin(addr,sin)   _ast_sockaddr_to_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 520 int _ast_sockaddr_to_sin(const struct ast_sockaddr *addr,
 521                         struct sockaddr_in *sin, const char *file, int line, const char *func);
 522
 523 /*!
 524  * \since 1.8
 525  *
 526  * \brief
 527  * Converts a struct sockaddr_in to a struct ast_sockaddr.
 528  *
 529  * \param sin The sockaddr_in to convert
 530  * \return an ast_sockaddr structure
 531  */
 532 #define ast_sockaddr_from_sin(addr,sin) _ast_sockaddr_from_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 533 void _ast_sockaddr_from_sin(struct ast_sockaddr *addr, const struct sockaddr_in *sin,
 534                 const char *file, int line, const char *func);
 535
 536 /*@}*/
 537
 538 #if defined(__cplusplus) || defined(c_plusplus)
 539 }
 540 #endif
 541
 542 #endif /* _ASTERISK_NETSOCK2_H */