共用方式為

GetHostNameW 函式 (winsock2.h)

  • 發行項

GetHostNameW函式會將本機電腦的標準主機名稱擷取為 Unicode 字串。

語法

int WSAAPI GetHostNameW(
  [out] PWSTR name,
  [in]  int   namelen
);

參數

[out] name

緩衝區的指標，接收本機主機名稱做為 Null終止的 Unicode 字串。

[in] namelen

name參數所指向之緩衝區的長度，以寬字元為單位。

傳回值

如果沒有發生錯誤， GetHostNameW 會傳回零。 否則，它會傳回 SOCKET_ERROR ，而且可以藉由呼叫 WSAGetLastError來擷取特定的錯誤碼。

錯誤碼 意義
WSAEFAULT
 name參數是Null指標，或不是使用者位址空間的有效部分。 如果 namelen 參數指定的緩衝區大小太小而無法保存完整主機名稱，也會傳回此錯誤。
WSANOTINITIALISED
 使用此函式之前，必須先進行成功的 WSAStartup 呼叫。
WSAENETDOWN
 網路子系統失敗。

備註

GetHostNameW函式會將本機主機的名稱傳回 Unicode (UTF-16) 中名稱參數所指定的緩衝區。 主機名稱會以 Null終止的 Unicode 字串傳回。 主機名稱的格式取決於 Windows Sockets 提供者，它可以是簡單的主機名稱，也可以是完整功能變數名稱。 不過，保證傳回的名稱將會由 GetAddrInfoW成功剖析。

隨著網際網路的成長，需要識別 ASCII 字元集未表示之其他語言的網際網路主機名稱。 有助於此需求的識別碼，並允許 Unicode (Unicode) 的非 ASCII 字元以特殊 ASCII 字元字串表示， (Punycode) 稱為國際化功能變數名稱 (IDN) 。 在應用程式 (IDNA) 中將功能變數名稱國際化的機制，可用來以標準方式處理 IDN。 GetHostNameW函式不會轉換 Punycode 與 Unicode 之間的本機主機名稱。 GetAddrInfoW函式支援國際化功能變數名稱 (IDN) 剖析和執行 Punycode/IDN 編碼和轉換。

如果在 Windows Server 2012 上的叢集資源上使用 GetHostNameW 函式，且 已定義CLUSTER_NETWORK_NAME 環境變數，則此環境變數中的值會覆寫實際的主機名稱並傳回。 在叢集資源上， CLUSTER_NETWORK_NAME 環境變數包含叢集的名稱。

GetHostNameW函式會查詢命名空間提供者，以使用Svgguid.h標頭檔中定義的SVCID_HOSTNAME GUID 來判斷本機主機名稱。 如果沒有命名空間提供者回應， GetHostNameW 函式會傳回 Unicode 中本機電腦的 NetBIOS 名稱。

name參數所指向之緩衝區中所傳回字串的最大長度，以寬字元為單位，取決於命名空間提供者，但此字串必須是 256 個寬字元或更少。 因此，如果在 name 參數中傳遞 256 寬字元的緩衝區， 且 namelen 參數設定為 256，則緩衝區大小一律會足夠。

注意 如果未設定本機主機名稱， GetHostNameW 必須成功，並傳回 GetAddrInfoW 可以解析的權杖主機名稱。
 

Windows Phone 8：Windows Phone 8 和更新版本Windows Phone市集應用程式支援此函式。

Windows 8.1和Windows Server 2012 R2：Windows 市集應用程式支援此功能，Windows 8.1、Windows Server 2012 R2 及更新版本。

規格需求

   
最低支援的用戶端 Windows 8.1，Windows 8 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2012 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 winsock2.h
程式庫 Ws2_32.lib
Dll Ws2_32.dll

另請參閱

GetAddrInfoW

Winsock 函式

Winsock 參考

gethostname