getnameinfo

関数

ソケットアドレスからホスト名とサービス名へ逆解決する。

DLLWS2_32.dll呼出規約winapiSetLastErrorあり対応OSWindows 8.1 以降

シグネチャ

// WS2_32.dll
#include <windows.h>

INT getnameinfo(
    const SOCKADDR* pSockaddr,
    socklen_t SockaddrLength,
    LPSTR pNodeBuffer,   // optional
    DWORD NodeBufferSize,
    LPSTR pServiceBuffer,   // optional
    DWORD ServiceBufferSize,
    INT Flags
);

パラメーター

名前	型	方向	説明
pSockaddr	SOCKADDR*	in	ソケットのアドレスとポート番号を格納したソケットアドレス構造体へのポインターです。IPv4 の場合、sa パラメーターは sockaddr_in 構造体を指します。IPv6 の場合、sa パラメーターは sockaddr_in6 構造体を指します。
SockaddrLength	socklen_t	in	sa パラメーターが指す構造体の長さ(バイト単位)です。
pNodeBuffer	LPSTR	outoptional	ホスト名を格納するために使用される ANSI 文字列へのポインターです。成功した場合、既定ではホスト名は完全修飾ドメイン名 (FQDN) として返されます。host パラメーターが NULL の場合、呼び出し側がホスト名文字列の受け取りを希望しないことを示します。
NodeBufferSize	DWORD	in	host パラメーターが指すバッファーの長さ(バイト単位)です。呼び出し側は、終端の NULL 文字を含めてホスト名を格納できる十分な大きさのバッファーを用意する必要があります。
pServiceBuffer	LPSTR	outoptional	サービス名を格納するための ANSI 文字列へのポインターです。成功した場合、ポート番号に関連付けられたサービス名を表す ANSI 文字列が返されます。serv パラメーターが NULL の場合、呼び出し側がサービス名文字列の受け取りを希望しないことを示します。
ServiceBufferSize	DWORD	in	serv パラメーターが指すバッファーの長さ(バイト単位)です。呼び出し側は、終端の NULL 文字を含めてサービス名を格納できる十分な大きさのバッファーを用意する必要があります。
Flags	INT	in	getnameinfo 関数の処理をカスタマイズするために使用する値です。「解説」セクションを参照してください。

戻り値の型: INT

公式ドキュメント

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

戻り値

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

getnameinfo 関数が返す 0 以外のエラーコードは、Internet Engineering Task Force (IETF) の勧告で定められた一連のエラーにも対応しています。次の表に、これらのエラーコードとそれに対応する WSA の同等コードを示します。WSA エラーコードは Winsock プログラマーにとってなじみがあり包括的なエラー情報を提供するため、WSA エラーコードの使用が推奨されます。

エラー値	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 が設定されていてホスト名を特定できない場合、または host パラメーターと serv パラメーターの両方が NULL であった場合に返されます。

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

さらに、次のエラーコードが返される場合があります。

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

解説(Remarks)

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

IPv6 および IPv4 プロトコルでは、名前解決はドメインネームシステム (DNS)、ローカルの hosts ファイル、またはその他の名前付けメカニズムによって行われます。この関数は、IPv4 または IPv6 アドレスのホスト名を特定する(逆引き DNS 検索)、あるいはポート番号のサービス名を特定するために使用できます。getnameinfo 関数は、sockaddr 構造体内の IP アドレスやポート番号を ANSI 文字列に変換するためにも使用できます。また、この関数はホスト名から IP アドレスを特定するためにも使用できます。

getnameinfo 関数の別名として GetNameInfoA を使用できます。Ws2tcpip.h ヘッダーファイル内のマクロにより、GetNameInfoA は getnameinfo として定義されています。

Windows XP Service Pack 2 (SP2) 以降で利用可能なこの関数の Unicode バージョンは GetNameInfoW です。

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

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

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

flags パラメーターは、 getnameinfo 関数の処理をカスタマイズするために使用できます。次のフラグが利用できます。

NI_NAMEREQD フラグが設定されている場合、DNS で解決できないホスト名はエラーになります。

NI_NOFQDN フラグを設定すると、ローカルホストについては host パラメーターにその相対識別名 (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 インライン関数として定義されます。実行時には、Ws2_32.dll または Wship6.dll(Windows 2000 向け IPv6 Technology Preview で getnameinfo を含むファイル)が getnameinfo を含んでいない場合に、Wspiapi.h ヘッダーファイル内のコードに基づいて getnameinfo のバージョンがインラインで実装されるように、WspiapiGetNameInfo 関数が実装されます。このインラインコードは、getnameinfo 関数をネイティブにサポートしていない古い Windows プラットフォームで使用されます。

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

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

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

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// WS2_32.dll
#include <windows.h>

INT getnameinfo(
    const SOCKADDR* pSockaddr,
    socklen_t SockaddrLength,
    LPSTR pNodeBuffer,   // optional
    DWORD NodeBufferSize,
    LPSTR pServiceBuffer,   // optional
    DWORD ServiceBufferSize,
    INT Flags
);

[DllImport("WS2_32.dll", SetLastError = true, ExactSpelling = true)]
static extern int getnameinfo(
    IntPtr pSockaddr,   // SOCKADDR*
    int SockaddrLength,   // socklen_t
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pNodeBuffer,   // LPSTR optional, out
    uint NodeBufferSize,   // DWORD
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pServiceBuffer,   // LPSTR optional, out
    uint ServiceBufferSize,   // DWORD
    int Flags   // INT
);

<DllImport("WS2_32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function getnameinfo(
    pSockaddr As IntPtr,   ' SOCKADDR*
    SockaddrLength As Integer,   ' socklen_t
    <MarshalAs(UnmanagedType.LPStr)> pNodeBuffer As System.Text.StringBuilder,   ' LPSTR optional, out
    NodeBufferSize As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPStr)> pServiceBuffer As System.Text.StringBuilder,   ' LPSTR optional, out
    ServiceBufferSize As UInteger,   ' DWORD
    Flags As Integer   ' INT
) As Integer
End Function

