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
IP_INTERFACE_INFO 구조를 수신하기 위해 pIfTable 매개 변수가 가리키는 버퍼의 크기를 지정하는 DWORD 변수에 대한 포인터입니다. 이 크기가 IPv4 인터페이스 정보를 보유하기에 충분하지 않은 경우 GetInterfaceInfo 는 이 변수를 필요한 크기로 채우고 ERROR_INSUFFICIENT_BUFFER 오류 코드를 반환합니다.
반환 값
함수가 성공하면 반환 값이 NO_ERROR.
함수가 실패하면 반환 값은 다음 오류 코드 중 하나입니다.
| 반환 코드 | 설명 |
|---|---|
|
IPv4 어댑터 정보를 받을 버퍼가 너무 작습니다. dwOutBufLen 매개 변수가 pIfTable 매개 변수가 가리키는 버퍼가 너무 작아 IPv4 인터페이스 정보를 검색할 수 없음을 나타내는 경우 이 값이 반환됩니다. 필요한 크기는 dwOutBufLen 매개 변수가 가리키는 DWORD 변수에 반환됩니다. |
|
잘못된 매개 변수가 함수에 전달되었습니다. dwOutBufLen 매개 변수가 NULL이거나 GetInterfaceInfo가 dwOutBufLen 매개 변수가 가리키는 메모리에 쓸 수 없는 경우 이 오류가 반환됩니다. |
|
로컬 시스템에서 IPv4에 대해 사용하도록 설정된 네트워크 어댑터가 없습니다. 로컬 시스템의 모든 네트워크 어댑터가 비활성화된 경우에도 이 값이 반환됩니다. |
|
이 함수는 로컬 시스템에서 사용 중인 운영 체제에서 지원되지 않습니다. |
|
FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다. |
설명
GetInterfaceInfo 함수는 IPv4를 사용하도록 설정된 네트워크 어댑터와 관련이 있습니다. 함수는 로컬 시스템에서 IPv4를 사용하도록 설정된 네트워크 어댑터 수와 IPv4를 사용하도록 설정된 각 네트워크 어댑터에 대한 정보가 있는 IP_ADAPTER_INDEX_MAP 구조의 배열을 포함하는 pIfTable 매개 변수가 가리키는 IP_INTERFACE_INFO구조를 반환합니다. GetInterfaceInfo에서 반환된 IP_INTERFACE_INFO 구조체에는 IP_INTERFACE_INFO 구조체의 NumAdapters 멤버가 IPv4를 사용하는 네트워크 어댑터가 사용하도록 설정되어 있지 않음을 나타내더라도 하나 이상의 IP_ADAPTER_INDEX_MAP 구조체가 포함됩니다. GetInterfaceInfo에서 반환된 IP_INTERFACE_INFO 구조체의 NumAdapters 멤버가 0이면 IP_INTERFACE_INFO 구조체에서 반환된 단일 IP_ADAPTER_INDEX_MAP 구조체의 멤버 값이 정의되지 않습니다.
GetInterfaceInfo 함수가 너무 작은 버퍼로 호출되어 IPv4 인터페이스 정보를 검색하는 경우(dwOutBufLen 매개 변수는 pIfTable 매개 변수가 가리키는 버퍼가 너무 작다는 것을 나타낸다) 함수는 ERROR_INSUFFICIENT_BUFFER 반환합니다. 필요한 크기는 dwOutBufLen 매개 변수가 가리키는 DWORD 변수에 반환됩니다.
GetInterfaceInfo 함수를 사용하는 올바른 방법은 이 함수를 두 번 호출하는 것입니다. 첫 번째 호출에서 pIfTable 매개 변수에 NULL 포인터를 전달하고 dwOutBufLen 매개 변수가 가리키는 변수에 0을 전달합니다. ERROR_INSUFFICIENT_BUFFER 호출이 실패하고 이 버퍼에 필요한 크기가 dwOutBufLen 매개 변수가 가리키는 DWORD 변수에 반환됩니다. 그런 다음 dwOutBufLen이 가리키는 값을 사용하여 필요한 크기의 버퍼를 할당할 수 있습니다. 그런 다음 , GetInterfaceInfo 함수는 pIfTable 매개 변수에 전달된 이 버퍼에 대한 포인터와 이 버퍼의 크기로 설정된 버퍼의 길이를 사용하여 두 번째로 호출할 수 있습니다.
GetAdaptersInfo 및 GetInterfaceInfo 함수는 루프백 인터페이스에 대한 정보를 반환하지 않습니다. 루프백 인터페이스에 대한 정보는 GetIpAddrTable 함수에서 반환됩니다.
Windows Vista 이상에서 IP_INTERFACE_INFO 구조체에 반환된 IP_ADAPTER_INDEX_MAP 구조체의 Name 멤버는 네트워크 인터페이스에 대한 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 |
| 헤더 | iphlpapi.h |
| 라이브러리 | Iphlpapi.lib |
| DLL | Iphlpapi.dll |