SetServiceA 函式 (nspapi.h)

發行項
03/05/2024

SetService 函式會在登錄中註冊或移除一或多個命名空間內的網路服務。函式也可以新增或移除一或多個命名空間內的網路服務類型。

注意SetService 函式已過時。通訊協議獨立名稱解析中詳述的函式在 Windows Sockets 2 中提供對等的功能。為了方便 Windows Sockets 1.1 開發人員使用，參考數據如下所示。

語法

INT SetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           DWORD                dwOperation,
  [in]           DWORD                dwFlags,
  [in]           LPSERVICE_INFOA      lpServiceInfo,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPDWORD              lpdwStatusFlags
);

參數

[in] dwNameSpace

命名空間或一組預設命名空間，函式將在其中運作。

使用下列其中一個常數來指定命名空間。

值	意義
NS_DEFAULT	一組預設命名空間。函式會查詢此集合中的每個命名空間。預設命名空間集通常包含系統上安裝的所有命名空間。不過，系統管理員可以從集合中排除特定命名空間。 NS_DEFAULT是大部分應用程式應該用於 dwNameSpace 的值。
NS_DNS	因特網中用來解析主機名稱的域名系統。
NS_NDS	NetWare 4 提供者。
NS_NETBT	透過 TCP/IP 層的 NetBIOS。所有 Windows 系統都會向 NetBIOS 註冊其電腦名稱。此命名空間用來將計算機名稱轉換為使用此註冊的IP位址。
NS_SAP	NetWare 服務廣告通訊協定。如有需要，這可以存取 NetWare 系結專案。 NS_SAP是可註冊服務的動態命名空間。
NS_TCPIP_HOSTS	systemroot>\system32\drivers\etc\posts 檔案中的<查閱值。
NS_TCPIP_LOCAL	本機 TCP/IP 名稱解析機制，包括在主機與 IP 位址對應快取中與本機主機名的比較和查閱值。

[in] dwOperation

函式將執行的作業。使用下列其中一個值來指定作業：

值	意義
SERVICE_REGISTER	向命名空間註冊網路服務。此作業可以搭配SERVICE_FLAG_DEFER和SERVICE_FLAG_HARD位旗標使用。
SERVICE_DEREGISTER	從登錄中移除命名空間中的網路服務。此作業可以搭配SERVICE_FLAG_DEFER和SERVICE_FLAG_HARD位旗標使用。
SERVICE_FLUSH	執行任何呼叫且SERVICE_FLAG_DEFER位旗標設定為1的作業。
SERVICE_ADD_TYPE	將服務類型新增至命名空間。針對這項作業，請使用 lpServiceInfo 所指向之SERVICE_INFO結構的 ServiceSpecificInfo 成員來傳遞SERVICE_TYPE_INFO_ABS結構。您也必須設定SERVICE_INFO結構的 ServiceType 成員。會忽略其他 SERVICE_INFO 成員。
SERVICE_DELETE_TYPE	從命名空間中移除先前指定SERVICE_ADD_TYPE作業的呼叫所新增的服務類型。

[in] dwFlags

修改函式作業的一組位旗標。您可以設定下列一或多個位旗標：

值	意義
SERVICE_FLAG_DEFER	只有在作業SERVICE_REGISTER或SERVICE_DEREGISTER時，此位旗標才有效。如果這個位旗標是其中一個，而且有效，命名空間提供者應該延遲註冊或取消註冊作業，直到要求SERVICE_FLUSH作業為止。
SERVICE_FLAG_HARD	只有在作業SERVICE_REGISTER或SERVICE_DEREGISTER時，此位旗標才有效。如果這個位旗標是其中一個，而且有效，命名空間提供者會在執行作業時更新任何相關的永續性存放區資訊。例如：如果作業涉及在使用永續性存放區的命名空間中取消註冊，命名空間提供者會移除相關的永續性存放區資訊。

值

意義

SERVICE_FLAG_DEFER

只有在作業SERVICE_REGISTER或SERVICE_DEREGISTER時，此位旗標才有效。

如果這個位旗標是其中一個，而且有效，命名空間提供者應該延遲註冊或取消註冊作業，直到要求SERVICE_FLUSH作業為止。

SERVICE_FLAG_HARD

只有在作業SERVICE_REGISTER或SERVICE_DEREGISTER時，此位旗標才有效。

如果這個位旗標是其中一個，而且有效，命名空間提供者會在執行作業時更新任何相關的永續性存放區資訊。

例如：如果作業涉及在使用永續性存放區的命名空間中取消註冊，命名空間提供者會移除相關的永續性存放區資訊。

[in] lpServiceInfo

包含網路服務或服務類型相關信息之SERVICE_INFO 結構的指標。

[in, optional] lpServiceAsyncInfo

保留供未來使用。必須設定為 NULL。

[out] lpdwStatusFlags

接收函式狀態資訊的一組位旗標。已定義下欄位旗標：

值	意義
SET_SERVICE_ PARTIAL_SUCCESS	一或多個命名空間提供者無法成功執行要求的作業。

傳回值

如果函式失敗，傳回值會SOCKET_ERROR。若要取得擴充的錯誤資訊，請呼叫 GetLastError。 GetLastError 可以傳回下列擴充錯誤值。

錯誤碼	意義
ERROR_ALREADY_已註冊	函式嘗試註冊已註冊的服務。

備註

注意

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

規格需求

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