getAddressByNameW 函式 (nspapi.h)

  • 發行項

[GetAddressByName 已無法再用於 Windows Sockets 2。 請改用 通訊協定獨立名稱解析中詳述的函式。]

GetAddressByName函式會查詢命名空間或一組預設命名空間，以擷取指定網路服務的網路位址資訊。 此程式稱為服務名稱解析。 網路服務也可以使用 函式來取得可搭配 系結 函式使用的本機位址資訊。

語法

INT GetAddressByNameW(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPWSTR               lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPWSTR               lpAliasBuffer,
  [in, out]      LPDWORD              lpdwAliasBufferLength
);

參數

[in] dwNameSpace

作業系統應該查詢網路位址資訊的命名空間或預設命名空間集合。

使用下列其中一個常數來指定命名空間。

值 意義
NS_DEFAULT
 一組預設命名空間。 函式會查詢此集合中的每個命名空間。 預設命名空間集通常包含系統上安裝的所有命名空間。 不過，系統管理員可以從集合中排除特定命名空間。 這是大部分應用程式應該用於 dwNameSpace的值。
NS_DNS
 網域名稱系統 (在網際網路中用於主機名稱解析的 DNS) 。
NS_NETBT
 透過 TCP/IP 層的 NetBIOS。 所有作業系統都會向 NetBIOS 註冊其電腦名稱稱。 此命名空間用來將電腦名稱稱轉換為使用此註冊的 IP 位址。 請注意，NS_NETBT可以存取 WINS 伺服器來執行解析。
NS_SAP
 NetWare 服務廣告通訊協定。 如有需要，這可以存取 NetWare 系結。 NS_SAP是允許註冊服務的動態命名空間。
NS_TCPIP_HOSTS
 systemroot > \system32\drivers\etc\hosts 檔案中的 < 查閱值。
NS_TCPIP_LOCAL
 本機 TCP/IP 名稱解析機制，包括與本機主機名稱的比較，以及查閱主機與 IP 位址對應快取中的主機名稱和 IP 位址。
 

大部分 對 GetAddressByName 的呼叫都應該使用特殊值NS_DEFAULT。 這可讓用戶端瞭解網際網路上可用的命名空間。 系統管理員決定命名空間存取權。 命名空間可以來回，而不需要用戶端知道變更。

[in] lpServiceType

指定網路服務類型的全域唯一識別碼指標， (GUID) 。 Svcguid.h 標頭檔包含數種 GUID 服務類型的定義，以及用來使用這些類型的宏。

Winsock2.h 標頭檔不會自動包含 Svcguid.h 標頭檔。

[in, optional] lpServiceName

以零結尾字串的指標，可唯一表示服務名稱。 例如，「MY SNA SERVER」。

將 lpServiceName 設定為 Null 相當於將 dwResolution 設定為 RES_SERVICE。 函式會在其第二個模式中運作，取得指定型別的服務應該系結至其中的本機位址。 函式會將本機位址儲存在儲存至 *lpCsaddrBuffer之CSADDR_INFO結構的LocalAddr成員內。

如果 dwResolution 設定為 RES_SERVICE，函式會忽略 lpServiceName 參數。

如果 dwNameSpace 設定為 NS_DNS，*lpServiceName 是主機的名稱。

[in, optional] lpiProtocols

以零結尾的通訊協定識別碼陣列指標。 函式會將名稱解析嘗試限制為提供這些通訊協定的命名空間提供者。 這可讓呼叫端限制搜尋的範圍。

如果 lpiProtocols 設定為 Null，函式會擷取所有可用通訊協定的相關資訊。

[in] dwResolution

一組位旗標，指定服務名稱解析程式的各個層面。 定義下列位旗標。

值 意義
RES_SERVICE
 如果設定，函式會擷取指定型別的服務應該系結的位址。 這相當於將 lpServiceName 參數設定為 Null。

如果這個旗標清楚，就會發生一般名稱解析。
RES_FIND_MULTIPLE
 如果設定此旗標，作業系統會針對服務執行所有命名空間的廣泛搜尋。 它會要求每個適當的命名空間解析服務名稱。 如果此旗標清楚，作業系統會在找到服務位址時立即停止尋找服務位址。
RES_SOFT_SEARCH
 如果命名空間支援多個層級的搜尋，則此旗標有效。

