Share via

WSALookupServiceBeginA 函式 (winsock2.h)

  • 發行項

WSALookupServiceBegin 函式會起始客戶端查詢，此查詢受限於 WSAQUERYSET 結構中包含的資訊。 WSALookupServiceBegin 只會傳回句柄，後續呼叫 WSALookupServiceNext 時應該使用這個句柄來取得實際的結果。

語法

INT WSAAPI WSALookupServiceBeginA(
  [in]  LPWSAQUERYSETA lpqsRestrictions,
  [in]  DWORD          dwControlFlags,
  [out] LPHANDLE       lphLookup
);

參數

[in] lpqsRestrictions

搜尋準則的指標。 如需詳細資訊，請參閱。

[in] dwControlFlags

一組旗標，可控制搜尋的深度。

dwControlFlags 參數支援的值是在 Winsock2.h 頭文件中定義，而且可以是下列選項的組合。

旗標 意義
LUP_DEEP
0x0001
 查詢深度，而不是第一個層級。
LUP_CONTAINERS
0x0002
 只傳回容器。
LUP_NOCONTAINERS
0x0004
 請勿傳回容器。
LUP_NEAREST
0x0008
 可能的話，會以距離的順序傳回結果。 距離的量值是提供者特定的。
LUP_RETURN_NAME
0x0010
 擷取名稱為 lpszServiceInstanceName。
LUP_RETURN_TYPE
0x0020
 擷取類型為 lpServiceClassId。
LUP_RETURN_VERSION
0x0040
 擷取版本作為 lpVersion。
LUP_RETURN_COMMENT
0x0080
 將批注擷取為 lpszComment。
LUP_RETURN_ADDR
0x0100
 擷取位址做為 lpcsaBuffer。
LUP_RETURN_BLOB
0x0200
 以 lpBlob 的形式擷取私人數據。
LUP_RETURN_ALIASES
0x0400
 任何可用的別名資訊都會在 對 WSALookupServiceNext 的後續呼叫中傳回，而傳回的每個別名都會設定RESULT_IS_ALIAS旗標。
LUP_RETURN_QUERY_STRING
0x0800
 擷取用於要求的查詢字串。
LUP_RETURN_ALL
0x0FF0
 一組旗標，擷取所有LUP_RETURN_* 值。
LUP_FLUSHPREVIOUS
0x1000
 作為 WSALookupServiceNext 中 dwControlFlags 參數的值。 設定此旗標會指示提供者捨棄最後一個結果集，這對指定的緩衝區太大，並移至下一個結果集。
LUP_FLUSHCACHE
0x2000
 如果提供者已經快取資訊，請忽略快取，並查詢命名空間本身。
LUP_RES_SERVICE
0x8000
 這表示主要回應是在 CSADDR_INFO 結構的遠端或本機部分。 另一個部分必須可在任一情況下使用。

[out] lphLookup

呼叫 WSALookupServiceNext 時要使用的句柄，以便開始擷取結果集。

傳回值

如果作業成功，則傳回值為零。 否則，會傳回SOCKET_ERROR值，並呼叫 WSAGetLastError 來擷取特定的錯誤號碼。

錯誤碼 意義
WSA_NOT_ENOUGH_MEMORY
 記憶體不足，無法執行作業。
WSAEINVAL
 此提供者遺漏或無效的一或多個參數。
WSANO_DATA
 在資料庫中找到名稱，但找不到符合指定限制的數據。
WSANOTINITIALISED
 尚未初始化 WS2_32.DLL。 應用程式必須先呼叫 WSAStartup ，再呼叫任何 Windows Sockets 函式。
WSASERVICE_NOT_FOUND
 不知道這類服務。 在指定的名稱空間中找不到服務。

如果找不到遠端藍牙裝置，則會針對藍牙服務探索要求傳回此錯誤。

備註

lpqsRestrictions 參數指向包含 WSAQUERYSET 結構的緩衝區。 在呼叫 WSALookupServiceBegin 函式之前，至少必須將 WSAQUERYSET 的 dwSize 成員設定為緩衝區的長度。 應用程式可以在 WSAQUERYSET 中指定其他成員來限制查詢。

在大部分情況下，只有特定傳輸通訊協定的應用程式應該使用 WSAQUERYSET 的 dwNumberOfProtocols 和 lpafpProtocols 成員來限制其查詢，而不是指定 dwNameSpace 成員中的命名空間。

您可以使用 EnumProtocols、 WSAEnumProtocols、 WSCEnumProtocols 或 WSCEnumProtocols32 函式，來擷取支持網路傳輸通訊協定的相關信息。

您也可以將查詢限制為單一命名空間。 例如，只想要 DNS 的結果 (不是來自本機主機檔案和其他命名服務的查詢，) 會將 dwNameSpace 成員設定為 NS_DNS。 例如，藍牙裝置探索會將 dwNameSpace 成員設定為 NS_BTH。

