LPNSPV2SETSERVICEEX回呼函式 (ws2spi.h)

發行項
03/13/2024

NSPv2SetServiceEx 函式會在命名空間服務提供者第 2 版 (NSPv2) 提供者的命名空間內註冊或取消註冊名稱或服務實例。

語法

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

參數

[in] hAsyncCall

從先前呼叫 NSPv2LookupServiceBegin 傳回的句柄，用於異步呼叫。

[in] lpProviderId

註冊名稱或服務之特定命名空間提供者 GUID 的指標。

[in] lpqsRegInfo

註冊時要更新的屬性資訊。

[in] essOperation

要求的作業類型。

此參數可以是 Winsock2.h 頭文件中定義之 WSAESETSERVICEOP 列舉類型的其中一個值。

值	意義
RNRSERVICE_REGISTER 0	註冊服務。對於在 NetWare 環境中使用的「服務廣告通訊協定」 (SAP) 命名空間，這表示傳送定期廣播。這是功能變數名稱系統 (DNS) 命名空間的 NOP。對於持續性數據存放區，這表示更新地址資訊。
RNRSERVICE_DEREGISTER 1	取消註冊服務。針對 SAP 命名空間，這表示停止傳送定期廣播。這是 DNS 命名空間的 NOP。對於持續性數據存放區，這表示刪除地址資訊。
RNRSERVICE_DELETE 2	從動態名稱和永續性空格中刪除服務。對於使用SERVICE_MULTIPLE) 旗標 (多個 CSADDR_INFO 結構所表示的服務，只會刪除提供的位址，而且這必須與服務註冊時所提供的對應 CSADDR_INFO 結構完全相符。

[in] dwControlFlags

一組旗標，可控制所要求的作業。

此參數的可能值定義在 Winsock2.h 頭檔中。

值	意義
SERVICE_MULTIPLE 0x00000001	控制作業的範圍。設定此值時，動作只會在指定的位址集上執行。註冊作業不會使現有的位址失效，而取消註冊作業只會使指定的位址集失效。當此值不存在時，服務位址會以群組的形式管理。註冊或取消註冊會在新增指定的位址集之前，使所有現有的位址失效。

值

意義

SERVICE_MULTIPLE

0x00000001

控制作業的範圍。

設定此值時，動作只會在指定的位址集上執行。註冊作業不會使現有的位址失效，而取消註冊作業只會使指定的位址集失效。

當此值不存在時，服務位址會以群組的形式管理。註冊或取消註冊會在新增指定的位址集之前，使所有現有的位址失效。

[in] lpvClientSessionArg

用戶端會話的指標。

傳回值

如果例程成功，函式應該傳回 NO_ERROR (零) 。它應該傳回 SOCKET_ERROR (，也就是說，例程失敗時為 1) ，而且必須使用 WSASetLastError 設定適當的錯誤碼。

錯誤碼	意義
WSA_NOT_ENOUGH_MEMORY	記憶體不足，無法執行這項作業。
WSAEACCES	呼叫例程沒有足夠的許可權可安裝服務。
WSAEINVAL	此提供者的一或多個參數無效或遺失。
WSAEOPNOTSUPP	不支援此作業。如果命名空間提供者未實作此函式，就會傳回此錯誤。如果指定的 dwControlCode 是無法辨識的命令，也可以傳回此錯誤。
WSASERVICE_NOT_FOUND	服務未知。在指定的命名空間中找不到服務。

備註

NSPv2SetServiceEx 函式會作為命名空間服務提供者第 2 版 (NSPv2) 架構的一部分，可在 Windows Vista 和更新版本上使用。

在 Windows Vista 和 Windows Server 2008 上， NSPv2SetServiceEx 函式只能用於NS_EMAIL命名空間提供者上的作業。

每次新的用戶端進程開始使用命名空間提供者時，都會呼叫 NSPv2Startup 函式。提供者可以使用 ppvClientSessionArg 參數所指向的用戶端會話自變數來儲存此會話的相關信息。此用戶端會話自變數可以傳遞至 lpvClientSessionArg 參數中的 NSPv2SetServiceEx 函式。

NSPv2SetServiceEx 函式是選擇性的，視 NSPv2 提供者的需求而定。如果未實作 NSPv2SetServiceEx 函式，則 NSPv2 函式指標可以是一律傳回 NO_ERROR的存根函式。

下表列出 essOperation 和 dwControlFlags 參數的可能值組合。

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

當 dwControlFlags 參數設定為 SERVICE_MULTIPLE 時，這可讓應用程式獨立管理其位址。當應用程式必須個別管理其通訊協定，或服務位於多部計算機上時，這非常有用。例如，當服務使用多個通訊協定時，一個接聽套接字可能會中止，但其他套接字仍可運作。在此範例中，服務可能會取消註冊中止的位址，而不會影響其他位址。

使用 SERVICE_MULTIPLE時，應用程式不得讓舊位址保留在物件中。如果應用程式在沒有發出 RNRSERVICE_DEREGISTER 要求的情況下中止，就會發生這種情況。當服務註冊時，它應該儲存其位址。在下一次呼叫時，服務應該在註冊新位址之前明確取消註冊這些舊位址。

如果未實作 NSPv2SetServiceEx 函式，則應該由傳回 WSAEOPNOTSUPP 的存根函式攔截該函式的呼叫。 NSPV2_ROUTINE 結構中未實作 NSPv2SetServiceEx 函式的 NSPv2 函式指標應指向存根函式。

服務屬性

下表列出 WSAQUERYSET2 成員名稱，並描述服務屬性數據的表示方式。當命名空間提供者未使用時，可能會將標記為選擇性且相依於 NSPv2 提供者需求的成員提供為 **NULL** 指標。

WSAQUERYSET2成員名稱	服務屬性描述
dwSize	設定為sizeof (WSAQUERYSET2) 。這是版本設定機制。
lpszServiceInstanceName	包含服務實例名稱的字串。
lpVersion	服務實例版本號碼。此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
lpszComment	批註字串。此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
dwNameSpace	命名空間標識碼。此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
lpNSProviderId	提供者標識碼。請注意，命名空間提供者標識碼也會傳入 lpProviderId 參數。此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
lpszContext	階層命名空間中查詢的起點。此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
dwNumberOfProtocols	通訊協議條件約束陣列中項目數的大小，以位元組為單位。這個成員可以是零。此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
lpafpProtocols	AFPROTOCOLS 結構的陣列。此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
lpszQueryString	某些命名空間 (例如 whois++) 支援簡單文字字串中包含的豐富類似 SQL 查詢。此參數是用來指定該字串。此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
dwNumberOfCsAddrs	lpcsaBuffer 所參考之CSADDR_INFO結構陣列中的項目數目。
lpcsaBuffer	包含服務正在接聽之位址或位址之CSADDR_INFO 結構的數位指標。
dwOutputFlags	此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
lpBlob	提供者特定實體的指標。 NS_EMAIL命名空間需要這個成員。此成員是選擇性的，取決於其他 NSPv2 服務提供者的需求。

**附注** 可接受 CSADDR_INFO 結構的 **iProtocol** 成員包含指令清單常數 **IPROTOCOL_ANY**，表示通配符值。命名空間提供者應該取代指定位址系列和套接字類型的可接受值。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	ws2spi.h