Merged revisions 324484 via svnmerge from
[asterisk/asterisk.git] / 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 */