getnameinfo 関数 (ws2tcpip.h)

  • [アーティクル]

getnameinfo 関数は、アドレスから ANSI ホスト名、およびポート番号から ANSI サービス名へのプロトコルに依存しない名前解決を提供します。

構文

INT WSAAPI getnameinfo(
  [in]  const SOCKADDR *pSockaddr,
  [in]  socklen_t      SockaddrLength,
  [out] PCHAR          pNodeBuffer,
  [in]  DWORD          NodeBufferSize,
  [out] PCHAR          pServiceBuffer,
  [in]  DWORD          ServiceBufferSize,
  [in]  INT            Flags
);

パラメーター

[in] pSockaddr

ソケットのアドレスとポート番号を含むソケット アドレス構造体へのポインター。 IPv4 の場合、 sa パラメーターは sockaddr_in 構造体を指します。 IPv6 の場合、 sa パラメーターは sockaddr_in6 構造体を指します。

[in] SockaddrLength

sa パラメーターが指す構造体の長さ (バイト単位)。

[out] pNodeBuffer

ホスト名を保持するために使用される ANSI 文字列へのポインター。 成功すると、ホスト名は既定で完全修飾ドメイン名 (FQDN) として返されます。 ホスト パラメーターが NULL の場合は、呼び出し元がホスト名の文字列を受け取りたくないことを示します。

[in] NodeBufferSize

ホスト パラメーターが指すバッファーの長さ (バイト単位)。 呼び出し元は、ホスト名を保持するのに十分な大きさのバッファー (終端の NULL 文字を含む) を提供する必要があります。

[out] pServiceBuffer

サービス名を保持する ANSI 文字列へのポインター。 成功すると、ポート番号に関連付けられているサービス名を表す ANSI 文字列が返されます。 serv パラメーターが NULL の場合、呼び出し元がサービス名の文字列を受け取りたくないことを示します。

[in] ServiceBufferSize

serv パラメーターが指すバッファーの長さ (バイト単位)。 呼び出し元は、サービス名を保持するのに十分な大きさのバッファー (終端の NULL 文字を含む) を 提供する必要があります。

[in] Flags

getnameinfo 関数の処理をカスタマイズするために使用される 値。 「解説」を参照してください。

戻り値

成功すると、 getnameinfo は 0 を返します。 0 以外の戻り値はエラーを示し、 WSAGetLastError を呼び出すことで特定のエラー コードを取得できます。

getnameinfo 関数によって返される 0 以外のエラー コードも、インターネット エンジニアリング タスク フォース (IETF) の推奨事項で説明されている一連のエラーにマップされます。 次の表に、これらのエラー コードとその WSA と同等のエラー コードを示します。 WSA エラー コードは、Winsock プログラマにとって使い慣れた包括的なエラー情報を提供するため、使用することをお勧めします。

エラー値 WSA と同等 説明
EAI_AGAIN WSATRY_AGAIN 名前解決で一時的なエラーが発生しました。
EAI_BADFLAGS WSAEINVAL 1 つ以上の無効なパラメーターが getnameinfo 関数に渡されました。 このエラーは、ホスト名が要求されたが hostlen パラメーターが 0 であった場合、またはサービス名が要求されたが 、servlen パラメーターが 0 の場合に返されます。
EAI_FAIL WSANO_RECOVERY 名前解決で回復できないエラーが発生しました。
EAI_FAMILY WSAEAFNOSUPPORT sa パラメーターによって指されるソケット・アドレス構造のsa_familyメンバーはサポートされていません。
EAI_MEMORY WSA_NOT_ENOUGH_MEMORY メモリ割り当てエラーが発生しました。
EAI_NONAME WSAHOST_NOT_FOUND サービス名が要求されましたが、 sa パラメーターが指す構造体にポート番号が見つからなかったか、ポート番号と一致するサービス名が見つかりませんでした。 NI_NAMEREQDが設定され、ホスト名が見つからないか、 ホスト と serv の両方のパラメーターが NULL でした。
 

