Merged revisions 321044 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_HOST           AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_BRACKETS
156 #define AST_SOCKADDR_STR_DEFAULT        AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT
157
158 /*!
159  * \since 1.8
160  *
161  * \brief
162  * Convert a socket address to a string.
163  *
164  * \details
165  * This will be of the form a.b.c.d:xyz
166  * for IPv4 and [a:b:c:...:d]:xyz for IPv6.
167  *
168  * This function is thread-safe. The returned string is on static
169  * thread-specific storage.
170  *
171  * \param addr The input to be stringified
172  * \param format one of the following:
173  * AST_SOCKADDR_STR_DEFAULT:
174  *    a.b.c.d:xyz for IPv4
175  *    [a:b:c:...:d]:xyz for IPv6.
176  * AST_SOCKADDR_STR_ADDR: address only
177  *    a.b.c.d for IPv4
178  *    a:b:c:...:d for IPv6.
179  * AST_SOCKADDR_STR_HOST: address only, suitable for a URL
180  *    a.b.c.d for IPv4
181  *    [a:b:c:...:d] for IPv6.
182  * AST_SOCKADDR_STR_PORT: port only
183  * \retval "(null)" \a addr is null
184  * \retval "" An error occurred during processing
185  * \retval string The stringified form of the address
186  */
187 char *ast_sockaddr_stringify_fmt(const struct ast_sockaddr *addr, int format);
188
189 /*!
190  * \since 1.8
191  *
192  * \brief
193  * Wrapper around ast_sockaddr_stringify_fmt() with default format
194  *
195  * \return same as ast_sockaddr_stringify_fmt()
196  */
197 static inline char *ast_sockaddr_stringify(const struct ast_sockaddr *addr)
198 {
199         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT);
200 }
201
202 /*!
203  * \since 1.8
204  *
205  * \brief
206  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only
207  *
208  * \return same as ast_sockaddr_stringify_fmt()
209  */
210 static inline char *ast_sockaddr_stringify_addr(const struct ast_sockaddr *addr)
211 {
212         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR);
213 }
214
215 /*!
216  * \since 1.8
217  *
218  * \brief
219  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only,
220  * suitable for a URL (with brackets for IPv6).
221  *
222  * \return same as ast_sockaddr_stringify_fmt()
223  */
224 static inline char *ast_sockaddr_stringify_host(const struct ast_sockaddr *addr)
225 {
226         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST);
227 }
228
229 /*!
230  * \since 1.8
231  *
232  * \brief
233  * Wrapper around ast_sockaddr_stringify_fmt() to return a port only
234  *
235  * \return same as ast_sockaddr_stringify_fmt()
236  */
237 static inline char *ast_sockaddr_stringify_port(const struct ast_sockaddr *addr)
238 {
239         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_PORT);
240 }
241
242 /*!
243  * \since 1.8
244  *
245  * \brief
246  * Splits a string into its host and port components
247  *
248  * \param str[in]   The string to parse. May be modified by writing a NUL at the end of
249  *                  the host part.
250  * \param host[out] Pointer to the host component within \a str.
251  * \param port[out] Pointer to the port component within \a str.
252  * \param flags     If set to zero, a port MAY be present. If set to PARSE_PORT_IGNORE, a
253  *                  port MAY be present but will be ignored. If set to PARSE_PORT_REQUIRE,
254  *                  a port MUST be present. If set to PARSE_PORT_FORBID, a port MUST NOT
255  *                  be present.
256  *
257  * \retval 1 Success
258  * \retval 0 Failure
259  */
260 int ast_sockaddr_split_hostport(char *str, char **host, char **port, int flags);
261
262 /*!
263  * \since 1.8
264  *
265  * \brief
266  * Parse an IPv4 or IPv6 address string.
267  *
268  * \details
269  * Parses a string containing an IPv4 or IPv6 address followed by an optional
270  * port (separated by a colon) into a struct ast_sockaddr. The allowed formats
271  * are the following:
272  *
273  * a.b.c.d
274  * a.b.c.d:port
275  * a:b:c:...:d
276  * [a:b:c:...:d]
277  * [a:b:c:...:d]:port
278  *
279  * Host names are NOT allowed.
280  *
281  * \param[out] addr The resulting ast_sockaddr
282  * \param str The string to parse
283  * \param flags If set to zero, a port MAY be present. If set to
284  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
285  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
286  * port MUST NOT be present.
287  *
288  * \retval 1 Success
289  * \retval 0 Failure
290  */
291 int ast_sockaddr_parse(struct ast_sockaddr *addr, const char *str, int flags);
292
293 /*!
294  * \since 1.8
295  *
296  * \brief
297  * Parses a string with an IPv4 or IPv6 address and place results into an array
298  *
299  * \details
300  * Parses a string containing a host name or an IPv4 or IPv6 address followed
301  * by an optional port (separated by a colon).  The result is returned into a
302  * array of struct ast_sockaddr. Allowed formats for str are the following:
303  *
304  * hostname:port
305  * host.example.com:port
306  * a.b.c.d
307  * a.b.c.d:port
308  * a:b:c:...:d
309  * [a:b:c:...:d]
310  * [a:b:c:...:d]:port
311  *
312  * \param[out] addrs The resulting array of ast_sockaddrs
313  * \param str The string to parse
314  * \param flags If set to zero, a port MAY be present. If set to
315  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
316  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
317  * port MUST NOT be present.
318  *
319  * \param family Only addresses of the given family will be returned. Use 0 or
320  * AST_SOCKADDR_UNSPEC to get addresses of all families.
321  *
322  * \retval 0 Failure
323  * \retval non-zero The number of elements in addrs array.
324  */
325 int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str,
326                          int flags, int family);
327
328 /*!
329  * \since 1.8
330  *
331  * \brief
332  * Get the port number of a socket address.
333  *
334  * \warning Do not use this function unless you really know what you are doing.
335  * And "I want the port number" is not knowing what you are doing.
336  *
337  * \retval 0 Address is null
338  * \retval non-zero The port number of the ast_sockaddr
339  */
340 #define ast_sockaddr_port(addr) _ast_sockaddr_port(addr, __FILE__, __LINE__, __PRETTY_FUNCTION__)
341 uint16_t _ast_sockaddr_port(const struct ast_sockaddr *addr, const char *file, int line, const char *func);
342
343 /*!
344  * \since 1.8
345  *
346  * \brief
347  * Sets the port number of a socket address.
348  *
349  * \warning Do not use this function unless you really know what you are doing.
350  * And "I want the port number" is not knowing what you are doing.
351  *
352  * \param addr Address on which to set the port
353  * \param port The port you wish to set the address to use
354  * \retval void
355  */
356 #define ast_sockaddr_set_port(addr,port)        _ast_sockaddr_set_port(addr,port,__FILE__,__LINE__,__PRETTY_FUNCTION__)
357 void _ast_sockaddr_set_port(struct ast_sockaddr *addr, uint16_t port, const char *file, int line, const char *func);
358
359 /*!
360  * \since 1.8
361  *
362  * \brief
363  * Get an IPv4 address of an ast_sockaddr
364  *
365  * \warning You should rarely need this function. Only use if you know what
366  * you're doing.
367  * \return IPv4 address in network byte order
368  */
369 uint32_t ast_sockaddr_ipv4(const struct ast_sockaddr *addr);
370
371 /*!
372  * \since 1.8
373  *
374  * \brief
375  * Determine if the address is an IPv4 address
376  *
377  * \warning You should rarely need this function. Only use if you know what
378  * you're doing.
379  * \retval 1 This is an IPv4 address
380  * \retval 0 This is an IPv6 or IPv4-mapped IPv6 address
381  */
382 int ast_sockaddr_is_ipv4(const struct ast_sockaddr *addr);
383
384 /*!
385  * \since 1.8
386  *
387  * \brief
388  * Determine if this is an IPv4-mapped IPv6 address
389  *
390  * \warning You should rarely need this function. Only use if you know what
391  * you're doing.
392  *
393  * \retval 1 This is an IPv4-mapped IPv6 address.
394  * \retval 0 This is not an IPv4-mapped IPv6 address.
395  */
396 int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr);
397
398 /*!
399  * \since 1.10
400  *
401  * \brief
402  * Determine if an IPv4 address is a multicast address
403  *
404  * \parm addr the address to check
405  *
406  * This function checks if an address is in the 224.0.0.0/4 network block.
407  *
408  * \return non-zero if this is a multicast address
409  */
410 int ast_sockaddr_is_ipv4_multicast(const struct ast_sockaddr *addr);
411
412 /*!
413  * \since 1.8
414  *
415  * \brief
416  * Determine if this is an IPv6 address
417  *
418  * \warning You should rarely need this function. Only use if you know what
419  * you're doing.
420  *
421  * \retval 1 This is an IPv6 or IPv4-mapped IPv6 address.
422  * \retval 0 This is an IPv4 address.
423  */
424 int ast_sockaddr_is_ipv6(const struct ast_sockaddr *addr);
425
426 /*!
427  * \since 1.8
428  *
429  * \brief
430  * Determine if the address type is unspecified, or "any" address.
431  *
432  * \details
433  * For IPv4, this would be the address 0.0.0.0, and for IPv6,
434  * this would be the address ::. The port number is ignored.
435  *
436  * \retval 1 This is an "any" address
437  * \retval 0 This is not an "any" address
438  */
439 int ast_sockaddr_is_any(const struct ast_sockaddr *addr);
440
441 /*!
442  * \since 1.8
443  *
444  * \brief
445  * Computes a hash value from the address. The port is ignored.
446  *
447  * \retval 0 Unknown address family
448  * \retval other A 32-bit hash derived from the address
449  */
450 int ast_sockaddr_hash(const struct ast_sockaddr *addr);
451
452 /*!
453  * \since 1.8
454  *
455  * \brief
456  * Wrapper around accept(2) that uses struct ast_sockaddr.
457  *
458  * \details
459  * For parameter and return information, see the man page for
460  * accept(2).
461  */
462 int ast_accept(int sockfd, struct ast_sockaddr *addr);
463
464 /*!
465  * \since 1.8
466  *
467  * \brief
468  * Wrapper around bind(2) that uses struct ast_sockaddr.
469  *
470  * \details
471  * For parameter and return information, see the man page for
472  * bind(2).
473  */
474 int ast_bind(int sockfd, const struct ast_sockaddr *addr);
475
476 /*!
477  * \since 1.8
478  *
479  * \brief
480  * Wrapper around connect(2) that uses struct ast_sockaddr.
481  *
482  * \details
483  * For parameter and return information, see the man page for
484  * connect(2).
485  */
486 int ast_connect(int sockfd, const struct ast_sockaddr *addr);
487
488 /*!
489  * \since 1.8
490  *
491  * \brief
492  * Wrapper around getsockname(2) that uses struct ast_sockaddr.
493  *
494  * \details
495  * For parameter and return information, see the man page for
496  * getsockname(2).
497  */
498 int ast_getsockname(int sockfd, struct ast_sockaddr *addr);
499
500 /*!
501  * \since 1.8
502  *
503  * \brief
504  * Wrapper around recvfrom(2) that uses struct ast_sockaddr.
505  *
506  * \details
507  * For parameter and return information, see the man page for
508  * recvfrom(2).
509  */
510 ssize_t ast_recvfrom(int sockfd, void *buf, size_t len, int flags,
511                      struct ast_sockaddr *src_addr);
512
513 /*!
514  * \since 1.8
515  *
516  * \brief
517  * Wrapper around sendto(2) that uses ast_sockaddr.
518  *
519  * \details
520  * For parameter and
521  * return information, see the man page for sendto(2)
522  */
523 ssize_t ast_sendto(int sockfd, const void *buf, size_t len, int flags,
524                    const struct ast_sockaddr *dest_addr);
525
526 /*!
527  * \since 1.8
528  *
529  * \brief
530  * Set type of service
531  *
532  * \details
533  * Set ToS ("Type of Service for IPv4 and "Traffic Class for IPv6) and
534  * CoS (Linux's SO_PRIORITY)
535  *
536  * \param sockfd File descriptor for socket on which to set the parameters
537  * \param tos The type of service for the socket
538  * \param cos The cost of service for the socket
539  * \param desc A text description of the socket in question.
540  * \retval 0 Success
541  * \retval -1 Error, with errno set to an appropriate value
542  */
543 int ast_set_qos(int sockfd, int tos, int cos, const char *desc);
544
545 /*!
546  * These are backward compatibility functions that may be used by subsystems
547  * that have not yet been converted to IPv6. They will be removed when all
548  * subsystems are IPv6-ready.
549  */
550 /*@{*/
551
552 /*!
553  * \since 1.8
554  *
555  * \brief
556  * Converts a struct ast_sockaddr to a struct sockaddr_in.
557  *
558  * \param addr The ast_sockaddr to convert
559  * \param[out] sin The resulting sockaddr_in struct
560  * \retval nonzero Success
561  * \retval zero Failure
562  */
563 #define ast_sockaddr_to_sin(addr,sin)   _ast_sockaddr_to_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__)
564 int _ast_sockaddr_to_sin(const struct ast_sockaddr *addr,
565                         struct sockaddr_in *sin, const char *file, int line, const char *func);
566
567 /*!
568  * \since 1.8
569  *
570  * \brief
571  * Converts a struct sockaddr_in to a struct ast_sockaddr.
572  *
573  * \param sin The sockaddr_in to convert
574  * \return an ast_sockaddr structure
575  */
576 #define ast_sockaddr_from_sin(addr,sin) _ast_sockaddr_from_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__)
577 void _ast_sockaddr_from_sin(struct ast_sockaddr *addr, const struct sockaddr_in *sin,
578                 const char *file, int line, const char *func);
579
580 /*@}*/
581
582 #if defined(__cplusplus) || defined(c_plusplus)
583 }
584 #endif
585
586 #endif /* _ASTERISK_NETSOCK2_H */