LPNSPSETSERVICE 回呼函式 (ws2spi.h)

  • 發行項

NSPSetService 函式會在命名空間內註冊或取消註冊服務實例。

語法

LPNSPSETSERVICE Lpnspsetservice;

INT Lpnspsetservice(
  [in] LPGUID lpProviderId,
  [in] LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in] LPWSAQUERYSETW lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags
)
{...}

參數

[in] lpProviderId

登錄服務之特定命名空間提供者之 GUID 的指標。

[in] lpServiceClassInfo

服務類別架構資訊。

[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
 控制作業的範圍。

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

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

傳回值

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

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

備註

下表列出 essOperation 和 dwControlFlags 的可用值。

作業 Flags 服務已經存在 服務不存在
**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 要求的情況下中止，就會發生這種情況。 當服務註冊時，它應該儲存其位址。 在下一次呼叫時，服務應該在註冊新位址之前明確取消註冊這些舊位址。

服務屬性

下表列出 WSAQUERYSET 成員名稱，並描述服務屬性數據的表示方式。 標記為 (選擇性) 的成員可以使用 Null 指標提供。
WSAQUERYSET 成員名稱 服務屬性描述
**dwSize** 設定為 WSAQUERYSET (sizeof) 。 這是版本設定機制。
**lpszServiceInstanceName** 參考的字串包含服務實例名稱。
**lpServiceClassId** 對應至這個服務類別的 GUID。
**lpVersion** 選擇性。 提供服務實例版本號碼。
**lpszComment** 選擇性。 選擇性批註字串。
**dwNameSpace** 忽略此作業。
**lpNSProviderId** 忽略此作業。 提供者標識碼包含在 lpProviderId 參數中。
**lpszContext** 選擇性。 階層命名空間中查詢的起點。
**dwNumberOfProtocols** 忽略此作業。
**lpafpProtocols** 忽略此作業。
**pszQueryString** 忽略此作業。
**dwNumberOfCsAddrs** lpcsaBuffer 所參考之CSADDR_INFO結構陣列中的項目數目。
**lpcsaBuffer** 包含服務正在接聽之位址或位址 之CSADDR_INFO 結構的數位指標。
**dwOutputFlags** 忽略此作業。
**lpBlob** 選擇性。 提供者特定實體的指標。
 
**附注** 可接受 CSADDR_INFO 結構的 **iProtocol** 成員包含指令清單常數 **IPROTOCOL_ANY**，表示通配符值。 命名空間提供者應該取代指定位址系列和套接字類型的可接受值。
 

規格需求

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

另請參閱

CSADDR_INFO

WSAQUERYSET

WSASetLastError