應用程式也可以藉由指定 lpNSProviderId 成員中提供者之 GUID 的指標，將查詢限制為特定命名空間提供者。

您可以使用 WSAEnumNameSpaceProviders、WSAEnumNameSpaceProvidersEx、WSCEnumNameSpaceProviders32 或 WSCEnumNameSpaceProvidersEx32 函式來擷取本機電腦上的命名空間提供者資訊。

如果在呼叫中指定LUP_CONTAINERS，應該避免其他限制值。 如果指定了任何專案，則由名稱服務提供者決定是否可支援容器的這項限制。 如果無法，它應該會傳回錯誤。

某些名稱服務提供者可以有其他方法來尋找容器。 例如，容器可能全都是一些已知的類型，或一組已知的類型，因此可以建立查詢限制來尋找它們。 不論其他哪一個表示名稱服務提供者對於尋找容器而言，LUP_CONTAINERS和LUP_NOCONTAINERS優先。 因此，如果指定包含容器的查詢限制，則指定LUP_NOCONTAINERS將會防止傳回容器專案。 同樣地，不論查詢限制為何，如果已指定LUP_CONTAINERS，則應該只傳回容器。 如果命名空間不支援容器，而且已指定LUP_CONTAINERS，則應該只傳回 WSANO_DATA。

取得另一個容器內容器的慣用方法是呼叫：

dwStatus = WSALookupServiceBegin(
      lpqsRestrictions,
      LUP_CONTAINERS,
      lphLookup);

此呼叫後面接著必要的 WSALookupServiceNext 呼叫數目。 這會傳回在開始內容中立即包含的所有容器;也就是說，這不是深層查詢。 如此一來，您可以藉由逐步執行階層來對應位址空間結構，或許會列舉所選容器的內容。 後續使用 WSALookupServiceBegin 時，會使用先前呼叫所傳回的容器。

如上所述， WSAQUERYSET 結構會作為 WSALookupBegin 的輸入參數，以限定查詢。 下表指出如何使用 WSAQUERYSET 來建構查詢。 當參數標示為 (選擇性) 可以指定 NULL 指標時，表示參數不會當做搜尋準則使用。 如需詳細資訊，請參閱 查詢相關數據結構 一節。

WSAQUERYSET 成員 查詢解譯
dwSize 必須設定為sizeof (WSAQUERYSET) 。 這是版本設定機制。
dwOutputFlags 針對查詢忽略。
lpszServiceInstanceName (選擇性) 參考字串包含服務名稱。 未定義字串內通配符的語意，但可由特定命名空間提供者支援。
lpServiceClassId (必要) 對應至服務類別的 GUID。
lpVersion (選擇性) 參考所需的版本號碼，並提供版本比較語意 (，也就是版本必須完全相符，或版本必須不小於指定的) 值。
lpszComment 針對查詢忽略。
dwNameSpace

請參閱下列重要注意事項。

 要限制搜尋的單一命名空間標識碼，或NS_ALL包含所有命名空間。
lpNSProviderId (選擇性) 參考特定命名空間提供者的 GUID，並僅限制此提供者的查詢。
lpszContext (選擇性) 指定階層命名空間中的查詢起點。
dwNumberOfProtocols 通訊協議條件約束陣列的大小可以是零。
lpafpProtocols (選擇性) 參考 AFPROTOCOLS 結構的陣列。 只會傳回使用這些通訊協議的服務。
lpszQueryString (選擇性) 某些命名空間 (，例如 whois++) 支援簡單文字字串中包含的擴充 SQL 類似查詢。 此參數是用來指定該字串。
dwNumberOfCsAddrs 針對查詢忽略。
lpcsaBuffer 針對查詢忽略。
lpBlob (選擇性) 這是提供者特定實體的指標。
 
重要 在大部分情況下，只對特定傳輸通訊協定感興趣的應用程式應該依位址系列和通訊協定來限制其查詢，而不是依命名空間限制。 這可讓需要尋找 TCP/IP 服務的應用程式，例如，讓所有可用的命名空間處理其查詢，例如本機主機檔案、DNS 和 NIS。
 
Windows Phone 8：Windows Phone 8 和更新版本上的 Windows Phone Store 應用程式支援 WSALookupServiceBeginW 函式。

Windows 8.1 和 Windows Server 2012 R2：Windows 市集應用程式支援 WSALookupServiceBeginW 函式，Windows 8.1、Windows Server 2012 R2 及更新版本。

注意

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

規格需求

需求 值
最低支援的用戶端 Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 winsock2.h
程式庫 Ws2_32.lib
Dll Ws2_32.dll

另請參閱

藍牙和 WSALookupServiceBegin

EnumProtocols

WSAEnumNameSpaceProviders

WSAEnumNameSpaceProvidersEx

WSAEnumProtocols

WSALookupServiceEnd

WSALookupServiceNext

WSAQUERYSET

WSCEnumNameSpaceProviders32

WSCEnumNameSpaceProvidersEx32

WSCEnumProtocols

WSCEnumProtocols32