getServiceA 函式 (nspapi.h)

發行項
02/29/2024

GetService 函式會擷取一組預設命名空間或指定命名空間內容中的網路服務相關信息。網路服務是由其類型和名稱所指定。服務的相關信息會以一組NS_SERVICE_INFO 數據結構的形式取得。

注意GetService 函式是 Windows Sockets 1.1 規格的 Microsoft 特定擴充功能。此函式已過時。為了方便 Windows Sockets 1.1 開發人員使用，會包含此參考數據。

注意通訊協議獨立名稱解析中詳述的函式在 Windows Sockets 2 中提供對等的功能。

語法

INT GetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpGuid,
  [in]           LPSTR                lpServiceName,
  [in]           DWORD                dwProperties,
  [out]          LPVOID               lpBuffer,
  [in, out]      LPDWORD              lpdwBufferSize,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);

參數

[in] dwNameSpace

操作系統應該查詢指定網路服務相關信息的命名空間或一組預設命名空間。

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

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

大部分 對 GetService 的呼叫都應該使用特殊值NS_DEFAULT。這可讓用戶端在不知道因特網上可用的命名空間的情況下取得。系統管理員決定命名空間存取權。命名空間可以來回，而不需要用戶端知道變更。

[in] lpGuid

指定網路服務類型的全域唯一標識符指標， (GUID) 。 Svcguid.h 頭檔包含來自 DNS 和 SAP 命名空間內許多已知服務的 GUID 服務類型。

Winsock2.h 頭檔不會自動包含 Svcguid.h 頭檔。

[in] lpServiceName

以零結尾字串的指標，可唯一表示服務名稱。例如，“MY SNA SERVER”。

[in] dwProperties

一組位旗標，指定函式所擷取的服務資訊。除了 PROP_ALL 以外，這些位旗標常數都對應至 SERVICE_INFO 數據結構的特定成員。如果設定旗標，函式會將資訊放入儲存在 *lpBuffer 中之數據結構的對應成員。定義下列位旗標。

值	意義
PROP_COMMENT	如果設定此旗標，函式會將數據儲存在儲存在 *lpBuffer 中的數據結構 lpComment 成員中。
PROP_LOCALE	如果設定此旗標，函式會將數據儲存在儲存在 *lpBuffer 中的數據結構的 lpLocale 成員中。
PROP_DISPLAY_HINT	如果設定此旗標，函式會將數據儲存在儲存在 *lpBuffer 中之數據結構的 dwDisplayHint 成員中。
PROP_VERSION	如果設定此旗標，函式會將數據儲存在儲存在 *lpBuffer 中之數據結構的 dwVersion 成員中。
PROP_START_TIME	如果設定此旗標，函式會將數據儲存在儲存在 *lpBuffer 中的數據結構 dwTime 成員中。
PROP_MACHINE	如果設定此旗標，函式會將數據儲存在 *lpBuffer 中儲存之數據結構的 lpMachineName 成員中。
PROP_ADDRESSES	如果設定此旗標，函式會將數據儲存在儲存在 *lpBuffer 中的數據結構的 lpServiceAddress 成員中。
PROP_SD	如果設定此旗標，函式會將數據儲存在儲存在 *lpBuffer 中的數據結構 ServiceSpecificInfo 成員中。
PROP_ALL	如果設定此旗標，函式會將數據儲存在 *lpBuffer 中儲存之數據結構的所有成員中。

[out] lpBuffer

緩衝區的指標，用來接收 NS_SERVICE_INFO 結構和相關聯服務資訊的陣列。每個 NS_SERVICE_INFO 結構都包含特定命名空間內容中的服務資訊。請注意，如果 dwNameSpace NS_DEFAULT，函式會將多個結構儲存到緩衝區中;否則，只會儲存一個結構。

每個 NS_SERVICE_INFO 結構都包含 SERVICE_INFO 結構。這些 SERVICE_INFO 結構的成員會根據 dwProperties 參數中設定的位旗標，包含有效的數據。如果未在 dwProperties 中設定成員的對應位旗標，則成員的值是未定義的。

函式會將 NS_SERVICE_INFO 結構儲存在連續數位中，從緩衝區的開頭開始。包含 SERVICE_INFO 結構中的指標指向儲存在 緩衝區中NS_SERVICE_INFO 結構結尾與緩衝區結尾之間的資訊。

[in, out] lpdwBufferSize

在輸入時，變數的指標包含 lpBuffer 所指向緩衝區的大小，以位元組為單位。在輸出時，此變數包含儲存所要求資訊所需的位元組數目。如果這個輸出值大於輸入值，函式因緩衝區大小不足而失敗。

[in, optional] lpServiceAsyncInfo

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

傳回值

如果函式成功，則傳回值是儲存在 *lpBuffer 中的NS_SERVICE_INFO結構數目。零表示未儲存任何結構。

如果函式失敗，傳回值會SOCKET_ERROR ( – 1) 。若要取得擴充的錯誤資訊，請呼叫 GetLastError，其會傳回下列其中一個擴充錯誤值。

錯誤碼	意義
ERROR_INSUFFICIENT_BUFFER	lpBuffer 指向的緩衝區太小，無法接收所有要求的資訊。使用緩衝區至少與 *lpdwBufferSize 中傳回的值一樣大呼叫函式。
ERROR_SERVICE_NOT_FOUND	找不到指定的服務，或指定的命名空間不在使用中。在此情況下，函式傳回值為零。

備註

注意

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

規格需求

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