WSALookupServiceBeginW 函式 (winsock2.h)
WSALookupServiceBegin 函式會起始受 WSAQUERYSET 結構內所含資訊的限制客戶端查詢。 WSALookupServiceBegin 只會傳回句柄，後續呼叫 WSALookupServiceNext 時應該使用此句柄來取得實際結果。
語法
INT WSAAPI WSALookupServiceBeginW(
[in] LPWSAQUERYSETW 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 結構的緩衝區。 至少，WSAQUERYSET 的 dwSize 成員必須設定為緩衝區的長度，才能呼叫 WSALookupServiceBegin 函式。 應用程式可以在 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 8.1、Windows Server 2012 R2 及更新版本的 Windows 市集應用程式支援 WSALookupServiceBeginW 函式。
注意
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 |