' pSockaddr : SOCKADDR*
' SockaddrLength : socklen_t
' pNodeBuffer : LPSTR optional, out
' NodeBufferSize : DWORD
' pServiceBuffer : LPSTR optional, out
' ServiceBufferSize : DWORD
' Flags : INT
Declare PtrSafe Function getnameinfo Lib "ws2_32" ( _
    ByVal pSockaddr As LongPtr, _
    ByVal SockaddrLength As Long, _
    ByVal pNodeBuffer As String, _
    ByVal NodeBufferSize As Long, _
    ByVal pServiceBuffer As String, _
    ByVal ServiceBufferSize As Long, _
    ByVal Flags As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

getnameinfo = ctypes.windll.ws2_32.getnameinfo
getnameinfo.restype = ctypes.c_int
getnameinfo.argtypes = [
    ctypes.c_void_p,  # pSockaddr : SOCKADDR*
    ctypes.c_int,  # SockaddrLength : socklen_t
    wintypes.LPSTR,  # pNodeBuffer : LPSTR optional, out
    wintypes.DWORD,  # NodeBufferSize : DWORD
    wintypes.LPSTR,  # pServiceBuffer : LPSTR optional, out
    wintypes.DWORD,  # ServiceBufferSize : DWORD
    ctypes.c_int,  # Flags : INT
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WS2_32.dll')
getnameinfo = Fiddle::Function.new(
  lib['getnameinfo'],
  [
    Fiddle::TYPE_VOIDP,  # pSockaddr : SOCKADDR*
    Fiddle::TYPE_INT,  # SockaddrLength : socklen_t
    Fiddle::TYPE_VOIDP,  # pNodeBuffer : LPSTR optional, out
    -Fiddle::TYPE_INT,  # NodeBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # pServiceBuffer : LPSTR optional, out
    -Fiddle::TYPE_INT,  # ServiceBufferSize : DWORD
    Fiddle::TYPE_INT,  # Flags : INT
  ],
  Fiddle::TYPE_INT)

#[link(name = "ws2_32")]
extern "system" {
    fn getnameinfo(
        pSockaddr: *const SOCKADDR,  // SOCKADDR*
        SockaddrLength: i32,  // socklen_t
        pNodeBuffer: *mut u8,  // LPSTR optional, out
        NodeBufferSize: u32,  // DWORD
        pServiceBuffer: *mut u8,  // LPSTR optional, out
        ServiceBufferSize: u32,  // DWORD
        Flags: i32  // INT
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WS2_32.dll", SetLastError = true)]
public static extern int getnameinfo(IntPtr pSockaddr, int SockaddrLength, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pNodeBuffer, uint NodeBufferSize, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pServiceBuffer, uint ServiceBufferSize, int Flags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WS2_32_getnameinfo' -Namespace Win32 -PassThru
# $api::getnameinfo(pSockaddr, SockaddrLength, pNodeBuffer, NodeBufferSize, pServiceBuffer, ServiceBufferSize, Flags)

#uselib "WS2_32.dll"
#func global getnameinfo "getnameinfo" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; getnameinfo varptr(pSockaddr), SockaddrLength, varptr(pNodeBuffer), NodeBufferSize, varptr(pServiceBuffer), ServiceBufferSize, Flags   ; 戻り値は stat
; pSockaddr : SOCKADDR* -> "sptr"
; SockaddrLength : socklen_t -> "sptr"
; pNodeBuffer : LPSTR optional, out -> "sptr"
; NodeBufferSize : DWORD -> "sptr"
; pServiceBuffer : LPSTR optional, out -> "sptr"
; ServiceBufferSize : DWORD -> "sptr"
; Flags : INT -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WS2_32.dll"
#cfunc global getnameinfo "getnameinfo" var, int, var, int, var, int, int
; res = getnameinfo(pSockaddr, SockaddrLength, pNodeBuffer, NodeBufferSize, pServiceBuffer, ServiceBufferSize, Flags)
; pSockaddr : SOCKADDR* -> "var"
; SockaddrLength : socklen_t -> "int"
; pNodeBuffer : LPSTR optional, out -> "var"
; NodeBufferSize : DWORD -> "int"
; pServiceBuffer : LPSTR optional, out -> "var"
; ServiceBufferSize : DWORD -> "int"
; Flags : INT -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WS2_32.dll"
#cfunc global getnameinfo "getnameinfo" sptr, int, sptr, int, sptr, int, int
; res = getnameinfo(varptr(pSockaddr), SockaddrLength, varptr(pNodeBuffer), NodeBufferSize, varptr(pServiceBuffer), ServiceBufferSize, Flags)
; pSockaddr : SOCKADDR* -> "sptr"
; SockaddrLength : socklen_t -> "int"
; pNodeBuffer : LPSTR optional, out -> "sptr"
; NodeBufferSize : DWORD -> "int"
; pServiceBuffer : LPSTR optional, out -> "sptr"
; ServiceBufferSize : DWORD -> "int"
; Flags : INT -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。