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 を持つネットワーク アダプターが有効になっていないことを示している場合でも、少なくとも 1 つの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 関数を使用する正しい方法は、この関数を 2 回呼び出すことです。 最初の呼び出しで、pIfTable パラメーターに NULL ポインターを渡し、dwOutBufLen パラメーターが指す変数に 0 を渡します。 呼び出しはERROR_INSUFFICIENT_BUFFERで失敗し、このバッファーに必要なサイズは dwOutBufLen パラメーターによって指される DWORD 変数で返されます。 その後、 dwOutBufLen によって示される値を使用して、必要なサイズのバッファーを割り当てることができます。 次に 、GetInterfaceInfo 関数を 2 回目に呼び出し、 pIfTable パラメーターで渡されたこのバッファーへのポインターと、バッファーの長さをこのバッファーのサイズに設定できます。
GetAdaptersInfo 関数と GetInterfaceInfo 関数は、ループバック インターフェイスに関する情報を返しません。 ループバック インターフェイスに関する情報は、 GetIpAddrTable 関数によって返されます。
Windows Vista 以降では、IP_INTERFACE_INFO構造体で返されるIP_ADAPTER_INDEX_MAP構造体のName メンバーは、ネットワーク インターフェイスの GUID の Unicode 文字列である場合があります (文字列は '{' 文字で始まります)。
例
次の例では、ローカル システムで 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 |
| Library | Iphlpapi.lib |
| [DLL] | Iphlpapi.dll |