res_pjsip: Log IPv6 addresses correctly
[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  * String buffer size that can accommodate a fully stringified representation of a
36  * supported IP address & port:
37  *
38  * - 45 bytes for an IPv6 address
39  * -  2 bytes for brackets around an IPv6 address
40  * -  1 byte for the port separator (a colon)
41  * -  5 bytes for the port
42  * -  1 byte for the zero-terminator
43  */
44 #define AST_SOCKADDR_BUFLEN (45 + 2 + 1 + 5 + 1)
45
46 /*!
47  * Values for address families that we support. This is reproduced from socket.h
48  * because we do not want users to include that file. Only netsock2.c should
49  * ever include socket.h.
50  */
51 enum {
52         AST_AF_UNSPEC = AF_UNSPEC,
53         AST_AF_INET   = AF_INET,
54         AST_AF_INET6  = AF_INET6,
55 };
56
57 enum ast_transport {
58         AST_TRANSPORT_UDP   = 1,
59         AST_TRANSPORT_TCP   = 1 << 1,
60         AST_TRANSPORT_TLS   = 1 << 2,
61         AST_TRANSPORT_WS    = 1 << 3,
62         AST_TRANSPORT_WSS   = 1 << 4,
63 };
64
65 /*!
66  * \brief
67  * Isolate a 32-bit section of an IPv6 address
68  *
69  * An IPv6 address can be divided into 4 32-bit chunks. This gives
70  * easy access to one of these chunks.
71  *
72  * \param sin6 A pointer to a struct sockaddr_in6
73  * \param index Which 32-bit chunk to operate on. Must be in the range 0-3.
74  */
75 #define V6_WORD(sin6, index) ((uint32_t *)&((sin6)->sin6_addr))[(index)]
76
77 /*!
78  * \brief Socket address structure.
79  *
80  * \details
81  * The first member is big enough to contain addresses of any
82  * family. The second member contains the length (in bytes) used
83  * in the first member.
84  *
85  * \note
86  * Some BSDs have the length embedded in sockaddr structs. We
87  * ignore them. (This is the right thing to do.)
88  *
89  * \note
90  * It is important to always initialize ast_sockaddr before use
91  * -- even if they are passed to ast_sockaddr_copy() as the
92  * underlying storage could be bigger than what ends up being
93  * copied -- leaving part of the data unitialized.
94  */
95 struct ast_sockaddr {
96         struct sockaddr_storage  ss;
97         socklen_t len;
98 };
99
100 /*!
101  * \brief
102  * Convert an IPv4-mapped IPv6 address into an IPv4 address.
103  *
104  * \warning You should rarely need this function. Only call this
105  * if you know what you're doing.
106  *
107  * \param addr The IPv4-mapped address to convert
108  * \param ast_mapped The resulting IPv4 address
109  * \retval 0 Unable to make the conversion
110  * \retval 1 Successful conversion
111  */
112 int ast_sockaddr_ipv4_mapped(const struct ast_sockaddr *addr, struct ast_sockaddr *ast_mapped);
113
114 /*!
115  * \since 1.8
116  *
117  * \brief
118  * Checks if the ast_sockaddr is null. "null" in this sense essentially
119  * means uninitialized, or having a 0 length.
120  *
121  * \param addr Pointer to the ast_sockaddr we wish to check
122  * \retval 1 \a addr is null
123  * \retval 0 \a addr is non-null.
124  */
125 static inline int ast_sockaddr_isnull(const struct ast_sockaddr *addr)
126 {
127         return !addr || addr->len == 0;
128 }
129
130 /*!
131  * \since 1.8
132  *
133  * \brief
134  * Sets address \a addr to null.
135  *
136  * \retval void
137  */
138 static inline void ast_sockaddr_setnull(struct ast_sockaddr *addr)
139 {
140         addr->len = 0;
141 }
142
143 /*!
144  * \brief
145  * Copies the data from a sockaddr to an ast_sockaddr
146  *
147  * \param dst The destination ast_sockaddr
148  * \param src The source sockaddr
149  * \param len Length of the value stored in sockaddr
150  * \retval void
151  */
152 static inline void ast_sockaddr_copy_sockaddr(struct ast_sockaddr *dst,
153                 struct sockaddr *src, socklen_t len)
154 {
155         memcpy(dst, src, len);
156         dst->len = len;
157 }
158
159 /*!
160  * \since 1.8
161  *
162  * \brief
163  * Copies the data from one ast_sockaddr to another
164  *
165  * \param dst The destination ast_sockaddr
166  * \param src The source ast_sockaddr
167  * \retval void
168  */
169 static inline void ast_sockaddr_copy(struct ast_sockaddr *dst,
170                 const struct ast_sockaddr *src)
171 {
172         memcpy(dst, src, src->len);
173         dst->len = src->len;
174 };
175
176 /*!
177  * \since 1.8
178  *
179  * \brief
180  * Compares two ast_sockaddr structures
181  *
182  * \retval -1 \a a is lexicographically smaller than \a b
183  * \retval 0 \a a is equal to \a b
184  * \retval 1 \a b is lexicographically smaller than \a a
185  */
186 int ast_sockaddr_cmp(const struct ast_sockaddr *a, const struct ast_sockaddr *b);
187
188 /*!
189  * \since 1.8
190  *
191  * \brief
192  * Compares the addresses of two ast_sockaddr structures.
193  *
194  * \retval -1 \a a is lexicographically smaller than \a b
195  * \retval 0 \a a is equal to \a b
196  * \retval 1 \a b is lexicographically smaller than \a a
197  */
198 int ast_sockaddr_cmp_addr(const struct ast_sockaddr *a, const struct ast_sockaddr *b);
199
200 #define AST_SOCKADDR_STR_ADDR           (1 << 0)
201 #define AST_SOCKADDR_STR_PORT           (1 << 1)
202 #define AST_SOCKADDR_STR_BRACKETS       (1 << 2)
203 #define AST_SOCKADDR_STR_REMOTE         (1 << 3)
204 #define AST_SOCKADDR_STR_HOST           (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_BRACKETS)
205 #define AST_SOCKADDR_STR_DEFAULT        (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT)
206 #define AST_SOCKADDR_STR_ADDR_REMOTE     (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_REMOTE)
207 #define AST_SOCKADDR_STR_HOST_REMOTE     (AST_SOCKADDR_STR_HOST | AST_SOCKADDR_STR_REMOTE)
208 #define AST_SOCKADDR_STR_DEFAULT_REMOTE  (AST_SOCKADDR_STR_DEFAULT | AST_SOCKADDR_STR_REMOTE)
209 #define AST_SOCKADDR_STR_FORMAT_MASK     (AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT | AST_SOCKADDR_STR_BRACKETS)
210
211 /*!
212  * \since 1.8
213  *
214  * \brief
215  * Convert a socket address to a string.
216  *
217  * \details
218  * This will be of the form a.b.c.d:xyz
219  * for IPv4 and [a:b:c:...:d]:xyz for IPv6.
220  *
221  * This function is thread-safe. The returned string is on static
222  * thread-specific storage.
223  *
224  * \param addr The input to be stringified
225  * \param format one of the following:
226  * AST_SOCKADDR_STR_DEFAULT:
227  *    a.b.c.d:xyz for IPv4
228  *    [a:b:c:...:d]:xyz for IPv6.
229  * AST_SOCKADDR_STR_ADDR: address only
230  *    a.b.c.d for IPv4
231  *    a:b:c:...:d for IPv6.
232  * AST_SOCKADDR_STR_HOST: address only, suitable for a URL
233  *    a.b.c.d for IPv4
234  *    [a:b:c:...:d] for IPv6.
235  * AST_SOCKADDR_STR_PORT: port only
236  *
237  * \note The string pointer returned by this function will point to a string that
238  * will be changed whenever any form of ast_sockaddr_stringify_fmt is called on that
239  * thread. Because of this, it is important that if you use this function, you use the
240  * string before another use of this function is made elsewhere in the same thread.
241  * The easiest way to accomplish this is by immediately copying the string to a buffer
242  * with something like ast_strdupa.
243  *
244  * \retval "(null)" \a addr is null
245  * \retval "" An error occurred during processing
246  * \retval string The stringified form of the address
247  */
248 char *ast_sockaddr_stringify_fmt(const struct ast_sockaddr *addr, int format);
249
250 /*!
251  * \since 1.8
252  *
253  * \brief
254  * Wrapper around ast_sockaddr_stringify_fmt() with default format
255  *
256  * \return same as ast_sockaddr_stringify_fmt()
257  */
258 static inline char *ast_sockaddr_stringify(const struct ast_sockaddr *addr)
259 {
260         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT);
261 }
262
263 /*!
264  * \since 1.8
265  *
266  * \brief
267  * Wrapper around ast_sockaddr_stringify_fmt() with default format
268  *
269  * \note This address will be suitable for passing to a remote machine via the
270  * application layer. For example, the scope-id on a link-local IPv6 address
271  * will be stripped.
272  *
273  * \return same as ast_sockaddr_stringify_fmt()
274  */
275 static inline char *ast_sockaddr_stringify_remote(const struct ast_sockaddr *addr)
276 {
277         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT_REMOTE);
278 }
279
280 /*!
281  * \since 1.8
282  *
283  * \brief
284  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only
285  *
286  * \return same as ast_sockaddr_stringify_fmt()
287  */
288 static inline char *ast_sockaddr_stringify_addr(const struct ast_sockaddr *addr)
289 {
290         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR);
291 }
292
293 /*!
294  * \since 12.4
295  *
296  * \brief
297  * Count the 1 bits in a netmask
298  *
299  * \return number of 1 bits
300  */
301 int ast_sockaddr_cidr_bits(const struct ast_sockaddr *sa);
302
303 /*!
304  * \since 1.8
305  *
306  * \brief
307  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only
308  *
309  * \note This address will be suitable for passing to a remote machine via the
310  * application layer. For example, the scope-id on a link-local IPv6 address
311  * will be stripped.
312  *
313  * \return same as ast_sockaddr_stringify_fmt()
314  */
315 static inline char *ast_sockaddr_stringify_addr_remote(const struct ast_sockaddr *addr)
316 {
317         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR_REMOTE);
318 }
319
320 /*!
321  * \since 1.8
322  *
323  * \brief
324  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only,
325  * suitable for a URL (with brackets for IPv6).
326  *
327  * \return same as ast_sockaddr_stringify_fmt()
328  */
329 static inline char *ast_sockaddr_stringify_host(const struct ast_sockaddr *addr)
330 {
331         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST);
332 }
333
334 /*!
335  * \since 1.8
336  *
337  * \brief
338  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only,
339  * suitable for a URL (with brackets for IPv6).
340  *
341  * \note This address will be suitable for passing to a remote machine via the
342  * application layer. For example, the scope-id on a link-local IPv6 address
343  * will be stripped.
344  *
345  * \return same as ast_sockaddr_stringify_fmt()
346  */
347 static inline char *ast_sockaddr_stringify_host_remote(const struct ast_sockaddr *addr)
348 {
349         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST_REMOTE);
350 }
351
352 /*!
353  * \since 1.8
354  *
355  * \brief
356  * Wrapper around ast_sockaddr_stringify_fmt() to return a port only
357  *
358  * \return same as ast_sockaddr_stringify_fmt()
359  */
360 static inline char *ast_sockaddr_stringify_port(const struct ast_sockaddr *addr)
361 {
362         return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_PORT);
363 }
364
365 /*!
366  * \since 1.8
367  *
368  * \brief
369  * Splits a string into its host and port components
370  *
371  * \param[in] str The string to parse. May be modified by writing a NUL at the end of
372  *                  the host part.
373  * \param[out] host Pointer to the host component within \a str.
374  * \param[out] port Pointer to the port component within \a str.
375  * \param flags     If set to zero, a port MAY be present. If set to PARSE_PORT_IGNORE, a
376  *                  port MAY be present but will be ignored. If set to PARSE_PORT_REQUIRE,
377  *                  a port MUST be present. If set to PARSE_PORT_FORBID, a port MUST NOT
378  *                  be present.
379  *
380  * \retval 1 Success
381  * \retval 0 Failure
382  */
383 int ast_sockaddr_split_hostport(char *str, char **host, char **port, int flags);
384
385 /*!
386  * \since 1.8
387  *
388  * \brief
389  * Parse an IPv4 or IPv6 address string.
390  *
391  * \details
392  * Parses a string containing an IPv4 or IPv6 address followed by an optional
393  * port (separated by a colon) into a struct ast_sockaddr. The allowed formats
394  * are the following:
395  *
396  * a.b.c.d
397  * a.b.c.d:port
398  * a:b:c:...:d
399  * [a:b:c:...:d]
400  * [a:b:c:...:d]:port
401  *
402  * Host names are NOT allowed.
403  *
404  * \param[out] addr The resulting ast_sockaddr. This MAY be NULL from
405  * functions that are performing validity checks only, e.g. ast_parse_arg().
406  * \param str The string to parse
407  * \param flags If set to zero, a port MAY be present. If set to
408  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
409  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
410  * port MUST NOT be present.
411  *
412  * \retval 1 Success
413  * \retval 0 Failure
414  */
415 int ast_sockaddr_parse(struct ast_sockaddr *addr, const char *str, int flags);
416
417 /*!
418  * \since 1.8
419  *
420  * \brief
421  * Parses a string with an IPv4 or IPv6 address and place results into an array
422  *
423  * \details
424  * Parses a string containing a host name or an IPv4 or IPv6 address followed
425  * by an optional port (separated by a colon).  The result is returned into a
426  * array of struct ast_sockaddr. Allowed formats for str are the following:
427  *
428  * hostname:port
429  * host.example.com:port
430  * a.b.c.d
431  * a.b.c.d:port
432  * a:b:c:...:d
433  * [a:b:c:...:d]
434  * [a:b:c:...:d]:port
435  *
436  * \param[out] addrs The resulting array of ast_sockaddrs
437  * \param str The string to parse
438  * \param flags If set to zero, a port MAY be present. If set to
439  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
440  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
441  * port MUST NOT be present.
442  *
443  * \param family Only addresses of the given family will be returned. Use 0 or
444  * AST_AF_UNSPEC to get addresses of all families.
445  *
446  * \retval 0 Failure
447  * \retval non-zero The number of elements in addrs array.
448  */
449 int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str,
450                          int flags, int family);
451
452 /*!
453  * \since 16.0
454  *
455  * \brief
456  * Return the first entry from ast_sockaddr_resolve filtered by address family
457  *
458  * \details
459  * Parses a string containing a host name or an IPv4 or IPv6 address followed
460  * by an optional port (separated by a colon).  This function only returns the
461  * first address into the ast_sockaddr. Allowed formats for name are the following:
462  *
463  * hostname:port
464  * host.example.com:port
465  * a.b.c.d
466  * a.b.c.d:port
467  * a:b:c:...:d
468  * [a:b:c:...:d]
469  * [a:b:c:...:d]:port
470  *
471  * \param[out] addr The resulting ast_sockaddr
472  * \param name The string to parse
473  * \param flags If set to zero, a port MAY be present. If set to
474  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
475  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
476  * port MUST NOT be present.
477  *
478  * \param family Only addresses of the given family will be returned. Use 0 or
479  * AST_AF_UNSPEC to specify any address family.  Behavior is ultimately determined
480  * by getaddrinfo in how it orders return results.  First result is selected to
481  * be returned.
482  *
483  * \retval 0 Success
484  * \retval non-zero Failure
485  * \warning Using this function potentially means you have a faulty design.
486  */
487 int ast_sockaddr_resolve_first_af(struct ast_sockaddr *addr,
488                                       const char* name, int flag, int family);
489
490 /*!
491  * \brief
492  * Apply a netmask to an address and store the result in a separate structure.
493  *
494  * When dealing with IPv6 addresses, one cannot apply a netmask with a simple
495  * logical AND operation.  Futhermore, the incoming address may be an IPv4
496  * address and needs to be mapped properly before attempting to apply a rule.
497  *
498  * \param addr The IP address to apply the mask to.
499  * \param netmask The netmask configured in the host access rule.
500  * \param result The resultant address after applying the netmask to the given address
501  * \retval 0 Successfully applied netmask
502  * \retval -1 Failed to apply netmask
503  */
504 int ast_sockaddr_apply_netmask(const struct ast_sockaddr *addr, const struct ast_sockaddr *netmask,
505                 struct ast_sockaddr *result);
506
507 /*!
508  * \since 1.8
509  *
510  * \brief
511  * Get the port number of a socket address.
512  *
513  * \warning Do not use this function unless you really know what you are doing.
514  * And "I want the port number" is not knowing what you are doing.
515  *
516  * \retval 0 Address is null
517  * \retval non-zero The port number of the ast_sockaddr
518  */
519 #define ast_sockaddr_port(addr) _ast_sockaddr_port(addr, __FILE__, __LINE__, __PRETTY_FUNCTION__)
520 uint16_t _ast_sockaddr_port(const struct ast_sockaddr *addr, const char *file, int line, const char *func);
521
522 /*!
523  * \since 1.8
524  *
525  * \brief
526  * Sets the port number of a socket address.
527  *
528  * \warning Do not use this function unless you really know what you are doing.
529  * And "I want the port number" is not knowing what you are doing.
530  *
531  * \param addr Address on which to set the port
532  * \param port The port you wish to set the address to use
533  * \retval void
534  */
535 #define ast_sockaddr_set_port(addr,port)        _ast_sockaddr_set_port(addr,port,__FILE__,__LINE__,__PRETTY_FUNCTION__)
536 void _ast_sockaddr_set_port(struct ast_sockaddr *addr, uint16_t port, const char *file, int line, const char *func);
537
538 /*!
539  * \since 1.8
540  *
541  * \brief
542  * Get an IPv4 address of an ast_sockaddr
543  *
544  * \warning You should rarely need this function. Only use if you know what
545  * you're doing.
546  * \return IPv4 address in network byte order
547  */
548 uint32_t ast_sockaddr_ipv4(const struct ast_sockaddr *addr);
549
550 /*!
551  * \since 1.8
552  *
553  * \brief
554  * Determine if the address is an IPv4 address
555  *
556  * \warning You should rarely need this function. Only use if you know what
557  * you're doing.
558  * \retval 1 This is an IPv4 address
559  * \retval 0 This is an IPv6 or IPv4-mapped IPv6 address
560  */
561 int ast_sockaddr_is_ipv4(const struct ast_sockaddr *addr);
562
563 /*!
564  * \since 1.8
565  *
566  * \brief
567  * Determine if this is an IPv4-mapped IPv6 address
568  *
569  * \warning You should rarely need this function. Only use if you know what
570  * you're doing.
571  *
572  * \retval 1 This is an IPv4-mapped IPv6 address.
573  * \retval 0 This is not an IPv4-mapped IPv6 address.
574  */
575 int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr);
576
577 /*!
578  * \since 10.0
579  *
580  * \brief
581  * Determine if an IPv4 address is a multicast address
582  *
583  * \param addr the address to check
584  *
585  * This function checks if an address is in the 224.0.0.0/4 network block.
586  *
587  * \return non-zero if this is a multicast address
588  */
589 int ast_sockaddr_is_ipv4_multicast(const struct ast_sockaddr *addr);
590
591 /*!
592  * \since 1.8
593  *
594  * \brief
595  * Determine if this is a link-local IPv6 address
596  *
597  * \warning You should rarely need this function. Only use if you know what
598  * you're doing.
599  *
600  * \retval 1 This is a link-local IPv6 address.
601  * \retval 0 This is link-local IPv6 address.
602  */
603 int ast_sockaddr_is_ipv6_link_local(const struct ast_sockaddr *addr);
604
605 /*!
606  * \since 1.8
607  *
608  * \brief
609  * Determine if this is an IPv6 address
610  *
611  * \warning You should rarely need this function. Only use if you know what
612  * you're doing.
613  *
614  * \retval 1 This is an IPv6 or IPv4-mapped IPv6 address.
615  * \retval 0 This is an IPv4 address.
616  */
617 int ast_sockaddr_is_ipv6(const struct ast_sockaddr *addr);
618
619 /*!
620  * \since 1.8
621  *
622  * \brief
623  * Determine if the address type is unspecified, or "any" address.
624  *
625  * \details
626  * For IPv4, this would be the address 0.0.0.0, and for IPv6,
627  * this would be the address ::. The port number is ignored.
628  *
629  * \retval 1 This is an "any" address
630  * \retval 0 This is not an "any" address
631  */
632 int ast_sockaddr_is_any(const struct ast_sockaddr *addr);
633
634 /*!
635  * \since 1.8
636  *
637  * \brief
638  * Computes a hash value from the address. The port is ignored.
639  *
640  * \retval 0 Unknown address family
641  * \retval other A 32-bit hash derived from the address
642  */
643 int ast_sockaddr_hash(const struct ast_sockaddr *addr);
644
645 /*!
646  * \since 12.3
647  *
648  * \brief
649  * Returns a string representation of an ast_transport
650  *
651  * \retval Name of the tranpsort if it is defined
652  * \retval Undefined if the transport is undefined
653  */
654 const char *ast_transport2str(enum ast_transport transport);
655
656 /*!
657  * \since 1.8
658  *
659  * \brief
660  * Wrapper around accept(2) that uses struct ast_sockaddr.
661  *
662  * \details
663  * For parameter and return information, see the man page for
664  * accept(2).
665  */
666 int ast_accept(int sockfd, struct ast_sockaddr *addr);
667
668 /*!
669  * \since 1.8
670  *
671  * \brief
672  * Wrapper around bind(2) that uses struct ast_sockaddr.
673  *
674  * \details
675  * For parameter and return information, see the man page for
676  * bind(2).
677  */
678 int ast_bind(int sockfd, const struct ast_sockaddr *addr);
679
680 /*!
681  * \since 1.8
682  *
683  * \brief
684  * Wrapper around connect(2) that uses struct ast_sockaddr.
685  *
686  * \details
687  * For parameter and return information, see the man page for
688  * connect(2).
689  */
690 int ast_connect(int sockfd, const struct ast_sockaddr *addr);
691
692 /*!
693  * \since 1.8
694  *
695  * \brief
696  * Wrapper around getsockname(2) that uses struct ast_sockaddr.
697  *
698  * \details
699  * For parameter and return information, see the man page for
700  * getsockname(2).
701  */
702 int ast_getsockname(int sockfd, struct ast_sockaddr *addr);
703
704 /*!
705  * \since 1.8
706  *
707  * \brief
708  * Wrapper around recvfrom(2) that uses struct ast_sockaddr.
709  *
710  * \details
711  * For parameter and return information, see the man page for
712  * recvfrom(2).
713  */
714 ssize_t ast_recvfrom(int sockfd, void *buf, size_t len, int flags,
715                      struct ast_sockaddr *src_addr);
716
717 /*!
718  * \since 1.8
719  *
720  * \brief
721  * Wrapper around sendto(2) that uses ast_sockaddr.
722  *
723  * \details
724  * For parameter and
725  * return information, see the man page for sendto(2)
726  */
727 ssize_t ast_sendto(int sockfd, const void *buf, size_t len, int flags,
728                    const struct ast_sockaddr *dest_addr);
729
730 /*!
731  * \since 1.8
732  *
733  * \brief
734  * Set type of service
735  *
736  * \details
737  * Set ToS ("Type of Service for IPv4 and "Traffic Class for IPv6) and
738  * CoS (Linux's SO_PRIORITY)
739  *
740  * \param sockfd File descriptor for socket on which to set the parameters
741  * \param tos The type of service for the socket
742  * \param cos The cost of service for the socket
743  * \param desc A text description of the socket in question.
744  * \retval 0 Success
745  * \retval -1 Error, with errno set to an appropriate value
746  */
747 int ast_set_qos(int sockfd, int tos, int cos, const char *desc);
748
749 /*!
750  * These are backward compatibility functions that may be used by subsystems
751  * that have not yet been converted to IPv6. They will be removed when all
752  * subsystems are IPv6-ready.
753  */
754 /*@{*/
755
756 /*!
757  * \since 1.8
758  *
759  * \brief
760  * Converts a struct ast_sockaddr to a struct sockaddr_in.
761  *
762  * \param addr The ast_sockaddr to convert
763  * \param[out] sin The resulting sockaddr_in struct
764  * \retval nonzero Success
765  * \retval zero Failure
766  */
767 #define ast_sockaddr_to_sin(addr,sin)   _ast_sockaddr_to_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__)
768 int _ast_sockaddr_to_sin(const struct ast_sockaddr *addr,
769                         struct sockaddr_in *sin, const char *file, int line, const char *func);
770
771 /*!
772  * \since 1.8
773  *
774  * \brief Converts a struct sockaddr_in to a struct ast_sockaddr.
775  *
776  * \param addr
777  * \param sin The sockaddr_in to convert
778  * \return an ast_sockaddr structure
779  */
780 #define ast_sockaddr_from_sin(addr,sin) _ast_sockaddr_from_sin(addr,sin, __FILE__, __LINE__, __PRETTY_FUNCTION__)
781 void _ast_sockaddr_from_sin(struct ast_sockaddr *addr, const struct sockaddr_in *sin,
782                 const char *file, int line, const char *func);
783
784 /*@}*/
785
786 #if defined(__cplusplus) || defined(c_plusplus)
787 }
788 #endif
789
790 #endif /* _ASTERISK_NETSOCK2_H */