Managing Interfaces
A version of this page is also available for
4/8/2010
IP Helper extends your abilities to manage network interfaces. Use the functions described following to manage interfaces on the local computer.
Interfaces are related to adapters in that there is a one-to-one correspondence between the interfaces and adapters on a given computer. An interface is an IP-level abstraction, whereas an adapter is a datalink-level abstraction.
The GetNumberOfInterfaces function returns the number of interfaces on the local computer.
The GetInterfaceInfo function returns a table that contains the names and corresponding indexes for the interfaces on the local computer.
The GetFriendlyIfIndex function takes an interface index and returns a backward-compatible interface index, that is, one that uses only the lower 24 bits. This type of index is sometimes referred to as a friendly interface index.
The GetIfEntry function returns a MIB_IFROW structure that contains information about a particular interface on the local computer. This function requires the caller to supply the index of the interface.
The GetIfTable function returns a table of MIB_IFROW entries, one for each interface on the computer.
Use the SetIfEntry function to modify the configuration of a particular interface.
The following table describes each GetNumberOfInterfaces variable.
| Value | Description |
|---|---|
pdwNumIf |
Pointer to a DWORD variable that, on successful return, contains the number of interfaces on the local computer. |
The following table describes each GetInterfaceInfo variable and IP_INTERFACE_INFO member.
| Value | Description |
|---|---|
pIfTable |
(Read-only) Pointer to a buffer that receives an IP_INTERFACE_INFO structure that contains the list of adapters. This buffer should be allocated by the caller. |
dwOutBufLen |
(Read-only) Pointer to a DWORD variable. If the buffer pointed to by the pIfTable parameter is NULL, or is not large enough to contain the list of adapters, GetInterfaceInfo returns the required size in this DWORD variable. |
IP_INTERFACE_INFO |
NumAdapters Specifies the number of adapters listed in the array pointed to by the Adapter member. Adapter[1] Specifies an array of IP_ADAPTER_INDEX_MAP structures. Each structure maps an adapter index to that adapter's name. |
IP_ADAPTER_INDEX_MAP |
Index Specifies the index of the adapter. Name[MAX_ADAPTER_NAME] Pointer to a Unicode string that contains the name of the adapter. |
The following table describes each GetFriendlyIfIndex variable.
| Value | Description |
|---|---|
IfIndex |
Specifies an interface index from which the backward-compatible or friendly interface index is derived. |
The following table describes each GetIfEntry variable and MIB_IFROW member.
| Value | Description |
|---|---|
pIfRow |
Pointer to a MIB_IFROW structure that, on successful return, contains information for an interface on the local computer. Set the dwIndex member of MIB_IFROW to the index of the interface for which to retrieve information. |
MIB_IFROW (All fields are read-write, and can be changed by the API user with the SetIfEntry function) |
wszName[MAX_INTERFACE_NAME_LEN] Pointer to a Unicode string that contains the name of the interface. dwIndex Specifies the index that identifies the interface. dwType Specifies the type of interface. Common types are: MIB_IF_TYPE_OTHER 1 MIB_IF_TYPE_ETHERNET 6 MIB_IF_TYPE_TOKENRING 9 MIB_IF_TYPE_FDDI 15 MIB_IF_TYPE_PPP 23 MIB_IF_TYPE_LOOPBACK 24 MIB_IF_TYPE_SLIP 28 These types and more are defined in Ipifcons.h. dwMtu Specifies the Maximum Transmission Unit (MTU). dwSpeed Specifies the speed of the interface in bits per second. dwPhysAddrLen Specifies the length of the physical address specified by the bPhysAddr member. bPhysAddr[MAXLEN_PHYSADDR] Specifies the physical address of the adapter for this interface. dwAdminStatus Specifies the interface is administratively enabled or disabled. dwOperStatus Specifies the operational status of the interface. This member can be one of the following values. MIB_IF_OPER_STATUS_NON_OPERATIONAL MIB_IF_OPER_STATUS_UNREACHABLE MIB_IF_OPER_STATUS_DISCONNECTED MIB_IF_OPER_STATUS_CONNECTING MIB_IF_OPER_STATUS_CONNECTED MIB_IF_OPER_STATUS_OPERATIONAL dwLastChange Specifies the last time the operational status changed. (This is not supported in Windows Embedded CE.) dwInOctets Specifies the number of octets of data received through this interface. dwInUcastPkts Specifies the number of unicast packets received through this interface. dwInNUcastPkts Specifies the number of non-unicast packets received through this interface. This includes broadcast and multicast packets. dwInDiscards Specifies the number of incoming packets that were discarded even though they did not have errors. dwInErrors Specifies the number of incoming packets that were discarded because of errors. DwInUnknownProtos Specifies the number of incoming packets that were discarded because the protocol was unknown. dwOutOctets Specifies the number of octets of data sent through this interface. dwOutUcastPkts Specifies the number of unicast packets sent through this interface. dwOutNUcastPkts Specifies the number of non-unicast packets sent through this interface. This includes broadcast and multicast packets. dwOutDiscards Specifies the number of outgoing packets that were discarded even though they did not have errors. dwOutErrors Specifies the number of outgoing packets that were discarded because of errors. dwOutQLen Specifies the output queue length. dwDescrLen Specifies the length of the bDescr member. bDescr[MAXLEN_IFDESCR] Contains a description of the interface. |
The following table describes each GetIfTable variable and MIB_IFTABLE member.
| Value | Description |
|---|---|
pIfTable |
Pointer to a buffer that, on successful return, contains the interface table as a MIB_IFTABLE structure. |
pdwSize |
Specifies the size of the buffer pointed to by the pIfTable parameter. If the buffer is not large enough to hold the returned interface table, the function sets this parameter equal to the required buffer size. |
bOrder |
Specifies whether the returned interface table should be sorted in ascending order by interface index. If this parameter is TRUE, the table is sorted. |
MIB_IFTABLE |
dwNumEntries Specifies the number of interface entries in the array. table[ANY_SIZE] Pointer to a table of interface entries implemented as an array of MIB_IFROW structures. (See GetIfEntry table, above). |
The following table describes each SetIfEntry variable:
| Value | Description |
|---|---|
pIfRow |
Pointer to a MIB_IFROW structure. (See GetIfEntry table, above). The dwIndex member of this structure should specify the interface on which to set administrative status. The dwAdminStatus member specifies the new administrative status. The following list shows the possible values for the dwAdminStatus member:
|