WSASetServiceA 函式 (winsock2.h)

發行項
03/04/2024

WSASetService 函式會在登錄中註冊或移除一或多個命名空間內的服務實例。

語法

INT WSAAPI WSASetServiceA(
  [in] LPWSAQUERYSETA   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

參數

[in] lpqsRegInfo

註冊或取消註冊之服務資訊的指標。

[in] essoperation

值，決定所要求的作業。此參數可以是 Winsock2.h 頭檔中所定義 WSAESETSERVICEOP 列舉類型的其中一個值。

值	意義
RNRSERVICE_REGISTER	註冊服務。對於 SAP，這表示傳送定期廣播。這是 DNS 命名空間的 NOP。對於永續性數據存放區，這表示更新地址資訊。
RNRSERVICE_DEREGISTER	從登錄中移除服務。針對 SAP，這表示停止傳送定期廣播。這是 DNS 命名空間的 NOP。對於永續性數據存放區，這表示刪除地址資訊。
RNRSERVICE_DELETE	從動態名稱和永續性空格中刪除服務。對於使用 SERVICE_MULTIPLE 旗標) (多個 CSADDR_INFO 結構所代表的服務，只會刪除指定的位址，而且這必須與註冊服務時所指定的對應 CSADDR_INFO 結構完全相符。

[in] dwControlFlags

服務安裝旗標值，進一步控制 WSASetService 函式執行的作業。此參數的可能值定義在 Winsock2.h 頭檔中。

旗標	意義
SERVICE_MULTIPLE	控制作業的範圍。未設定此旗標時，服務位址會以群組的形式管理。在新增指定的位址集之前，登錄中的緩存器或移除會使所有現有的位址失效。設定時，動作只會在指定的位址集上執行。緩存器不會使現有位址失效，而且從登錄中移除只會使指定的位址集失效。

傳回值

如果作業成功， WSASetService 的傳回值為零。否則，會傳回SOCKET_ERROR值，並呼叫 WSAGetLastError 來擷取特定的錯誤號碼。

錯誤碼	意義
WSAEACCES	呼叫例程沒有足夠的許可權可安裝服務。
WSAEINVAL	一或多個必要參數無效或遺失。
WSANOTINITIALISED	尚未初始化 Ws2_32.dll 。應用程式必須先呼叫 WSAStartup ，再呼叫任何 Windows Sockets 函式。
WSA_NOT_ENOUGH_MEMORY	記憶體不足，無法執行作業。

備註

WSASetService 函式可用來影響特定命名空間提供者、與特定命名空間相關聯的所有提供者，或所有命名空間的所有提供者。

essOperation 和 dwControlFlags 的可用值會結合以控制 WSASetService 函式的作業，如下表所示。

作業	Flags	服務已經存在	服務不存在
RNRSERVICE_REGISTER	無	覆寫物件。只使用指定的位址。物件為 REGISTERED。	建立新的物件。只使用指定的位址。物件為 REGISTERED。
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	更新物件。將新的位址新增至現有的集合。物件為 REGISTERED。	建立新的物件。使用指定的所有位址。物件為 REGISTERED。
RNRSERVICE_DEREGISTER	無	拿掉所有位址，但不會從命名空間中移除物件。物件會從登錄中移除。	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	更新物件。只移除指定的位址。只有在沒有位址存在時，才會將對象標示為 DEREGISTERED。不會從命名空間中移除物件。	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	無	從命名空間中移除物件。	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	只移除指定的位址。只有在沒有任何位址保留時，才會從命名空間中移除物件。	WSASERVICE_NOT_FOUND

根據訪問控制清單 (ACL) ，將服務發佈至目錄，例如 Active Directory 服務。如需詳細資訊，請參閱服務發行集的安全性問題。

當 dwControlFlags 參數設定為 SERVICE_MULTIPLE時，應用程式可以獨立管理其位址。當應用程式想要個別管理其通訊協定或服務位於多部計算機上時，這非常有用。例如，當服務使用多個通訊協定時，可能會發現一個接聽套接字中止，但其他套接字仍可運作。在此情況下，服務可以從登錄中移除中止的位址，而不會影響其他位址。

當 dwControlFlags 參數設定為 SERVICE_MULTIPLE 時，應用程式不得讓過時的位址保留在物件中。如果應用程式在沒有發出 DEREGISTER 要求的情況下中止，就會發生這種情況。當服務註冊時，它應該儲存其位址。在下次叫用時，服務應該先從登錄明確移除這些舊的過時位址，再註冊新的位址。

注意如果使用 ANSI 字元字串，則此函式傳回之後，lpqsRegInfo 中的 WSAQUERYSET 數據可能不會包含任何結果。這是因為此方法的 ANSI 版本 WSASetServiceA 會在內部將 WSAQUERYSET 中的 ANSI 數據轉換成 Unicode，但不會將結果轉換回 ANSI。這主要會影響傳回用來唯一識別記錄之「服務記錄句柄」的傳輸。若要解決此問題，應用程式應該在呼叫此函式時，在 WSAQUERYSET 中使用 Unicode 字串數據。

服務屬性

下表描述如何在 WSAQUERYSET 結構中表示服務屬性數據。標記為 (選擇性) 的欄位可以包含 null 指標。

WSAQUERYSET 成員	服務屬性描述
dwSize	必須設定為sizeof (WSAQUERYSET) 。這是版本設定機制。
dwOutputFlags	不適用並忽略。
lpszServiceInstanceName	參考的字串包含服務實例名稱。
lpServiceClassId	對應至這個服務類別的 GUID。
lpVersion	(選擇性) 提供服務實例版本號碼。
lpszComment	(選擇性) 選擇性批注字串。
dwNameSpace	請參閱下表。
lpNSProviderId	請參閱下表。
lpszContext	(選擇性) 指定階層命名空間中的查詢起點。
dwNumberOfProtocols	忽略。
lpafpProtocols	忽略。
lpszQueryString	忽略。
dwNumberOfCsAddrs	lpcsaBuffer 所參考之CSADDR_INFO結構陣列中的項目數目。
lpcsaBuffer	包含服務所接聽之位址 () CSADDR_INFO 結構的陣列指標。
lpBlob	(選擇性) 這是提供者特定實體的指標。

如下列所示， dwNameSpace 和 lpNSProviderId 成員的組合會決定命名空間提供者受到此函式的影響。

dwNameSpace	lpNSProviderId	影響範圍
忽略	非 Null	指定的名稱空間提供者。
有效的名稱- 空格識別碼	Null	支援指定命名空間的所有名稱空間提供者。
NS_ALL	Null	所有名稱空間提供者。

Windows Phone 8：Windows Phone 8 和更新版本上的 Windows Phone Store 應用程式支援 WSASetServiceW 函式。

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

注意

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

規格需求

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