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  * \brief Socket address structure.
  47  *
  48  * \details
  49  * The first member is big enough to contain addresses of any
  50  * family. The second member contains the length (in bytes) used
  51  * in the first member.
  52  *
  53  * \note
  54  * Some BSDs have the length embedded in sockaddr structs. We
  55  * ignore them. (This is the right thing to do.)
  56  *
  57  * \note
  58  * It is important to always initialize ast_sockaddr before use
  59  * -- even if they are passed to ast_sockaddr_copy() as the
  60  * underlying storage could be bigger than what ends up being
  61  * copied -- leaving part of the data unitialized.
  62  */
  63 struct ast_sockaddr {
  64         struct sockaddr_storage  ss;
  65         socklen_t len;
  66 };
  67
  68 /*!
  69  * \brief
  70  * Convert an IPv4-mapped IPv6 address into an IPv4 address.
  71  *
  72  * \warning You should rarely need this function. Only call this
  73  * if you know what you're doing.
  74  *
  75  * \param addr The IPv4-mapped address to convert
  76  * \param mapped_addr The resulting IPv4 address
  77  * \retval 0 Unable to make the conversion
  78  * \retval 1 Successful conversion
  79  */
  80 int ast_sockaddr_ipv4_mapped(const struct ast_sockaddr *addr, struct ast_sockaddr *ast_mapped);
  81
  82 /*!
  83  * \since 1.8
  84  *
  85  * \brief
  86  * Checks if the ast_sockaddr is null. "null" in this sense essentially
  87  * means uninitialized, or having a 0 length.
  88  *
  89  * \param addr Pointer to the ast_sockaddr we wish to check
  90  * \retval 1 \a addr is null
  91  * \retval 0 \a addr is non-null.
  92  */
  93 static inline int ast_sockaddr_isnull(const struct ast_sockaddr *addr)
  94 {
  95         return !addr || addr->len == 0;
  96 }
  97
  98 /*!
  99  * \since 1.8
 100  *
 101  * \brief
 102  * Sets address \a addr to null.
 103  *
 104  * \retval void
 105  */
 106 static inline void ast_sockaddr_setnull(struct ast_sockaddr *addr)
 107 {
 108         addr->len = 0;
 109 }
 110
 111 /*!
 112  * \since 1.8
 113  *
 114  * \brief
 115  * Copies the data from one ast_sockaddr to another
 116  *
 117  * \param dst The destination ast_sockaddr
 118  * \param src The source ast_sockaddr
 119  * \retval void
 120  */
 121 static inline void ast_sockaddr_copy(struct ast_sockaddr *dst,
 122                 const struct ast_sockaddr *src)
 123 {
 124         memcpy(dst, src, src->len);
 125         dst->len = src->len;
 126 };
 127
 128 /*!
 129  * \since 1.8
 130  *
 131  * \brief
 132  * Compares two ast_sockaddr structures
 133  *
 134  * \retval -1 \a a is lexicographically smaller than \a b
 135  * \retval 0 \a a is equal to \a b
 136  * \retval 1 \a b is lexicographically smaller than \a a
 137  */
 138 int ast_sockaddr_cmp(const struct ast_sockaddr *a, const struct ast_sockaddr *b);
 139
 140 /*!
 141  * \since 1.8
 142  *
 143  * \brief
 144  * Compares the addresses of two ast_sockaddr structures.
 145  *
 146  * \retval -1 \a a is lexicographically smaller than \a b
 147  * \retval 0 \a a is equal to \a b
 148  * \retval 1 \a b is lexicographically smaller than \a a
 149  */
 150 int ast_sockaddr_cmp_addr(const struct ast_sockaddr *a, const struct ast_sockaddr *b);
 151
 152 #define AST_SOCKADDR_STR_ADDR           (1 << 0)
 153 #define AST_SOCKADDR_STR_PORT           (1 << 1)
 154 #define AST_SOCKADDR_STR_BRACKETS       (1 << 2)
 155 #define AST_SOCKADDR_STR_REMOTE         (1 << 3)
 156 #define AST_SOCKADDR_STR_HOST           (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_BRACKETS)
 157 #define AST_SOCKADDR_STR_DEFAULT        (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT)
 158 #define AST_SOCKADDR_STR_ADDR_REMOTE     (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_REMOTE)
 159 #define AST_SOCKADDR_STR_HOST_REMOTE     (AST_SOCKADDR_STR_HOST | AST_SOCKADDR_STR_REMOTE)
 160 #define AST_SOCKADDR_STR_DEFAULT_REMOTE  (AST_SOCKADDR_STR_DEFAULT | AST_SOCKADDR_STR_REMOTE)
 161 #define AST_SOCKADDR_STR_FORMAT_MASK     (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT | AST_SOCKADDR_STR_BRACKETS)
 162
 163 /*!
 164  * \since 1.8
 165  *
 166  * \brief
 167  * Convert a socket address to a string.
 168  *
 169  * \details
 170  * This will be of the form a.b.c.d:xyz
 171  * for IPv4 and [a:b:c:...:d]:xyz for IPv6.
 172  *
 173  * This function is thread-safe. The returned string is on static
 174  * thread-specific storage.
 175  *
 176  * \param addr The input to be stringified
 177  * \param format one of the following:
 178  * AST_SOCKADDR_STR_DEFAULT:
 179  *    a.b.c.d:xyz for IPv4
 180  *    [a:b:c:...:d]:xyz for IPv6.
 181  * AST_SOCKADDR_STR_ADDR: address only
 182  *    a.b.c.d for IPv4
 183  *    a:b:c:...:d for IPv6.
 184  * AST_SOCKADDR_STR_HOST: address only, suitable for a URL
 185  *    a.b.c.d for IPv4
 186  *    [a:b:c:...:d] for IPv6.
 187  * AST_SOCKADDR_STR_PORT: port only
 188  * \retval "(null)" \a addr is null
 189  * \retval "" An error occurred during processing
 190  * \retval string The stringified form of the address
 191  */
 192 char *ast_sockaddr_stringify_fmt(const struct ast_sockaddr *addr, int format);
 193
 194 /*!
 195  * \since 1.8
 196  *
 197  * \brief
 198  * Wrapper around ast_sockaddr_stringify_fmt() with default format
 199  *
 200  * \return same as ast_sockaddr_stringify_fmt()
 201  */
 202 static inline char *ast_sockaddr_stringify(const struct ast_sockaddr *addr)
 203 {
 204         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT);
 205 }
 206
 207 /*!
 208  * \since 1.8
 209  *
 210  * \brief
 211  * Wrapper around ast_sockaddr_stringify_fmt() with default format
 212  *
 213  * \note This address will be suitable for passing to a remote machine via the
 214  * application layer. For example, the scope-id on a link-local IPv6 address
 215  * will be stripped.
 216  *
 217  * \return same as ast_sockaddr_stringify_fmt()
 218  */
 219 static inline char *ast_sockaddr_stringify_remote(const struct ast_sockaddr *addr)
 220 {
 221         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT_REMOTE);
 222 }
 223
 224 /*!
 225  * \since 1.8
 226  *
 227  * \brief
 228  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only
 229  *
 230  * \return same as ast_sockaddr_stringify_fmt()
 231  */
 232 static inline char *ast_sockaddr_stringify_addr(const struct ast_sockaddr *addr)
 233 {
 234         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR);
 235 }
 236
 237 /*!
 238  * \since 1.8
 239  *
 240  * \brief
 241  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only
 242  *
 243  * \note This address will be suitable for passing to a remote machine via the
 244  * application layer. For example, the scope-id on a link-local IPv6 address
 245  * will be stripped.
 246  *
 247  * \return same as ast_sockaddr_stringify_fmt()
 248  */
 249 static inline char *ast_sockaddr_stringify_addr_remote(const struct ast_sockaddr *addr)
 250 {
 251         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR_REMOTE);
 252 }
 253
 254 /*!
 255  * \since 1.8
 256  *
 257  * \brief
 258  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only,
 259  * suitable for a URL (with brackets for IPv6).
 260  *
 261  * \return same as ast_sockaddr_stringify_fmt()
 262  */
 263 static inline char *ast_sockaddr_stringify_host(const struct ast_sockaddr *addr)
 264 {
 265         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST);
 266 }
 267
 268 /*!
 269  * \since 1.8
 270  *
 271  * \brief
 272  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only,
 273  * suitable for a URL (with brackets for IPv6).
 274  *
 275  * \note This address will be suitable for passing to a remote machine via the
 276  * application layer. For example, the scope-id on a link-local IPv6 address
 277  * will be stripped.
 278  *
 279  * \return same as ast_sockaddr_stringify_fmt()
 280  */
 281 static inline char *ast_sockaddr_stringify_host_remote(const struct ast_sockaddr *addr)
 282 {
 283         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST_REMOTE);
 284 }
 285
 286 /*!
 287  * \since 1.8
 288  *
 289  * \brief
 290  * Wrapper around ast_sockaddr_stringify_fmt() to return a port only
 291  *
 292  * \return same as ast_sockaddr_stringify_fmt()
 293  */
 294 static inline char *ast_sockaddr_stringify_port(const struct ast_sockaddr *addr)
 295 {
 296         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_PORT);
 297 }
 298
 299 /*!
 300  * \since 1.8
 301  *
 302  * \brief
 303  * Splits a string into its host and port components
 304  *
 305  * \param str[in]   The string to parse. May be modified by writing a NUL at the end of
 306  *                  the host part.
 307  * \param host[out] Pointer to the host component within \a str.
 308  * \param port[out] Pointer to the port component within \a str.
 309  * \param flags     If set to zero, a port MAY be present. If set to PARSE_PORT_IGNORE, a
 310  *                  port MAY be present but will be ignored. If set to PARSE_PORT_REQUIRE,
 311  *                  a port MUST be present. If set to PARSE_PORT_FORBID, a port MUST NOT
 312  *                  be present.
 313  *
 314  * \retval 1 Success
 315  * \retval 0 Failure
 316  */
 317 int ast_sockaddr_split_hostport(char *str, char **host, char **port, int flags);
 318
 319 /*!
 320  * \since 1.8
 321  *
 322  * \brief
 323  * Parse an IPv4 or IPv6 address string.
 324  *
 325  * \details
 326  * Parses a string containing an IPv4 or IPv6 address followed by an optional
 327  * port (separated by a colon) into a struct ast_sockaddr. The allowed formats
 328  * are the following:
 329  *
 330  * a.b.c.d
 331  * a.b.c.d:port
 332  * a:b:c:...:d
 333  * [a:b:c:...:d]
 334  * [a:b:c:...:d]:port
 335  *
 336  * Host names are NOT allowed.
 337  *
 338  * \param[out] addr The resulting ast_sockaddr
 339  * \param str The string to parse
 340  * \param flags If set to zero, a port MAY be present. If set to
 341  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
 342  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
 343  * port MUST NOT be present.
 344  *
 345  * \retval 1 Success
 346  * \retval 0 Failure
 347  */
 348 int ast_sockaddr_parse(struct ast_sockaddr *addr, const char *str, int flags);
 349
 350 /*!
 351  * \since 1.8
 352  *
 353  * \brief
 354  * Parses a string with an IPv4 or IPv6 address and place results into an array
 355  *
 356  * \details
 357  * Parses a string containing a host name or an IPv4 or IPv6 address followed
 358  * by an optional port (separated by a colon).  The result is returned into a
 359  * array of struct ast_sockaddr. Allowed formats for str are the following:
 360  *
 361  * hostname:port
 362  * host.example.com:port
 363  * a.b.c.d
 364  * a.b.c.d:port
 365  * a:b:c:...:d
 366  * [a:b:c:...:d]
 367  * [a:b:c:...:d]:port
 368  *
 369  * \param[out] addrs The resulting array of ast_sockaddrs
 370  * \param str The string to parse
 371  * \param flags If set to zero, a port MAY be present. If set to
 372  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
 373  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
 374  * port MUST NOT be present.
 375  *
 376  * \param family Only addresses of the given family will be returned. Use 0 or
 377  * AST_SOCKADDR_UNSPEC to get addresses of all families.
 378  *
 379  * \retval 0 Failure
 380  * \retval non-zero The number of elements in addrs array.
 381  */
 382 int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str,
 383                          int flags, int family);
 384
 385 /*!
 386  * \since 1.8
 387  *
 388  * \brief
 389  * Get the port number of a socket address.
 390  *
 391  * \warning Do not use this function unless you really know what you are doing.
 392  * And "I want the port number" is not knowing what you are doing.
 393  *
 394  * \retval 0 Address is null
 395  * \retval non-zero The port number of the ast_sockaddr
 396  */
 397 #define ast_sockaddr_port(addr) _ast_sockaddr_port(addr, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 398 uint16_t _ast_sockaddr_port(const struct ast_sockaddr *addr, const char *file, int line, const char *func);
 399
 400 /*!
 401  * \since 1.8
 402  *
 403  * \brief
 404  * Sets the port number of a socket address.
 405  *
 406  * \warning Do not use this function unless you really know what you are doing.
 407  * And "I want the port number" is not knowing what you are doing.
 408  *
 409  * \param addr Address on which to set the port
 410  * \param port The port you wish to set the address to use
 411  * \retval void
 412  */
 413 #define ast_sockaddr_set_port(addr,port)        _ast_sockaddr_set_port(addr,port,__FILE__,__LINE__,__PRETTY_FUNCTION__)
 414 void _ast_sockaddr_set_port(struct ast_sockaddr *addr, uint16_t port, const char *file, int line, const char *func);
 415
 416 /*!
 417  * \since 1.8
 418  *
 419  * \brief
 420  * Get an IPv4 address of an ast_sockaddr
 421  *
 422  * \warning You should rarely need this function. Only use if you know what
 423  * you're doing.
 424  * \return IPv4 address in network byte order
 425  */
 426 uint32_t ast_sockaddr_ipv4(const struct ast_sockaddr *addr);
 427
 428 /*!
 429  * \since 1.8
 430  *
 431  * \brief
 432  * Determine if the address is an IPv4 address
 433  *
 434  * \warning You should rarely need this function. Only use if you know what
 435  * you're doing.
 436  * \retval 1 This is an IPv4 address
 437  * \retval 0 This is an IPv6 or IPv4-mapped IPv6 address
 438  */
 439 int ast_sockaddr_is_ipv4(const struct ast_sockaddr *addr);
 440
 441 /*!
 442  * \since 1.8
 443  *
 444  * \brief
 445  * Determine if this is an IPv4-mapped IPv6 address
 446  *
 447  * \warning You should rarely need this function. Only use if you know what
 448  * you're doing.
 449  *
 450  * \retval 1 This is an IPv4-mapped IPv6 address.
 451  * \retval 0 This is not an IPv4-mapped IPv6 address.
 452  */
 453 int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr);
 454
 455 /*!
 456  * \since 1.10
 457  *
 458  * \brief
 459  * Determine if an IPv4 address is a multicast address
 460  *
 461  * \parm addr the address to check
 462  *
 463  * This function checks if an address is in the 224.0.0.0/4 network block.
 464  *
 465  * \return non-zero if this is a multicast address
 466  */
 467 int ast_sockaddr_is_ipv4_multicast(const struct ast_sockaddr *addr);
 468
 469 /*!
 470  * \since 1.8
 471  *
 472  * \brief
 473  * Determine if this is a link-local IPv6 address
 474  *
 475  * \warning You should rarely need this function. Only use if you know what
 476  * you're doing.
 477  *
 478  * \retval 1 This is a link-local IPv6 address.
 479  * \retval 0 This is link-local IPv6 address.
 480  */
 481 int ast_sockaddr_is_ipv6_link_local(const struct ast_sockaddr *addr);
 482
 483 /*!
 484  * \since 1.8
 485  *
 486  * \brief
 487  * Determine if this is an IPv6 address
 488  *
 489  * \warning You should rarely need this function. Only use if you know what
 490  * you're doing.
 491  *
 492  * \retval 1 This is an IPv6 or IPv4-mapped IPv6 address.
 493  * \retval 0 This is an IPv4 address.
 494  */
 495 int ast_sockaddr_is_ipv6(const struct ast_sockaddr *addr);
 496
 497 /*!
 498  * \since 1.8
 499  *
 500  * \brief
 501  * Determine if the address type is unspecified, or "any" address.
 502  *
 503  * \details
 504  * For IPv4, this would be the address 0.0.0.0, and for IPv6,
 505  * this would be the address ::. The port number is ignored.
 506  *
 507  * \retval 1 This is an "any" address
 508  * \retval 0 This is not an "any" address
 509  */
 510 int ast_sockaddr_is_any(const struct ast_sockaddr *addr);
 511
 512 /*!
 513  * \since 1.8
 514  *
 515  * \brief
 516  * Computes a hash value from the address. The port is ignored.
 517  *
 518  * \retval 0 Unknown address family
 519  * \retval other A 32-bit hash derived from the address
 520  */
 521 int ast_sockaddr_hash(const struct ast_sockaddr *addr);
 522
 523 /*!
 524  * \since 1.8
 525  *
 526  * \brief
 527  * Wrapper around accept(2) that uses struct ast_sockaddr.
 528  *
 529  * \details
 530  * For parameter and return information, see the man page for
 531  * accept(2).
 532  */
 533 int ast_accept(int sockfd, struct ast_sockaddr *addr);
 534
 535 /*!
 536  * \since 1.8
 537  *
 538  * \brief
 539  * Wrapper around bind(2) that uses struct ast_sockaddr.
 540  *
 541  * \details
 542  * For parameter and return information, see the man page for
 543  * bind(2).
 544  */
 545 int ast_bind(int sockfd, const struct ast_sockaddr *addr);
 546
 547 /*!
 548  * \since 1.8
 549  *
 550  * \brief
 551  * Wrapper around connect(2) that uses struct ast_sockaddr.
 552  *
 553  * \details
 554  * For parameter and return information, see the man page for
 555  * connect(2).
 556  */
 557 int ast_connect(int sockfd, const struct ast_sockaddr *addr);
 558
 559 /*!
 560  * \since 1.8
 561  *
 562  * \brief
 563  * Wrapper around getsockname(2) that uses struct ast_sockaddr.
 564  *
 565  * \details
 566  * For parameter and return information, see the man page for
 567  * getsockname(2).
 568  */
 569 int ast_getsockname(int sockfd, struct ast_sockaddr *addr);
 570
 571 /*!
 572  * \since 1.8
 573  *
 574  * \brief
 575  * Wrapper around recvfrom(2) that uses struct ast_sockaddr.
 576  *
 577  * \details
 578  * For parameter and return information, see the man page for
 579  * recvfrom(2).
 580  */
 581 ssize_t ast_recvfrom(int sockfd, void *buf, size_t len, int flags,
 582                      struct ast_sockaddr *src_addr);
 583
 584 /*!
 585  * \since 1.8
 586  *
 587  * \brief
 588  * Wrapper around sendto(2) that uses ast_sockaddr.
 589  *
 590  * \details
 591  * For parameter and
 592  * return information, see the man page for sendto(2)
 593  */
 594 ssize_t ast_sendto(int sockfd, const void *buf, size_t len, int flags,
 595                    const struct ast_sockaddr *dest_addr);
 596
 597 /*!
 598  * \since 1.8
 599  *
 600  * \brief
 601  * Set type of service
 602  *
 603  * \details
 604  * Set ToS ("Type of Service for IPv4 and "Traffic Class for IPv6) and
 605  * CoS (Linux's SO_PRIORITY)
 606  *
 607  * \param sockfd File descriptor for socket on which to set the parameters
 608  * \param tos The type of service for the socket
 609  * \param cos The cost of service for the socket
 610  * \param desc A text description of the socket in question.
 611  * \retval 0 Success
 612  * \retval -1 Error, with errno set to an appropriate value
 613  */
 614 int ast_set_qos(int sockfd, int tos, int cos, const char *desc);
 615
 616 /*!
 617  * These are backward compatibility functions that may be used by subsystems
 618  * that have not yet been converted to IPv6. They will be removed when all
 619  * subsystems are IPv6-ready.
 620  */
 621 /*@{*/
 622
 623 /*!
 624  * \since 1.8
 625  *
 626  * \brief
 627  * Converts a struct ast_sockaddr to a struct sockaddr_in.
 628  *
 629  * \param addr The ast_sockaddr to convert
 630  * \param[out] sin The resulting sockaddr_in struct
 631  * \retval nonzero Success
 632  * \retval zero Failure
 633  */
 634 #define ast_sockaddr_to_sin(addr,sin)   _ast_sockaddr_to_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 635 int _ast_sockaddr_to_sin(const struct ast_sockaddr *addr,
 636                         struct sockaddr_in *sin, const char *file, int line, const char *func);
 637
 638 /*!
 639  * \since 1.8
 640  *
 641  * \brief
 642  * Converts a struct sockaddr_in to a struct ast_sockaddr.
 643  *
 644  * \param sin The sockaddr_in to convert
 645  * \return an ast_sockaddr structure
 646  */
 647 #define ast_sockaddr_from_sin(addr,sin) _ast_sockaddr_from_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 648 void _ast_sockaddr_from_sin(struct ast_sockaddr *addr, const struct sockaddr_in *sin,
 649                 const char *file, int line, const char *func);
 650
 651 /*@}*/
 652
 653 #if defined(__cplusplus) || defined(c_plusplus)
 654 }
 655 #endif
 656
 657 #endif /* _ASTERISK_NETSOCK2_H */