interfaceiter.h revision 290001 
1/*
2 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2001  Internet Software Consortium.
4 *
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
16 */
17
18/* $Id: interfaceiter.h,v 1.17 2007/06/19 23:47:18 tbox Exp $ */
19
20#ifndef ISC_INTERFACEITER_H
21#define ISC_INTERFACEITER_H 1
22
23/*****
24 ***** Module Info
25 *****/
26
27/*! \file isc/interfaceiter.h
28 * \brief Iterates over the list of network interfaces.
29 *
30 * Interfaces whose address family is not supported are ignored and never
31 * returned by the iterator.  Interfaces whose netmask, interface flags,
32 * or similar cannot be obtained are also ignored, and the failure is logged.
33 *
34 * Standards:
35 *	The API for scanning varies greatly among operating systems.
36 *	This module attempts to hide the differences.
37 */
38
39/***
40 *** Imports
41 ***/
42
43#include <isc/lang.h>
44#include <isc/netaddr.h>
45#include <isc/types.h>
46
47/*!
48 * \brief Public structure describing a network interface.
49 */
50
51struct isc_interface {
52	char name[32];			/*%< Interface name, null-terminated. */
53	unsigned int af;		/*%< Address family. */
54	isc_netaddr_t address;		/*%< Local address. */
55	isc_netaddr_t netmask;		/*%< Network mask. */
56	isc_netaddr_t broadcast;	/*&< Broadcast address. */
57	isc_netaddr_t dstaddress; 	/*%< Destination address (point-to-point only). */
58	isc_uint32_t flags;		/*%< Flags; see INTERFACE flags. */
59	unsigned int ifindex;		/*%< Interface index for IP(V6)_MULTICAST_IF. */
60};
61
62/*@{*/
63/*! Interface flags. */
64
65#define INTERFACE_F_UP			0x00000001U
66#define INTERFACE_F_POINTTOPOINT	0x00000002U
67#define INTERFACE_F_LOOPBACK		0x00000004U
68#define INTERFACE_F_BROADCAST		0x00000008U
69#define INTERFACE_F_MULTICAST		0x00000010U
70#define INTERFACE_F_PRIVACY		0x00000020U	/* RFC 4941 */
71/*@}*/
72
73/***
74 *** Functions
75 ***/
76
77ISC_LANG_BEGINDECLS
78
79isc_result_t
80isc_interfaceiter_create(isc_mem_t *mctx, isc_interfaceiter_t **iterp);
81/*!<
82 * \brief Create an iterator for traversing the operating system's list
83 * of network interfaces.
84 *
85 * Returns:
86 *\li	#ISC_R_SUCCESS
87 * \li	#ISC_R_NOMEMORY
88 *\li	Various network-related errors
89 */
90
91isc_result_t
92isc_interfaceiter_first(isc_interfaceiter_t *iter);
93/*!<
94 * \brief Position the iterator on the first interface.
95 *
96 * Returns:
97 *\li	#ISC_R_SUCCESS		Success.
98 *\li	#ISC_R_NOMORE		There are no interfaces.
99 */
100
101isc_result_t
102isc_interfaceiter_current(isc_interfaceiter_t *iter,
103			  isc_interface_t *ifdata);
104/*!<
105 * \brief Get information about the interface the iterator is currently
106 * positioned at and store it at *ifdata.
107 *
108 * Requires:
109 *\li 	The iterator has been successfully positioned using
110 * 	isc_interface_iter_first() / isc_interface_iter_next().
111 *
112 * Returns:
113 *\li	#ISC_R_SUCCESS		Success.
114 */
115
116isc_result_t
117isc_interfaceiter_next(isc_interfaceiter_t *iter);
118/*!<
119 * \brief Position the iterator on the next interface.
120 *
121 * Requires:
122 * \li	The iterator has been successfully positioned using
123 * 	isc_interface_iter_first() / isc_interface_iter_next().
124 *
125 * Returns:
126 *\li	#ISC_R_SUCCESS		Success.
127 *\li	#ISC_R_NOMORE		There are no more interfaces.
128 */
129
130void
131isc_interfaceiter_destroy(isc_interfaceiter_t **iterp);
132/*!<
133 * \brief Destroy the iterator.
134 */
135
136ISC_LANG_ENDDECLS
137
138#endif /* ISC_INTERFACEITER_H */
139