GetIfEntry-Funktion (iphlpapi.h)
Die GetIfEntry-Funktion ruft Informationen für die angegebene Schnittstelle auf dem lokalen Computer ab.
Syntax
IPHLPAPI_DLL_LINKAGE DWORD GetIfEntry(
[in, out] PMIB_IFROW pIfRow
);
Parameter
[in, out] pIfRow
Ein Zeiger auf eine MIB_IFROW Struktur, die bei erfolgreicher Rückgabe Informationen für eine Schnittstelle auf dem lokalen Computer empfängt. Legen Sie bei der Eingabe den dwIndex-Member von MIB_IFROW auf den Index der Schnittstelle fest, für die Informationen abgerufen werden sollen. Der Wert für dwIndex muss durch einen vorherigen Aufruf der Funktion GetIfTable, GetIfTable2 oder GetIfTable2Ex abgerufen werden.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.
| Rückgabecode | Beschreibung |
|---|---|
|
Die Anforderung konnte nicht abgeschlossen werden. Dies ist ein interner Fehler. |
|
Ungültige Daten. Dieser Fehler wird zurückgegeben, wenn der Netzwerkschnittstellenindex, der vom dwIndex-Member der MIB_IFROW Struktur angegeben wird, auf die der pIfRow-Parameter verweist, kein gültiger Schnittstellenindex auf dem lokalen Computer ist. |
|
Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn ein NULL-Zeiger im pIfRow-Parameter übergeben wird. |
|
Die angegebene Schnittstelle konnte nicht gefunden werden. Dieser Fehler wird zurückgegeben, wenn der netzwerkschnittstellenindex, der vom dwIndex-Element der MIB_IFROW-Struktur angegeben wurde, auf die der pIfRow-Parameter verweist, nicht gefunden werden konnte. |
|
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn IPv4 auf dem lokalen Computer nicht konfiguriert ist. |
|
Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Die GetIfEntry-Funktion ruft Informationen für eine Schnittstelle auf einem lokalen Computer ab.
Der dwIndex-Member in der MIB_IFROW Struktur, auf die der pIfRow-Parameter verweist, muss in einem gültigen Netzwerkschnittstellenindex initialisiert werden, der durch einen vorherigen Aufruf der GetIfTable-, GetIfTable2- oder GetIfTable2Ex-Funktion abgerufen wurde.
Die GetIfEntry-Funktion schlägt fehl, wenn der dwIndex-Member des MIB_IFROW , auf den der pIfRow-Parameter verweist, nicht mit einem vorhandenen Schnittstellenindex auf dem lokalen Computer übereinstimmt.
Beispiele
Im folgenden Beispiel werden die Einträge aus der Schnittstellentabelle abgerufen und einige der für diesen Eintrag verfügbaren Informationen ausgegeben.
#include <winsock2.h>
#include <ws2tcpip.h>
#pragma comment(lib, "IPHLPAPI.lib")
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>
#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
/* Note: could also use malloc() and free() */
int main()
{
// Declare and initialize variables.
// Declare and initialize variables.
DWORD dwSize = 0;
DWORD dwRetVal = 0;
unsigned int i, j;
/* variables used for GetIfTable and GetIfEntry */
MIB_IFTABLE *pIfTable;
MIB_IFROW *pIfRow;
// Allocate memory for our pointers.
pIfTable = (MIB_IFTABLE *) MALLOC(sizeof (MIB_IFTABLE));
if (pIfTable == NULL) {
printf("Error allocating memory needed to call GetIfTable\n");
exit (1);
}
// Before calling GetIfEntry, we call GetIfTable to make
// sure there are entries to get and retrieve the interface index.
// Make an initial call to GetIfTable to get the
// necessary size into dwSize
dwSize = sizeof (MIB_IFTABLE);
if (GetIfTable(pIfTable, &dwSize, 0) == ERROR_INSUFFICIENT_BUFFER) {
FREE(pIfTable);
pIfTable = (MIB_IFTABLE *) MALLOC(dwSize);
if (pIfTable == NULL) {
printf("Error allocating memory\n");
exit (1);
}
}
// Make a second call to GetIfTable to get the actual
// data we want.
if ((dwRetVal = GetIfTable(pIfTable, &dwSize, 0)) == NO_ERROR) {
if (pIfTable->dwNumEntries > 0) {
pIfRow = (MIB_IFROW *) MALLOC(sizeof (MIB_IFROW));
if (pIfRow == NULL) {
printf("Error allocating memory\n");
if (pIfTable != NULL) {
FREE(pIfTable);
pIfTable = NULL;
}
exit (1);
}
printf("\tNum Entries: %ld\n\n", pIfTable->dwNumEntries);
for (i = 0; i < pIfTable->dwNumEntries; i++) {
pIfRow->dwIndex = pIfTable->table[i].dwIndex;
if ((dwRetVal = GetIfEntry(pIfRow)) == NO_ERROR) {
printf("\tIndex:\t %ld\n", pIfRow->dwIndex);
printf("\tInterfaceName[%d]:\t ", i);
if (pIfRow->wszName != NULL)
printf("%ws", pIfRow->wszName);
printf("\n");
printf("\tDescription[%d]:\t ", i);
for (j = 0; j < pIfRow->dwDescrLen; j++)
printf("%c", pIfRow->bDescr[j]);
printf("\n");
printf("\tIndex[%d]:\t\t %d\n", i, pIfRow->dwIndex);
printf("\tType[%d]:\t\t ", i);
switch (pIfRow->dwType) {
case IF_TYPE_OTHER:
printf("Other\n");
break;
case IF_TYPE_ETHERNET_CSMACD:
printf("Ethernet\n");
break;
case IF_TYPE_ISO88025_TOKENRING:
printf("Token Ring\n");
break;
case IF_TYPE_PPP:
printf("PPP\n");
break;
case IF_TYPE_SOFTWARE_LOOPBACK:
printf("Software Lookback\n");
break;
case IF_TYPE_ATM:
printf("ATM\n");
break;
case IF_TYPE_IEEE80211:
printf("IEEE 802.11 Wireless\n");
break;
case IF_TYPE_TUNNEL:
printf("Tunnel type encapsulation\n");
break;
case IF_TYPE_IEEE1394:
printf("IEEE 1394 Firewire\n");
break;
default:
printf("Unknown type %ld\n", pIfRow->dwType);
break;
}
printf("\tMtu[%d]:\t\t %ld\n", i, pIfRow->dwMtu);
printf("\tSpeed[%d]:\t\t %ld\n", i, pIfRow->dwSpeed);
printf("\tPhysical Addr:\t\t ");
if (pIfRow->dwPhysAddrLen == 0)
printf("\n");
// for (j = 0; j < (int) pIfRow->dwPhysAddrLen; j++) {
for (j = 0; j < pIfRow->dwPhysAddrLen; j++) {
if (j == (pIfRow->dwPhysAddrLen - 1))
printf("%.2X\n", (int) pIfRow->bPhysAddr[j]);
else
printf("%.2X-", (int) pIfRow->bPhysAddr[j]);
}
printf("\tAdmin Status[%d]:\t %ld\n", i,
pIfRow->dwAdminStatus);
printf("\tOper Status[%d]:\t ", i);
switch (pIfRow->dwOperStatus) {
case IF_OPER_STATUS_NON_OPERATIONAL:
printf("Non Operational\n");
break;
case IF_OPER_STATUS_UNREACHABLE:
printf("Unreasonable\n");
break;
case IF_OPER_STATUS_DISCONNECTED:
printf("Disconnected\n");
break;
case IF_OPER_STATUS_CONNECTING:
printf("Connecting\n");
break;
case IF_OPER_STATUS_CONNECTED:
printf("Connected\n");
break;
case IF_OPER_STATUS_OPERATIONAL:
printf("Operational\n");
break;
default:
printf("Unknown status %ld\n",
pIfRow->dwOperStatus);
break;
}
printf("\n");
}
else {
printf("GetIfEntry failed for index %d with error: %ld\n",
i, dwRetVal);
// Here you can use FormatMessage to find out why
// it failed.
}
}
} else {
printf("\tGetIfTable failed with error: %ld\n", dwRetVal);
}
}
exit (0);
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | iphlpapi.h |
| Bibliothek | Iphlpapi.lib |
| DLL | Iphlpapi.dll |
Weitere Informationen
SetIfEntry