getNameInfoW 函式 (ws2tcpip.h)

發行項
03/13/2024

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 字元數目。呼叫端必須提供足以保存 Unicode 主機名的緩衝區，包括終止 的 NULL 字元。

[out] pServiceBuffer

要保存服務名稱之 Unicode 字串的指標。成功時，指標會傳回 Unicode 字串，代表與埠號碼相關聯的服務名稱。如果 pServiceBuffer 參數為 NULL，這表示呼叫端不想接收服務名稱字串。

[in] ServiceBufferSize

pServiceBuffer 參數指向之緩衝區中的 WCHAR 字元數目。呼叫端必須提供足以保存 Unicode 服務名稱的緩衝區，包括終止 的 NULL 字元。

[in] Flags

值，用來自定義 GetNameInfoW 函式的處理。請參閱＜備註＞一節。

傳回值

成功時， GetNameInfoW 會傳回零。任何非零傳回值都表示失敗，而且呼叫 WSAGetLastError 即可擷取特定的錯誤碼。

GetNameInfoW 函式傳回的非零錯誤碼也會對應至 Internet Engineering Task Force (IETF) 建議中所述的錯誤集。下表顯示這些錯誤碼及其 WSA 對等專案。建議使用 WSA 錯誤碼，因為它們為 Winsock 程式設計人員提供熟悉且完整的錯誤資訊。

錯誤值	WSA 對等專案	Description
EAI_AGAIN	WSATRY_AGAIN	發生名稱解析的暫時失敗。
EAI_BADFLAGS	WSAEINVAL	一或多個無效的參數已傳遞至 GetNameInfoW 函式。如果要求主機名但 NodeBufferSize 參數為零，或要求服務名稱但 ServiceBufferSize 參數為零，則會傳回此錯誤。
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 建議的規範而提供，但不是安全線程。因此，建議使用傳統 Windows Sockets 函式，例如 WSAGetLastError 。

此外，可以傳回下列錯誤碼。

錯誤碼	意義
WSAEFAULT	如果 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 頭檔中的宏會定義 GetNameInfo 的混合大小寫函式名稱，當應用程式以 Service Pack 2 (SP2) 和更新版本 (_WIN32_WINNT >= 0x0502) 為目標時，即可使用。這個 GetNameInfo 函式應該使用 TCHAR 型別指標的 pNodeBuffer 和 pServiceBuffer 參數來呼叫。定義 UNICODE 或_UNICODE時，GetNameInfo 會定義為 Unicode 版本，並使用 char 類型的指標主機和 serv 參數呼叫 GetNameInfoW。未定義 UNICODE 或_UNICODE時，GetNameInfo 會定義為 ANSI 版本，並使用 PWCHAR 型別指標的 pNodeBuffer 和 pServiceBuffer 參數呼叫 getnameinfo。

為了簡化 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 服務提供不同埠號碼的少數服務而言是必要的。

注意使用 GetNameInfoW 函式執行反向 DNS 查閱的功能很方便，但這類查閱原本就不可靠，而且應該只做為提示使用。

注意GetNameInfoW 無法用來解析別名名稱。

Windows Phone 8：Windows Phone 8 和更新版本上的 Windows Phone Store 應用程式支援此函式。

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 標頭會將 GetNameInfo 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 8.1、Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	ws2tcpip.h
程式庫	Ws2_32.lib
Dll	Ws2_32.dll