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