getnameinfo 関数によって返される EAI コードに基づいてエラー メッセージを出力するには、gai_strerror関数を使用します。 gai_strerror関数は IETF の推奨事項に準拠するために提供されますが、スレッド セーフではありません。 そのため、 WSAGetLastError などの従来の Windows ソケット関数を使用することをお勧めします。

さらに、次のエラー コードを返すことができます。

エラー コード 意味
WSAEFAULT
 sa パラメーターが NULL であるか、salen パラメーターが IPv4 の構造体または IPv6 のsockaddr_in6構造体のサイズsockaddr_in必要な長さより短い場合、このエラーが返されます。

注釈

getnameinfo 関数は、プロトコルに依存しない名前解決を提供する関数の ANSI バージョンです。 getnameinfo 関数は、ソケット アドレス構造の内容をノード名またはサービス名に変換するために使用されます。

IPv6 および IPv4 プロトコルの場合、名前解決はドメイン ネーム システム (DNS)、ローカル ホスト ファイル、またはその他の名前付けメカニズムによって行うことができます。 この関数を使用して、IPv4 または IPv6 アドレスのホスト名、逆引き DNS 参照、またはポート番号のサービス名を決定できます。 getnameinfo 関数を使用して、sockaddr 構造体の IP アドレスまたはポート番号を ANSI 文字列に変換することもできます。 この関数を使用して、ホスト名の IP アドレスを決定することもできます。

getnameinfo 関数に使用できるもう 1 つの名前は、GetNameInfoA です。 Ws2tcpip.h ヘッダー ファイル内のマクロでは、GetNameInfoA を getnameinfo に定義します。

Windows XP Service Pack 2 (SP2) 以降で使用できるこの関数の Unicode バージョンは 、GetNameInfoW です。

Winsock ヘッダー ファイル内のマクロは、アプリケーションが SP2 以降の Windows XP を対象としている場合に使用できる GetNameInfo の大文字と小文字が混在する関数名を定義します (_WIN32_WINNT >= 0x0502)。 この GetNameInfo 関数は、TCHAR 型のポインターの host パラメーターと serv パラメーターを使用して呼び出す必要があります。 UNICODE または_UNICODEが定義されていない場合、GetNameInfo は ANSI バージョンに対して定義され、getnameinfo は char 型のポインターの host パラメーターと serv パラメーターを使用して呼び出されます。 UNICODE または_UNICODEが定義されている場合、GetNameInfo は Unicode バージョンに定義され、GetNameInfoW は PWCHAR 型のポインターの pNodeBuffer パラメーターと pServiceBuffer パラメーターを使用して呼び出されます。

ホストおよび serv パラメーターのバッファー要件の決定を簡単にするために、最大ホスト名の長さと最大サービス名に関する次の値が Ws2tcpip.h ヘッダー ファイルで定義されています。

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

flags パラメーターを使用して、getnameinfo 関数の処理をカスタマイズできます。 次のフラグを使用できます。

  • NI_NOFQDN
  • NI_NUMERICHOST
  • NI_NAMEREQD
  • NI_NUMERICSERV
  • NI_DGRAM

NI_NAMEREQD フラグを設定すると、DNS で解決できないホスト名がエラーになります。

NI_NOFQDN フラグを設定すると、ローカル ホストの相対識別名 (RDN) のみがホスト パラメーターに返されます。

NI_NUMERICHOST フラグを設定すると、ホスト名の名前ではなく、数値形式のホスト名が返されます。 ホスト名を DNS で解決できない場合は、ホスト名の数値形式も返されます。

NI_NUMERICSERV フラグを設定すると、名前ではなくサービスのポート番号が返されます。 また、IP アドレス (127.0.0.2 など) のホスト名が見つからない場合は、ホスト名が IP アドレスとして返されます。

Windows Vista 以降では、flags パラメーターにNI_NUMERICSERVが指定されておらず、sa パラメーターが指す sockaddr 構造体に含まれるポート番号が既知のサービスに解決されない場合、getnameinfo 関数はサービス アドレス (ポート番号) の数値形式を数値文字列として返します。 NI_NUMERICSERVを指定すると、ポート番号が数値文字列として返されます。 この動作は、RFC 3493 のセクション 6.2 で指定されています。 詳細については、「www.ietf.org/rfc3493.txt」を参照してください 。

