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

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

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

大部分 對 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

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

[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，以傳回下列擴充錯誤值。

備註

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

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

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

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

需求

另請參閱

CSADDR_INFO

Winsock 函式

Winsock 參考

getaddrinfo

gethostbyname