/contrib/bind9/lib/isc/include/isc/interfaceiter.h

  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 dstaddress; 	/*%< Destination address (point-to-point only). */
 57	isc_uint32_t flags;		/*%< Flags; see INTERFACE flags. */
 58};
 59
 60/*@{*/
 61/*! Interface flags. */
 62
 63#define INTERFACE_F_UP			0x00000001U
 64#define INTERFACE_F_POINTTOPOINT	0x00000002U
 65#define INTERFACE_F_LOOPBACK		0x00000004U
 66/*@}*/
 67
 68/***
 69 *** Functions
 70 ***/
 71
 72ISC_LANG_BEGINDECLS
 73
 74isc_result_t
 75isc_interfaceiter_create(isc_mem_t *mctx, isc_interfaceiter_t **iterp);
 76/*!<
 77 * \brief Create an iterator for traversing the operating system's list
 78 * of network interfaces.
 79 *
 80 * Returns:
 81 *\li	#ISC_R_SUCCESS
 82 * \li	#ISC_R_NOMEMORY
 83 *\li	Various network-related errors
 84 */
 85
 86isc_result_t
 87isc_interfaceiter_first(isc_interfaceiter_t *iter);
 88/*!<
 89 * \brief Position the iterator on the first interface.
 90 *
 91 * Returns:
 92 *\li	#ISC_R_SUCCESS		Success.
 93 *\li	#ISC_R_NOMORE		There are no interfaces.
 94 */
 95
 96isc_result_t
 97isc_interfaceiter_current(isc_interfaceiter_t *iter,
 98			  isc_interface_t *ifdata);
 99/*!<
100 * \brief Get information about the interface the iterator is currently
101 * positioned at and store it at *ifdata.
102 *
103 * Requires:
104 *\li 	The iterator has been successfully positioned using
105 * 	isc_interface_iter_first() / isc_interface_iter_next().
106 *
107 * Returns:
108 *\li	#ISC_R_SUCCESS		Success.
109 */
110
111isc_result_t
112isc_interfaceiter_next(isc_interfaceiter_t *iter);
113/*!<
114 * \brief Position the iterator on the next interface.
115 *
116 * Requires:
117 * \li	The iterator has been successfully positioned using
118 * 	isc_interface_iter_first() / isc_interface_iter_next().
119 *
120 * Returns:
121 *\li	#ISC_R_SUCCESS		Success.
122 *\li	#ISC_R_NOMORE		There are no more interfaces.
123 */
124
125void
126isc_interfaceiter_destroy(isc_interfaceiter_t **iterp);
127/*!<
128 * \brief Destroy the iterator.
129 */
130
131ISC_LANG_ENDDECLS
132
133#endif /* ISC_INTERFACEITER_H */