GetAddressByNameA 函式 (nspapi.h)

  • 發行項

[GetAddressByName 已不再可供 Windows Sockets 2 使用。 請改用 通訊協議獨立名稱解析中詳述的函式。

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

語法

INT GetAddressByNameA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPSTR                lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPSTR                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 bindery。 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 套接字位址。 用戶端會根據其服務類型和服務名稱來指定感興趣的服務。

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

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

注意

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

規格需求

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

另請參閱

CSADDR_INFO

Winsock 函式

Winsock 參考

getaddrinfo

gethostbyname