contrib/bind/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
  51 struct 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
  72 ISC_LANG_BEGINDECLS
  73
  74 isc_result_t
  75 isc_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
  86 isc_result_t
  87 isc_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
  96 isc_result_t
  97 isc_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
 111 isc_result_t
 112 isc_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
 125 void
 126 isc_interfaceiter_destroy(isc_interfaceiter_t **iterp);
 127 /*!<
 128  * \brief Destroy the iterator.
 129  */
 130
 131 ISC_LANG_ENDDECLS
 132
 133 #endif /* ISC_INTERFACEITER_H */