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 頭文件中定義，而且可以是下列選項的組合。
| 旗標 | 意義 |
|---|---|
|
查詢深度，而不是第一個層級。 |
|
只傳回容器。 |
|
請勿傳回容器。 |
|
可能的話，會以距離的順序傳回結果。 距離的量值是提供者特定的。 |
|
擷取名稱為 lpszServiceInstanceName。 |
|
擷取類型為 lpServiceClassId。 |
|
擷取版本作為 lpVersion。 |
|
將批注擷取為 lpszComment。 |
|
擷取位址做為 lpcsaBuffer。 |
|
以 lpBlob 的形式擷取私人數據。 |
|
任何可用的別名資訊都會在 對 WSALookupServiceNext 的後續呼叫中傳回，而傳回的每個別名都會設定RESULT_IS_ALIAS旗標。 |
|
擷取用於要求的查詢字串。 |
|
一組旗標，擷取所有LUP_RETURN_* 值。 |
|
作為 WSALookupServiceNext 中 dwControlFlags 參數的值。 設定此旗標會指示提供者捨棄最後一個結果集，這對指定的緩衝區太大，並移至下一個結果集。 |
|
如果提供者已經快取資訊，請忽略快取，並查詢命名空間本身。 |
|
這表示主要回應是在 CSADDR_INFO 結構的遠端或本機部分。 另一個部分必須可在任一情況下使用。 |
[out] lphLookup
呼叫 WSALookupServiceNext 時要使用的句柄，以便開始擷取結果集。
傳回值
如果作業成功，則傳回值為零。 否則，會傳回SOCKET_ERROR值，並呼叫 WSAGetLastError 來擷取特定的錯誤號碼。
| 錯誤碼 | 意義 |
|---|---|
| 記憶體不足，無法執行作業。 | |
| 此提供者遺漏或無效的一或多個參數。 | |
| 在資料庫中找到名稱，但找不到符合指定限制的數據。 | |
| 尚未初始化 WS2_32.DLL。 應用程式必須先呼叫 WSAStartup ，再呼叫任何 Windows Sockets 函式。 | |
|
不知道這類服務。 在指定的名稱空間中找不到服務。
如果找不到遠端藍牙裝置，則會針對藍牙服務探索要求傳回此錯誤。 |
備註
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 | (選擇性) 這是提供者特定實體的指標。 |
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 |