GetNameInfoW 関数 (ws2tcpip.h)
GetNameInfoW 関数は、アドレスから Unicode ホスト名、およびポート番号から Unicode サービス名へのプロトコルに依存しない名前解決を提供します。
構文
INT WSAAPI GetNameInfoW(
[in] const SOCKADDR *pSockaddr,
[in] socklen_t SockaddrLength,
[out] PWCHAR pNodeBuffer,
[in] DWORD NodeBufferSize,
[out] PWCHAR pServiceBuffer,
[in] DWORD ServiceBufferSize,
[in] INT Flags
);
パラメーター
[in] pSockaddr
ソケットの IP アドレスとポート番号を含むソケット アドレス構造体へのポインター。 IPv4 の場合、pSockaddr パラメーターはsockaddr_in構造体を指します。 IPv6 の場合、pSockaddr パラメーターはsockaddr_in6構造体を指します。
[in] SockaddrLength
pSockaddr パラメーターが指す構造体の長さ (バイト単位)。
[out] pNodeBuffer
ホスト名を保持する Unicode 文字列へのポインター。 成功すると、Unicode ホスト名へのポインターが既定で完全修飾ドメイン名 (FQDN) として返されます。 pNodeBuffer パラメーターが NULL の場合は、呼び出し元がホスト名文字列を受け取りたくないことを示します。
[in] NodeBufferSize
pNodeBuffer パラメーターが指すバッファー内の WCHAR 文字の数。 呼び出し元は、終端 の NULL 文字を含め、Unicode ホスト名を保持するのに十分な大きさのバッファーを提供する必要があります。
[out] pServiceBuffer
サービス名を保持する Unicode 文字列へのポインター。 成功すると、ポート番号に関連付けられているサービス名を表す Unicode 文字列へのポインターが返されます。 pServiceBuffer パラメーターが NULL の場合、呼び出し元がサービス名の文字列を受け取りたくないことを示します。
[in] ServiceBufferSize
pServiceBuffer パラメーターが指すバッファー内の WCHAR 文字の数。 呼び出し元は、終端 の NULL 文字を含め、Unicode サービス名を保持するのに十分な大きさのバッファーを提供する必要があります。
[in] Flags
GetNameInfoW 関数の処理をカスタマイズするために使用される値。 「解説」を参照してください。
戻り値
成功すると、 GetNameInfoW は 0 を返します。 0 以外の戻り値はエラーを示し、 WSAGetLastError を呼び出すことで特定のエラー コードを取得できます。
GetNameInfoW 関数によって返される 0 以外のエラー コードも、インターネット エンジニアリング タスク フォース (IETF) の推奨事項で概説されている一連のエラーにマップされます。 次の表に、これらのエラー コードとその WSA に相当するエラー コードを示します。 WSA エラー コードは、Winsock プログラマにとって使い慣れた包括的なエラー情報を提供するため、使用することをお勧めします。
| エラー値 | WSA と同等 | 説明 |
|---|---|---|
| EAI_AGAIN | WSATRY_AGAIN | 名前解決で一時的なエラーが発生しました。 |
| EAI_BADFLAGS | WSAEINVAL | 1 つ以上の無効なパラメーターが GetNameInfoW 関数に渡されました。 このエラーは、ホスト名が要求されたが NodeBufferSize パラメーターが 0 であった場合、またはサービス名が要求されたが ServiceBufferSize パラメーターが 0 の場合に返されます。 |
| EAI_FAIL | WSANO_RECOVERY | 名前解決で回復不可能なエラーが発生しました。 |
| EAI_FAMILY | WSAEAFNOSUPPORT | pSockaddr パラメーターが指すソケット アドレス構造のsa_family メンバーはサポートされていません。 |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | メモリ割り当てエラーが発生しました。 |
| EAI_NONAME | WSAHOST_NOT_FOUND | サービス名が要求されましたが、 pSockaddr パラメーターが指す構造体にポート番号が見つからなかったか、ポート番号と一致するサービス名が見つかりませんでした。 NI_NAMEREQDが設定され、ホストの名前が見つからないか、pNodeBuffer パラメーターと pServiceBuffer パラメーターの両方が NULL でした。 |
gai_strerror関数を使用すると、GetNameInfoW 関数によって返される EAI コードに基づいてエラー メッセージを出力できます。 gai_strerror関数は IETF の推奨事項に準拠するために提供されますが、スレッド セーフではありません。 そのため、 WSAGetLastError などの従来の Windows ソケット関数を使用することをお勧めします。
さらに、次のエラー コードを返すことができます。
| エラー コード | 意味 |
|---|---|
| このエラーは、 pSockaddr パラメーターが NULL であるか 、SockaddrLength パラメーターが IPv4 の sockaddr_in 構造体のサイズまたは IPv6 の sockaddr_in6 構造体に必要な長さより短い場合に返されます。 |
注釈
GetNameInfoW 関数は、プロトコルに依存しない名前解決を提供する Unicode バージョンの関数です。 GetNameInfoW 関数は、ソケット アドレス構造の内容をノード名またはサービス名に変換するために使用されます。
IPv6 および IPv4 プロトコルの場合、名前解決には、ドメイン ネーム システム (DNS)、ローカル ホスト ファイル、またはその他の名前付けメカニズムを使用できます。 この関数を使用して、IPv4 または IPv6 アドレスのホスト名、逆引き DNS 参照、またはポート番号のサービス名を決定できます。 GetNameInfoW 関数を使用して、SOCKADDR 構造体の IP アドレスまたはポート番号を Unicode 文字列に変換することもできます。 この関数を使用して、ホスト名の IP アドレスを決定することもできます。
この関数の ANSI バージョンは getnameinfo です。
Winsock ヘッダー ファイルのマクロは、アプリケーションが Service Pack 2 (SP2) 以降 (_WIN32_WINNT >= 0x0502) を使用する Windows XP を対象としている場合に使用できる、GetNameInfo の大文字と小文字が混在する関数名を定義します。 この GetNameInfo 関数は、TCHAR 型のポインターの pNodeBuffer パラメーターと pServiceBuffer パラメーターを使用して呼び出す必要があります。 UNICODE または_UNICODEが定義されている場合、GetNameInfo は Unicode バージョンに定義され、GetNameInfoW は char 型のポインターの host パラメーターと serv パラメーターを使用して呼び出されます。 UNICODE または_UNICODEが定義されていない場合、GetNameInfo は ANSI バージョンに定義され、getnameinfo は PWCHAR 型のポインターの pNodeBuffer パラメーターと pServiceBuffer パラメーターを使用して呼び出されます。
pNodeBuffer パラメーターと pServiceBuffer パラメーターのバッファー要件の決定を簡略化するために、Ws2tcpip.h ヘッダー ファイルには、ホスト名の最大長と最大サービス名に関する次の値が定義されています。
#include <windows.h>
#define NI_MAXSERV 32
#define NI_MAXHOST 1025
Flags パラメーターを使用して、GetNameInfoW 関数の処理をカスタマイズできます。 次のフラグを使用できます。
- NI_NOFQDN
- NI_NUMERICHOST
- NI_NAMEREQD
- NI_NUMERICSERV
- NI_DGRAM
NI_NAMEREQD フラグを設定すると、DNS で解決できないホスト名がエラーになります。
NI_NOFQDN フラグを設定すると、ローカル ホストの相対識別名 (RDN) のみが pNodeBuffer パラメーターで返されます。
NI_NUMERICHOST フラグを設定すると、ホスト名の名前ではなく数値形式が返されます。 ホスト名を DNS で解決できない場合は、ホスト名の数値形式も返されます。
NI_NUMERICSERV フラグを設定すると、サービスの名前ではなくポート番号が返されます。 また、IP アドレス (127.0.0.2 など) のホスト名が見つからない場合は、ホスト名が IP アドレスとして返されます。
Windows Vista 以降では、flags パラメーターにNI_NUMERICSERVが指定されておらず、sa パラメーターが指す sockaddr 構造体に含まれるポート番号が既知のサービスに解決されない場合、GetNameInfoW 関数はサービス アドレス (ポート番号) の数値形式を数値文字列として返します。 NI_NUMERICSERVを指定すると、ポート番号が数値文字列として返されます。 この動作は、RFC 3493 のセクション 6.2 で指定されています。 詳細については、「www.ietf.org/rfc/rfc3493.txt」を参照してください。
Windows Server 2003 以前では、flags パラメーターにNI_NUMERICSERVが指定されておらず、sa パラメーターが指す sockaddr 構造体に含まれるポート番号が既知のサービスに解決されない場合、GetNameInfoW 関数は失敗します。 NI_NUMERICSERVを指定すると、ポート番号が数値文字列として返されます。
NI_DGRAM フラグを設定すると、サービスがデータグラム サービスであることを示します。 このフラグは、UDP および TCP サービスに異なるポート番号を提供する少数のサービスに必要です。
Windows Phone 8: この関数は、Windows Phone 8 以降の Windows Phone ストア アプリでサポートされています。
Windows 8.1とWindows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストア アプリでサポートされています。
コード例
次の例では、 GetNameInfoW 関数の使用方法を示します。#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
DWORD dwRetval;
struct sockaddr_in saGNI;
WCHAR hostname[NI_MAXHOST];
WCHAR servInfo[NI_MAXSERV];
u_short port = 27015;
// Validate the parameters
if (argc != 2) {
wprintf(L"usage: %s IPv4 address\n", argv[0]);
wprintf(L" to return hostname\n");
wprintf(L" %s 127.0.0.1\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
wprintf(L"WSAStartup failed: %d\n", iResult);
return 1;
}
//-----------------------------------------
// Set up sockaddr_in structure which is passed
// to the getnameinfo function
saGNI.sin_family = AF_INET;
saGNI.sin_addr.s_addr = inet_addr(argv[1]);
saGNI.sin_port = htons(port);
//-----------------------------------------
// Call GetNameInfoW
dwRetval = GetNameInfoW((struct sockaddr *) &saGNI,
sizeof (struct sockaddr),
hostname,
NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);
if (dwRetval != 0) {
wprintf(L"GetNameInfoW failed with error # %ld\n", WSAGetLastError());
return 1;
} else {
wprintf(L"GetNameInfoW returned hostname = %ws\n", hostname);
return 0;
}
}
注意
ws2tcpip.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして GetNameInfo を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8.1、 Windows Vista [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | ws2tcpip.h |
| Library | Ws2_32.lib |
| [DLL] | Ws2_32.dll |