Функция GetInterfaceInfo (iphlpapi.h)
Функция GetInterfaceInfo получает список сетевых адаптеров с включенным протоколом IPv4 в локальной системе.
Синтаксис
IPHLPAPI_DLL_LINKAGE DWORD GetInterfaceInfo(
[out] PIP_INTERFACE_INFO pIfTable,
[in, out] PULONG dwOutBufLen
);
Параметры
[out] pIfTable
Указатель на буфер, указывающий IP_INTERFACE_INFO структуру, получающую список адаптеров. Этот буфер должен быть выделен вызывающим объектом.
[in, out] dwOutBufLen
Указатель на переменную DWORD , указывающую размер буфера, на который указывает параметр pIfTable для получения структуры IP_INTERFACE_INFO . Если этого размера недостаточно для хранения сведений об интерфейсе IPv4, GetInterfaceInfo заполняет эту переменную требуемым размером и возвращает код ошибки ERROR_INSUFFICIENT_BUFFER.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет NO_ERROR.
Если функция завершается сбоем, возвращается один из следующих кодов ошибок.
| Код возврата | Описание |
|---|---|
|
Буфер для получения сведений об адаптере IPv4 слишком мал. Это значение возвращается, если параметр dwOutBufLen указывает, что буфер, на который указывает параметр pIfTable, слишком мал для получения сведений об интерфейсе IPv4. Требуемый размер возвращается в переменной DWORD , на которую указывает параметр dwOutBufLen . |
|
В функцию передан недопустимый параметр. Эта ошибка возвращается, если параметр dwOutBufLen имеет значение NULL или GetInterfaceInfo не может выполнить запись в память, на которую указывает параметр dwOutBufLen . |
|
В локальной системе не включены сетевые адаптеры для протокола IPv4. Это значение также возвращается, если отключены все сетевые адаптеры в локальной системе. |
|
Эта функция не поддерживается в операционной системе, используемой в локальной системе. |
|
Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки. |
Комментарии
Функция GetInterfaceInfo зависит от сетевых адаптеров с включенным протоколом IPv4. Функция возвращает структуру IP_INTERFACE_INFO , на которую указывает параметр pIfTable , который содержит число сетевых адаптеров с включенным протоколом IPv4 в локальной системе и массив IP_ADAPTER_INDEX_MAP структур с информацией о каждом сетевом адаптере с включенным протоколом IPv4. Структура IP_INTERFACE_INFO , возвращаемая GetInterfaceInfo , содержит по крайней мере одну структуру IP_ADAPTER_INDEX_MAP , даже если элемент NumAdaptersструктуры IP_INTERFACE_INFO указывает, что сетевые адаптеры с IPv4 не включены. Если элемент NumAdaptersструктуры IP_INTERFACE_INFO , возвращаемой GetInterfaceInfo , равен нулю, значение членов одной структуры IP_ADAPTER_INDEX_MAP , возвращаемое в структуре IP_INTERFACE_INFO , не определено.
Если функция GetInterfaceInfo вызывается с слишком маленьким буфером для получения сведений об интерфейсе IPv4 (параметр dwOutBufLen указывает, что буфер, на который указывает параметр pIfTable , слишком мал), функция возвращает ERROR_INSUFFICIENT_BUFFER. Требуемый размер возвращается в переменной DWORD , на которую указывает параметр dwOutBufLen .
Правильный способ использовать функцию GetInterfaceInfo — вызвать эту функцию дважды. В первом вызове передайте указатель NULL в параметре pIfTable и ноль в переменную, на которую указывает параметр dwOutBufLen . Вызов завершится ошибкой с ERROR_INSUFFICIENT_BUFFER и требуемый размер для этого буфера возвращается в переменной DWORD , на которую указывает параметр dwOutBufLen . Затем можно выделить буфер требуемого размера, используя значение, указанное dwOutBufLen. Затем функцию GetInterfaceInfo можно вызвать во второй раз с указателем на этот буфер, переданным в параметре pIfTable , а длина буфера устанавливается в соответствии с размером этого буфера.
Функции GetAdaptersInfo и GetInterfaceInfo не возвращают сведения об интерфейсе замыкания на себя. Сведения об интерфейсе замыкания на себя возвращаются функцией GetIpAddrTable .
В Windows Vista и более поздних версиях элемент nameструктуры IP_ADAPTER_INDEX_MAP , возвращаемый в структуре IP_INTERFACE_INFO , может быть строкой Юникода GUID для сетевого интерфейса (строка начинается с символа "{").
Примеры
В следующем примере извлекается список сетевых адаптеров с включенным протоколом IPv4 в локальной системе и выводится различные свойства первого сетевого адаптера.
#include <winsock2.h>
#include <ws2ipdef.h>
#include <iphlpapi.h>
#include <stdio.h>
#pragma comment(lib, "iphlpapi.lib")
#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
PIP_INTERFACE_INFO pInfo = NULL;
ULONG ulOutBufLen = 0;
DWORD dwRetVal = 0;
int iReturn = 1;
int i;
// Make an initial call to GetInterfaceInfo to get
// the necessary size in the ulOutBufLen variable
dwRetVal = GetInterfaceInfo(NULL, &ulOutBufLen);
if (dwRetVal == ERROR_INSUFFICIENT_BUFFER) {
pInfo = (IP_INTERFACE_INFO *) MALLOC(ulOutBufLen);
if (pInfo == NULL) {
printf
("Unable to allocate memory needed to call GetInterfaceInfo\n");
return 1;
}
}
// Make a second call to GetInterfaceInfo to get
// the actual data we need
dwRetVal = GetInterfaceInfo(pInfo, &ulOutBufLen);
if (dwRetVal == NO_ERROR) {
printf("Number of Adapters: %ld\n\n", pInfo->NumAdapters);
for (i = 0; i < pInfo->NumAdapters; i++) {
printf("Adapter Index[%d]: %ld\n", i,
pInfo->Adapter[i].Index);
printf("Adapter Name[%d]: %ws\n\n", i,
pInfo->Adapter[i].Name);
}
iReturn = 0;
} else if (dwRetVal == ERROR_NO_DATA) {
printf
("There are no network adapters with IPv4 enabled on the local system\n");
iReturn = 0;
} else {
printf("GetInterfaceInfo failed with error: %d\n", dwRetVal);
iReturn = 1;
}
FREE(pInfo);
return (iReturn);
}
Требования
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | iphlpapi.h |
| Библиотека | Iphlpapi.lib |
| DLL | Iphlpapi.dll |
См. также раздел
Справочник по вспомогательной функции IP