WSASetServiceA 函式（winsock2.h）

發行項
11/20/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	從動態名稱和永續性空格中刪除服務。對於以多個 CSADDR_INFO 結構表示的服務（使用 SERVICE_MULTIPLE 旗標），只會刪除指定的位址，而且這必須與註冊服務時指定的對應 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 函式的作業，如下表所示。

操作	標誌	服務已經存在	服務不存在
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

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

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

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

注意如果使用 ANSI 字元字串，WSAQUERYSETlpqsRegInfo 中的數據，在此函式傳回之後可能不會包含任何結果。這是因為此方法的 ANSI 版本 WSASetServiceA，會將 WSAQUERY SET 中的 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	指定的名稱空間提供者。
有效的名稱- 空間識別碼	零	支援指定命名空間的所有名稱空間提供者。
NS_ALL	零	所有名稱空間提供者。

Windows Phone 8： Windows Phone 8 和更新版本的 Windows Phone 市集應用程式支援 WSASetServiceW 功能。

Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更新版本上的 Windows 市集應用程式支援 WSASetServiceW 功能。

注意

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

要求

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