SetAddrInfoExA 函式 (ws2tcpip.h)

發行項
03/13/2024

SetAddrInfoEx 函式會向特定命名空間提供者註冊或取消註冊名稱、服務名稱和相關聯的位址。

語法

INT WSAAPI SetAddrInfoExA(
  [in]            PCSTR                              pName,
  [in]            PCSTR                              pServiceName,
  [in, out]       SOCKET_ADDRESS                     *pAddresses,
  [in]            DWORD                              dwAddressCount,
  [in, optional]  LPBLOB                             lpBlob,
  [in]            DWORD                              dwFlags,
  [in]            DWORD                              dwNameSpace,
  [in, optional]  LPGUID                             lpNspId,
  [in, optional]  timeval                            *timeout,
  [in, optional]  LPOVERLAPPED                       lpOverlapped,
  [in, optional]  LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
  [out, optional] LPHANDLE                           lpNameHandle
);

參數

[in] pName

NULL 終止字串的指標，其中包含要註冊或取消註冊地址的名稱。命名空間提供者特有的此參數解譯。

[in] pServiceName

選擇性 NULL 終止字串的指標，其中包含與所註冊之名稱相關聯的服務名稱。此參數的解譯是命名空間提供者特有的。

[in, out] pAddresses

要向命名空間提供者註冊之選擇性位址清單的指標。

[in] dwAddressCount

在 pAddresses 參數中傳遞的位址數目。如果此參數為零， pName 參數會從命名空間提供者取消註冊。

[in, optional] lpBlob

選擇性數據指標，用來設定與地址清單以外的 pName 參數相關聯的提供者特定命名空間資訊。無法在 pAddresses 參數中傳遞的任何資訊，都可以傳入 lpBlob 參數。此資訊的格式專屬於命名空間提供者。

[in] dwFlags

一組旗標，控制 pName 和 pServiceName 參數如何向命名空間提供者註冊。此資訊的解譯是命名空間提供者特有的。

[in] dwNameSpace

命名空間標識碼，決定要向哪個命名空間提供者註冊這項資訊。傳遞特定命名空間識別碼時，只會向支援指定命名空間的命名空間提供者註冊這項資訊。指定NS_ALL會導致向所有已安裝和作用中的命名空間提供者註冊資訊。

dwNameSpace 參數的選項會列在 Winsock2.h 包含檔案中。 Windows Vista 和更新版本包含數個命名空間提供者。您可以安裝其他命名空間提供者，因此只有下列可能的值才可供使用。可能還有其他許多專案。

值	意義
NS_ALL	所有已安裝和作用中的命名空間。
NS_BTH	藍牙命名空間。 Windows Vista 和更新版本支援此命名空間標識碼。
NS_DNS	功能變數名稱系統 (DNS) 命名空間。
NS_EMAIL	電子郵件命名空間。 Windows Vista 和更新版本支援此命名空間標識碼。
NS_NLA	網路位置感知 (NLA) 命名空間。 Windows XP 和更新版本支援此命名空間識別碼。
NS_PNRPNAME	特定對等名稱的點對點命名空間。 Windows Vista 和更新版本支援此命名空間標識碼。
NS_PNRPCLOUD	對等名稱集合的點對點命名空間。 Windows Vista 和更新版本支援此命名空間標識碼。

[in, optional] lpNspId

特定命名空間提供者選擇性 GUID 的指標，可在多個命名空間提供者在單一命名空間下註冊，例如 NS_DNS。傳遞特定命名空間提供者的 GUID 會導致只向指定的命名空間提供者註冊資訊。您可以呼叫 WSAEnumNameSpaceProviders 函式來擷取命名空間提供者的 GUID。

[in, optional] timeout

選擇性參數，指出在中止呼叫之前，等候命名空間提供者的回應，以毫秒為單位。此參數目前是保留的，而且必須設定為 NULL ，因為不支援逾時選項。

[in, optional] lpOverlapped

用於異步操作之重疊結構的選擇性指標。此參數目前是保留的，而且必須設定為 NULL ，因為不支援異步操作。

[in, optional] lpCompletionRoutine

異步操作成功完成時要叫用之函式的選擇性指標。此參數目前是保留的，而且必須設定為 NULL ，因為不支援異步操作。

[out, optional] lpNameHandle

僅用於異步操作的選擇性指標。此參數目前是保留的，而且必須設定為 NULL ，因為不支援異步操作。

傳回值

成功時， SetAddrInfoEx 會傳回 NO_ERROR (0) 。失敗會傳回非零的 Windows Sockets 錯誤碼，如 Windows 套接字錯誤碼中所找到。

錯誤碼	意義
WSANOTINITIALISED	使用此函式之前，必須先進行成功的 WSAStartup 呼叫。
WSATRY_AGAIN	發生名稱解析的暫時失敗。
WSAEINVAL	提供無效的參數。如果任何保留參數不是 NULL，就會傳回此錯誤。
WSAENOBUFS	緩衝區空間不足。
WSANO_RECOVERY	發生無法復原的名稱解析失敗。
WSA_NOT_ENOUGH_MEMORY	發生記憶體配置失敗。

備註

SetAddrInfoEx 函式提供與通訊協議無關的方法，可向命名空間提供者註冊或取消註冊名稱和一或多個位址。 Windows Vista 和更新版本中的NS_EMAIL命名空間提供者支援地址的註冊和取消註冊。默認NS_DNS、NS_PNRPNAME和NS_PNRPNAME命名空間提供者目前不支援名稱註冊。

如果使用 NS_ALL設定為 dwNameSpace 參數和未指定的 lpNspId 參數呼叫 SetAddrInfoEx 函式，則 SetAddrInfoEx 會嘗試向所有已安裝和作用中的命名空間註冊或取消註冊名稱和相關聯的位址。如果任何命名空間提供者成功註冊或取消註冊名稱， 則 SetAddrInfoEx 函式會傳回成功，但不會指出哪個命名空間提供者成功或要求失敗。

定義 UNICODE 或 _UNICODE 時， SetAddrInfoEx 會定義為 SetAddrInfoExW，這是此函式的 Unicode 版本。字串參數會定義為 PWSTR 資料類型。

未定義 UNICODE 或_UNICODE時，SetAddrInfoEx 會定義為 SetAddrInfoExA，這是此函式的 ANSI 版本。字串參數是 PCSTR 資料類型。

透過呼叫 GetAddrInfoEx、 getaddrinfo 或 GetAddrInfoW 函式，即可傳回向命名空間提供者註冊的資訊。 GetAddrInfoEx 函式是 getaddrinfo 和 GetAddrInfoW 函式的增強版本。

在 Windows Vista 和更新版本上，從服務呼叫 SetAddrInfoEx 時，如果作業是呼叫服務的用戶進程結果，則服務應該模擬使用者。這是允許正確強制執行安全性和路由區間。

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

注意

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

規格需求

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