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