如果此旗標有效並設定，作業系統會執行命名空間的簡單且快速搜尋。 如果應用程式只需要取得服務的容易尋找位址，這非常有用。

如果此旗標有效且清楚，作業系統會執行更廣泛的命名空間搜尋。

[in, optional] lpServiceAsyncInfo

保留供日後使用;必須設定為 Null。

[out] lpCsaddrBuffer

要接收一或多個 CSADDR_INFO 資料結構的緩衝區指標。 寫入緩衝區的結構數目取決於解析嘗試中找到的資訊量。 您應該假設會寫入多個結構，但在許多情況下，只有一個結構。

[in, out] lpdwBufferLength

輸入時，變數的指標會指定 lpCsaddrBuffer所指向緩衝區的大小，以位元組為單位。

輸出時，此變數包含儲存 CSADDR_INFO 結構陣列所需的位元組總數。 如果此值小於或等於 *lpdwBufferLength的輸入值，而且函式成功，則這是實際儲存在緩衝區中的位元組數目。 如果此值大於 *lpdwBufferLength的輸入值，緩衝區太小，而且 *lpdwBufferLength 的輸出值是最少的必要緩衝區大小。

[in, out] lpAliasBuffer

緩衝區的指標，用來接收網路服務的別名資訊。

如果命名空間支援別名，函式會將零終止名稱字串的陣列儲存到 lpAliasBuffer指向的緩衝區中。 清單結尾有雙零結束字元。 陣列中的名字是服務的主要名稱。 後面的名稱是別名。 支援別名的命名空間範例是 DNS。

如果命名空間不支援別名，它會將雙零結束字元儲存至緩衝區。

這個參數是選擇性的，而且可以設定為 Null。

[in, out] lpdwAliasBufferLength

輸入時，變數的指標會指定 lpAliasBuffer所指向緩衝區 (字元) 的大小。

輸出時，此變數包含儲存名稱字串陣列所需的元素總數 (字元數) 。 如果此值小於或等於 *lpdwAliasBufferLength的輸入值，而且函式成功，則這是實際儲存在緩衝區中的元素數目。 如果此值大於 *lpdwAliasBufferLength的輸入值，緩衝區太小，而且 *lpdwAliasBufferLength 的輸出值是最少的必要緩衝區大小。

如果 lpAliasBuffer 為 Null， lpdwAliasBufferLength 是無意義的，也可以是 Null。

傳回值

如果函式成功，傳回值就是寫入lpCsaddrBuffer所指向之緩衝區CSADDR_INFO資料結構的數目。

如果函式失敗，傳回值會SOCKET_ERROR ( –1) 。 若要取得擴充的錯誤資訊，請呼叫 GetLastError，以傳回下列擴充錯誤值。

錯誤碼 意義
ERROR_INSUFFICIENT_BUFFER
 lpCsaddrBuffer指向的緩衝區太小，無法接收所有相關CSADDR_INFO結構。 使用緩衝區至少與 *lpdwBufferLength中傳回的值一樣大呼叫函式。

備註

此函式是 更強大的 gethostbyname 函式版本。 GetAddressByName函式可搭配多個名稱服務使用。

注意gethostbyname函式已被getaddrinfo函式簡介所取代。 建立 Windows Sockets 2 應用程式的開發人員會鼓勵使用 getaddrinfo 函式，而不是 gethostbyname。
 

GetAddressByName函式可讓用戶端取得網路服務的 Windows Sockets 位址。 用戶端會依服務類型和服務名稱來指定感興趣的服務。

許多名稱服務都支援名稱服務提供者在解析服務名稱時所考慮的預設前置詞或尾碼。 例如，在 DNS 命名空間中，如果網域命名為 「nt.microsoft.com」，且提供 「ftp millikan」 作為輸入，則 DNS 軟體無法解析 「millikan」，但已成功解析 「millikan.nt.microsoft.com」。

請注意， GetAddressByName 函式可以透過兩種方式搜尋服務位址：在特定命名空間內，或在一組預設命名空間內。 使用預設命名空間時，系統管理員可以指定只有在名稱指定時，才會搜尋特定命名空間的服務位址。 系統管理員或命名空間—安裝程式也可以控制命名空間搜尋的順序。

注意

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

需求

   
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 nspapi.h
程式庫 Mswsock.lib
Dll Mswsock.dll

另請參閱

CSADDR_INFO

Winsock 函式

Winsock 參考

getaddrinfo

gethostbyname