Share via


Managing Interfaces

A version of this page is also available for

Windows Embedded CE 6.0 R3

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:

  • MIB_IF_ADMIN_STATUS_UP indicates the interface is administratively enabled.
  • MIB_IF_ADMIN_STATUS_DOWN indicates the interface is administratively disabled.

See Also

Concepts

Internet Protocol Helper APIs