dlls/iphlpapi/ifenum.h

   1 /* ifenum.h
   2  * Copyright (C) 2003,2006 Juan Lang
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  17  *
  18  * This module implements network interface and address enumeration.  It's
  19  * meant to hide some problematic defines like socket(), and make iphlpapi
  20  * more portable.
  21  *
  22  * Like Windows, it uses a numeric index to identify an interface uniquely.
  23  * As implemented, an interface represents a UNIX network interface, virtual
  24  * or real, and thus can have 0 or 1 IP addresses associated with it.  (This
  25  * only supports IPv4.)
  26  * The indexes returned are not guaranteed to be contiguous, so don't call
  27  * getNumInterfaces() and assume the values [0,getNumInterfaces() - 1] will be
  28  * valid indexes; use getInterfaceIndexTable() instead.
  29  *
  30  * See also the companion file, ipstats.h, for functions related to getting
  31  * statistics.
  32  */
  33 #ifndef WINE_IFENUM_H_
  34 #define WINE_IFENUM_H_
  35
  36 #include <stdarg.h>
  37
  38 #include "windef.h"
  39 #include "winbase.h"
  40 #define USE_WS_PREFIX
  41 #include "iprtrmib.h"
  42 #include "winsock2.h"
  43
  44 #define MAX_INTERFACE_PHYSADDR    8
  45 #define MAX_INTERFACE_DESCRIPTION 256
  46
  47 DWORD getNumInterfaces(void) DECLSPEC_HIDDEN;
  48 DWORD getNumNonLoopbackInterfaces(void) DECLSPEC_HIDDEN;
  49 BOOL isIfIndexLoopback(ULONG idx) DECLSPEC_HIDDEN;
  50
  51 /* A table of interface indexes, see get*InterfaceTable(). */
  52 typedef struct _InterfaceIndexTable {
  53   DWORD numIndexes;
  54   IF_INDEX indexes[1];
  55 } InterfaceIndexTable;
  56
  57 /* Returns a table with all known interface indexes, or NULL if one could not
  58  * be allocated.  HeapFree() the returned table.
  59  */
  60 InterfaceIndexTable *getInterfaceIndexTable(void) DECLSPEC_HIDDEN;
  61
  62 /* Like getInterfaceIndexTable, but filters out loopback interfaces. */
  63 InterfaceIndexTable *getNonLoopbackInterfaceIndexTable(void) DECLSPEC_HIDDEN;
  64
  65 /* ByName/ByIndex versions of various getter functions. */
  66
  67 /* can be used as quick check to see if you've got a valid index, returns NULL
  68  * if not.  Overwrites your buffer, which should be at least of size
  69  * MAX_ADAPTER_NAME.
  70  */
  71 char *getInterfaceNameByIndex(IF_INDEX index, char *name) DECLSPEC_HIDDEN;
  72
  73 /* Fills index with the index of name, if found.  Returns
  74  * ERROR_INVALID_PARAMETER if name or index is NULL, ERROR_INVALID_DATA if name
  75  * is not found, and NO_ERROR on success.
  76  */
  77 DWORD getInterfaceIndexByName(const char *name, IF_INDEX *index) DECLSPEC_HIDDEN;
  78
  79 /* Gets a few physical characteristics of a device:  MAC addr len, MAC addr,
  80  * and type as one of the MIB_IF_TYPEs.
  81  * len's in-out: on in, needs to say how many bytes are available in addr,
  82  * which to be safe should be MAX_INTERFACE_PHYSADDR.  On out, it's how many
  83  * bytes were set, or how many were required if addr isn't big enough.
  84  * Returns ERROR_INVALID_PARAMETER if name, len, addr, or type is NULL.
  85  * Returns ERROR_INVALID_DATA if name/index isn't valid.
  86  * Returns ERROR_INSUFFICIENT_BUFFER if addr isn't large enough for the
  87  * physical address; *len will contain the required size.
  88  * May return other errors, e.g. ERROR_OUTOFMEMORY or ERROR_NO_MORE_FILES,
  89  * if internal errors occur.
  90  * Returns NO_ERROR on success.
  91  */
  92 DWORD getInterfacePhysicalByIndex(IF_INDEX index, PDWORD len, PBYTE addr,
  93  PDWORD type) DECLSPEC_HIDDEN;
  94
  95 /* Fills in the MIB_IFROW by name.  Doesn't fill in interface statistics,
  96  * see ipstats.h for that.
  97  * Returns ERROR_INVALID_PARAMETER if name is NULL, ERROR_INVALID_DATA
  98  * if name isn't valid, and NO_ERROR otherwise.
  99  */
 100 DWORD getInterfaceEntryByName(const char *name, PMIB_IFROW entry) DECLSPEC_HIDDEN;
 101
 102 DWORD getNumIPAddresses(void) DECLSPEC_HIDDEN;
 103
 104 /* Gets the configured IP addresses for the system, and sets *ppIpAddrTable to
 105  * a table of them allocated from heap, or NULL if out of memory.  Returns
 106  * NO_ERROR on success, something else on failure.  Note there may be more than
 107  * one IP address may exist per interface.
 108  */
 109 DWORD getIPAddrTable(PMIB_IPADDRTABLE *ppIpAddrTable, HANDLE heap, DWORD flags) DECLSPEC_HIDDEN;
 110
 111 /* Returns the IPv6 addresses for a particular interface index.
 112  * Returns NO_ERROR on success, something else on failure.
 113  */
 114 ULONG v6addressesFromIndex(IF_INDEX index, SOCKET_ADDRESS **addrs, ULONG *num_addrs) DECLSPEC_HIDDEN;
 115
 116 /* Converts the network-order bytes in addr to a printable string.  Returns
 117  * string.
 118  */
 119 char *toIPAddressString(unsigned int addr, char string[16]) DECLSPEC_HIDDEN;
 120
 121 DWORD getInterfaceMtuByName(const char *name, PDWORD mtu) DECLSPEC_HIDDEN;
 122 DWORD getInterfaceStatusByName(const char *name, INTERNAL_IF_OPER_STATUS *status) DECLSPEC_HIDDEN;
 123
 124 #endif /* ndef WINE_IFENUM_H_ */