Windows Server 2003 以前では、flags パラメーターにNI_NUMERICSERVが指定されておらず、sa パラメーターが指す sockaddr 構造体に含まれるポート番号が既知のサービスに解決されない場合、getnameinfo 関数は失敗します。 NI_NUMERICSERVを指定すると、ポート番号が数値文字列として返されます。

NI_DGRAM フラグを設定すると、サービスがデータグラム サービスであることを示します。 このフラグは、UDP および TCP サービスに異なるポート番号を提供する少数のサービスに必要です。

メモgetnameinfo 関数を使用して逆引き DNS 参照を実行する機能は便利ですが、このような参照は本質的に信頼性が低いと見なされ、ヒントとしてのみ使用する必要があります。
 
メモgetnameinfo 関数を使用して別名を解決することはできません。
 

コード例

次のコード例は 、getnameinfo 関数の使用方法を示しています。 
#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 = {0};
    int iResult = 0;

    DWORD dwRetval;

    struct sockaddr_in saGNI;
    char hostname[NI_MAXHOST];
    char servInfo[NI_MAXSERV];
    u_short port = 27015;

    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s IPv4 address\n", argv[0]);
        printf("  to return hostname\n");
        printf("       %s 127.0.0.1\n", argv[0]);
        return 1;
    }
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("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 getnameinfo
    dwRetval = getnameinfo((struct sockaddr *) &saGNI,
                           sizeof (struct sockaddr),
                           hostname,
                           NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);

    if (dwRetval != 0) {
        printf("getnameinfo failed with error # %ld\n", WSAGetLastError());
        return 1;
    } else {
        printf("getnameinfo returned hostname = %s\n", hostname);
        return 0;
    }
}

以前のバージョンの Windows での getnameinfo のサポート

getnameinfo 関数は、Windows XP 以降の Ws2_32.dll に追加されました。 以前のバージョンの Windows (Windows 2000、Windows NT、Windows Me/98/95) でこの関数を使用してアプリケーションを実行する場合は、Ws2tcpip.h ファイルを含め、Wspiapi.h ファイルも含める必要があります。 Wspiapi.h インクルード ファイルを追加すると、getnameinfo 関数は Wspiapi.h ファイルの WspiapiGetNameInfo インライン関数に定義されます。 実行時に、WspiapiGetNameInfo 関数は、Ws2_32.dll または Wship6.dll (Windows 2000 の IPv6 テクノロジ プレビューの getnameinfo を含むファイル) に getnameinfo が含まれていない場合に、Wspiapi.h ヘッダー ファイル内のコードに基づいて getnameinfo のバージョンがインラインで実装されるように実装されます。 このインライン コードは、 getnameinfo 関数をネイティブにサポートしていない古い Windows プラットフォームで使用されます。

Windows 2000 用 IPv6 テクノロジ プレビューがインストールされている場合、Windows 2000 では IPv6 プロトコルがサポートされます。 それ以外の場合、Windows XP より前のバージョンの Windows での getnameinfo のサポートは、IPv4 名前解決の処理に限定されます。

GetNameInfoW 関数は、getnameinfo の Unicode バージョンです。 GetNameInfoW 関数は、SP2 を使用した Windows XP の Ws2_32.dll に追加されました。 GetNameInfoW 関数は、SP2 を使用する Windows XP より前のバージョンの Windows では使用できません。

Windows Phone 8: この関数は、Windows Phone 8 以降のWindows Phone ストア アプリでサポートされています。

Windows 8.1とWindows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストア アプリでサポートされています。

要件

要件 値
サポートされている最小のクライアント Windows 8.1、 Windows Vista [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー ws2tcpip.h
Library Ws2_32.lib
[DLL] Ws2_32.dll

こちらもご覧ください

GetNameInfoW

WSAGetLastError

Winsock 関数

Winsock リファレンス

gai_strerror

getaddrinfo

Sockaddr