1/* MIT License
2 *
3 * Copyright (c) 2023 Brad House
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice (including the next
13 * paragraph) shall be included in all copies or substantial portions of the
14 * Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 *
24 * SPDX-License-Identifier: MIT
25 */
26#ifndef __ARES__IFACE_IPS_H
27#define __ARES__IFACE_IPS_H
28
29/*! Flags for interface ip addresses. */
30typedef enum {
31  ARES_IFACE_IP_V4 = 1 << 0,        /*!< IPv4 address. During enumeration if
32                                     *   this flag is set ARES_IFACE_IP_V6
33                                     *   is not, will only enumerate v4
34                                     *   addresses. */
35  ARES_IFACE_IP_V6 = 1 << 1,        /*!< IPv6 address. During enumeration if
36                                     *   this flag is set ARES_IFACE_IP_V4
37                                     *   is not, will only enumerate v6
38                                     *   addresses. */
39  ARES_IFACE_IP_LOOPBACK  = 1 << 2, /*!< Loopback adapter */
40  ARES_IFACE_IP_OFFLINE   = 1 << 3, /*!< Adapter offline */
41  ARES_IFACE_IP_LINKLOCAL = 1 << 4, /*!< Link-local ip address */
42  /*! Default, enumerate all ips for online interfaces, including loopback */
43  ARES_IFACE_IP_DEFAULT = (ARES_IFACE_IP_V4 | ARES_IFACE_IP_V6 |
44                           ARES_IFACE_IP_LOOPBACK | ARES_IFACE_IP_LINKLOCAL)
45} ares__iface_ip_flags_t;
46
47struct ares__iface_ips;
48
49/*! Opaque pointer for holding enumerated interface ip addresses */
50typedef struct ares__iface_ips ares__iface_ips_t;
51
52/*! Destroy ip address enumeration created by ares__iface_ips().
53 *
54 *  \param[in]  ips   Initialized IP address enumeration structure
55 */
56void                           ares__iface_ips_destroy(ares__iface_ips_t *ips);
57
58/*! Enumerate ip addresses on interfaces
59 *
60 *  \param[out]  ips   Returns initialized ip address structure
61 *  \param[in]   flags Flags for enumeration
62 *  \param[in]   name  Interface name to enumerate, or NULL to enumerate all
63 *  \return ARES_ENOMEM on out of memory, ARES_ENOTIMP if not supported on
64 *          the system, ARES_SUCCESS on success
65 */
66ares_status_t                  ares__iface_ips(ares__iface_ips_t    **ips,
67                                               ares__iface_ip_flags_t flags, const char *name);
68
69/*! Count of ips enumerated
70 *
71 * \param[in]  ips   Initialized IP address enumeration structure
72 * \return count
73 */
74size_t      ares__iface_ips_cnt(const ares__iface_ips_t *ips);
75
76/*! Retrieve interface name
77 *
78 * \param[in]  ips   Initialized IP address enumeration structure
79 * \param[in]  idx   Index of entry to pull
80 * \return interface name
81 */
82const char *ares__iface_ips_get_name(const ares__iface_ips_t *ips, size_t idx);
83
84/*! Retrieve interface address
85 *
86 * \param[in]  ips   Initialized IP address enumeration structure
87 * \param[in]  idx   Index of entry to pull
88 * \return interface address
89 */
90const struct ares_addr *ares__iface_ips_get_addr(const ares__iface_ips_t *ips,
91                                                 size_t                   idx);
92
93/*! Retrieve interface address flags
94 *
95 * \param[in]  ips   Initialized IP address enumeration structure
96 * \param[in]  idx   Index of entry to pull
97 * \return interface address flags
98 */
99ares__iface_ip_flags_t  ares__iface_ips_get_flags(const ares__iface_ips_t *ips,
100                                                  size_t                   idx);
101
102/*! Retrieve interface address netmask
103 *
104 * \param[in]  ips   Initialized IP address enumeration structure
105 * \param[in]  idx   Index of entry to pull
106 * \return interface address netmask
107 */
108unsigned char ares__iface_ips_get_netmask(const ares__iface_ips_t *ips,
109                                          size_t                   idx);
110
111/*! Retrieve interface ipv6 link local scope
112 *
113 * \param[in]  ips   Initialized IP address enumeration structure
114 * \param[in]  idx   Index of entry to pull
115 * \return interface ipv6 link local scope
116 */
117unsigned int  ares__iface_ips_get_ll_scope(const ares__iface_ips_t *ips,
118                                           size_t                   idx);
119
120
121/*! Retrieve the interface index (aka link local scope) from the interface
122 *  name.
123 *
124 * \param[in] name  Interface name
125 * \return 0 on failure, index otherwise
126 */
127unsigned int  ares__if_nametoindex(const char *name);
128
129/*! Retrieves the interface name from the index (aka link local scope)
130 *
131 * \param[in] index  Interface index (> 0)
132 * \param[in] name   Buffer to hold name
133 * \param[in] name_len Length of provided buffer, must be at least IF_NAMESIZE
134 * \return NULL on failure, or pointer to name on success
135 */
136const char   *ares__if_indextoname(unsigned int index, char *name,
137                                   size_t name_len);
138
139#endif
140