aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/libs/c-ares/src/lib/util/ares__iface_ips.h
blob: 61ff736a796361165dd624aac490b2fb71ca63a4 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
/* MIT License
 *
 * Copyright (c) 2023 Brad House
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef __ARES__IFACE_IPS_H
#define __ARES__IFACE_IPS_H

/*! Flags for interface ip addresses. */
typedef enum {
  ARES_IFACE_IP_V4 = 1 << 0,        /*!< IPv4 address. During enumeration if
                                     *   this flag is set ARES_IFACE_IP_V6
                                     *   is not, will only enumerate v4
                                     *   addresses. */
  ARES_IFACE_IP_V6 = 1 << 1,        /*!< IPv6 address. During enumeration if
                                     *   this flag is set ARES_IFACE_IP_V4
                                     *   is not, will only enumerate v6
                                     *   addresses. */
  ARES_IFACE_IP_LOOPBACK  = 1 << 2, /*!< Loopback adapter */
  ARES_IFACE_IP_OFFLINE   = 1 << 3, /*!< Adapter offline */
  ARES_IFACE_IP_LINKLOCAL = 1 << 4, /*!< Link-local ip address */
  /*! Default, enumerate all ips for online interfaces, including loopback */
  ARES_IFACE_IP_DEFAULT = (ARES_IFACE_IP_V4 | ARES_IFACE_IP_V6 |
                           ARES_IFACE_IP_LOOPBACK | ARES_IFACE_IP_LINKLOCAL)
} ares__iface_ip_flags_t;

struct ares__iface_ips;

/*! Opaque pointer for holding enumerated interface ip addresses */
typedef struct ares__iface_ips ares__iface_ips_t;

/*! Destroy ip address enumeration created by ares__iface_ips().
 *
 *  \param[in]  ips   Initialized IP address enumeration structure
 */
void                           ares__iface_ips_destroy(ares__iface_ips_t *ips);

/*! Enumerate ip addresses on interfaces
 *
 *  \param[out]  ips   Returns initialized ip address structure
 *  \param[in]   flags Flags for enumeration
 *  \param[in]   name  Interface name to enumerate, or NULL to enumerate all
 *  \return ARES_ENOMEM on out of memory, ARES_ENOTIMP if not supported on
 *          the system, ARES_SUCCESS on success
 */
ares_status_t                  ares__iface_ips(ares__iface_ips_t    **ips,
                                               ares__iface_ip_flags_t flags, const char *name);

/*! Count of ips enumerated
 *
 * \param[in]  ips   Initialized IP address enumeration structure
 * \return count
 */
size_t      ares__iface_ips_cnt(const ares__iface_ips_t *ips);

/*! Retrieve interface name
 *
 * \param[in]  ips   Initialized IP address enumeration structure
 * \param[in]  idx   Index of entry to pull
 * \return interface name
 */
const char *ares__iface_ips_get_name(const ares__iface_ips_t *ips, size_t idx);

/*! Retrieve interface address
 *
 * \param[in]  ips   Initialized IP address enumeration structure
 * \param[in]  idx   Index of entry to pull
 * \return interface address
 */
const struct ares_addr *ares__iface_ips_get_addr(const ares__iface_ips_t *ips,
                                                 size_t                   idx);

/*! Retrieve interface address flags
 *
 * \param[in]  ips   Initialized IP address enumeration structure
 * \param[in]  idx   Index of entry to pull
 * \return interface address flags
 */
ares__iface_ip_flags_t  ares__iface_ips_get_flags(const ares__iface_ips_t *ips,
                                                  size_t                   idx);

/*! Retrieve interface address netmask
 *
 * \param[in]  ips   Initialized IP address enumeration structure
 * \param[in]  idx   Index of entry to pull
 * \return interface address netmask
 */
unsigned char ares__iface_ips_get_netmask(const ares__iface_ips_t *ips,
                                          size_t                   idx);

/*! Retrieve interface ipv6 link local scope
 *
 * \param[in]  ips   Initialized IP address enumeration structure
 * \param[in]  idx   Index of entry to pull
 * \return interface ipv6 link local scope
 */
unsigned int  ares__iface_ips_get_ll_scope(const ares__iface_ips_t *ips,
                                           size_t                   idx);


/*! Retrieve the interface index (aka link local scope) from the interface
 *  name.
 *
 * \param[in] name  Interface name
 * \return 0 on failure, index otherwise
 */
unsigned int  ares__if_nametoindex(const char *name);

/*! Retrieves the interface name from the index (aka link local scope)
 *
 * \param[in] index  Interface index (> 0)
 * \param[in] name   Buffer to hold name
 * \param[in] name_len Length of provided buffer, must be at least IF_NAMESIZE
 * \return NULL on failure, or pointer to name on success
 */
const char   *ares__if_indextoname(unsigned int index, char *name,
                                   size_t name_len);

#endif