WSALookupServiceNextW 函式 (winsock2.h)

  • 發行項

從先前呼叫WSALookupServiceBegin取得控制碼之後，會呼叫WSALookupServiceNext函式，以擷取所要求的服務資訊。

提供者會傳回lpqsResults緩衝區中的WSAQUERYSET結構。 用戶端應該會繼續呼叫此函式，直到傳回WSA_E_NO_MORE，表示已傳回所有 WSAQUERYSET 。

語法

INT WSAAPI WSALookupServiceNextW(
  [in]      HANDLE         hLookup,
  [in]      DWORD          dwControlFlags,
  [in, out] LPDWORD        lpdwBufferLength,
  [out]     LPWSAQUERYSETW lpqsResults
);

參數

[in] hLookup

從先前呼叫 WSALookupServiceBegin傳回的控制碼。

[in] dwControlFlags

一組可控制作業的旗標。 在 dwControlFlags 參數中傳遞至 WSALookupServiceBegin 函式的值會決定可能的準則。 在 dwControlFlags 參數中傳遞至 WSALookupServiceNext 函式的任何值，會進一步限制服務查閱的準則。

目前，LUP_FLUSHPREVIOUS定義為處理太大結果集的方法。 如果應用程式未 (或無法) 提供足夠的緩衝區，則設定 LUP_FLUSHPREVIOUS會指示提供者捨棄最後一個結果集，也就是太大，並移至下一個集合以進行此呼叫。

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 結構的遠端或本機部分。 另一個部分必須可在任一情況下使用。

[in, out] lpdwBufferLength

在輸入時， lpqsResults所指向緩衝區中包含的位元組數目。 在輸出中，如果函式失敗且錯誤為 WSAEFAULT，則會包含 要為 lpqsResults 擷取記錄傳遞的最小位元組數。

[out] lpqsResults

記憶體區塊的指標，其會在傳回時在 WSAQUERYSET 結構中包含一個結果集。

傳回值

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

錯誤碼 意義
WSA_E_CANCELLED
 呼叫 WSALookupServiceEnd 時，此呼叫仍在處理中。 呼叫已取消。 lpqsResults緩衝區中的資料未定義。 在 Windows Sockets 第 2 版中， WSAECANCELLED (10103) 定義衝突的錯誤碼 ，WSA_E_CANCELLED ( 10111) 。 未來版本將會移除錯誤碼 WSAECANCELLED，而且只會保留WSA_E_CANCELLED。 不過，針對 Windows Sockets 第 2 版，應用程式應該檢查 WSAECANCELLED 和 WSA_E_CANCELLED，以取得與使用任一版本之命名空間提供者最廣泛的相容性。
WSA_E_NO_MORE
 沒有其他可用的資料。 在 Windows Sockets 第 2 版中， WSAENOMORE (10102) 定義衝突的錯誤 碼，WSA_E_NO_MORE (10110) 。 未來版本將會移除錯誤碼 WSAENOMORE，而且只會保留WSA_E_NO_MORE。 不過，針對 Windows Sockets 第 2 版，應用程式應該檢查 WSAENOMORE 和 WSA_E_NO_MORE，以取得與使用任一版本之名稱空間提供者最廣泛的相容性。
WSAEFAULT
 lpqsResults緩衝區太小，無法包含WSAQUERYSET集合。
WSAEINVAL
 一或多個必要參數無效或遺失。
WSA_INVALID_HANDLE
 指定的查閱控制碼無效。
WSANOTINITIALISED
 尚未初始化 WS2_32.DLL。 應用程式必須先呼叫 WSAStartup ，再呼叫任何 Windows Sockets 函式。
WSANO_DATA
 在資料庫中找到名稱，但找不到符合指定限制的資料。
WSA_NOT_ENOUGH_MEMORY
 記憶體不足，無法執行作業。

備註

在此函式中指定的 dwControlFlags 參數， 以及 WSALookupServiceBegin 時所指定的參數會被視為組合用途的限制。 限制會在 WSALookupServiceBegin 時間與 WSALookupServiceNext 時間的限制之間結合。 因此 ，WSALookupServiceNext 的旗標永遠不會增加超過 WSALookupServiceBegin要求的資料量，雖然指定更多或較少的旗標並不錯誤。 在指定 WSALookupServiceNext 指定的旗標僅適用于該呼叫。

dwControlFlags LUP_FLUSHPREVIOUS 和 LUP_RES_SERVICE 是合併的限制規則 (的例外狀況，因為它們是行為旗標，而不是限制旗標) 。 如果其中一個旗標用於 WSALookupServiceNext 中，不論 WSALookupServiceBegin上的相同旗標設定為何，它們都有其已定義的效果。

例如，如果在 WSALookupServiceBegin 指定LUP_RETURN_VERSION，服務提供者會擷取包含版本的記錄。 如果在 WSALookupServiceNext上未指定LUP_RETURN_VERSION，則傳回的資訊不會包含版本，即使版本可用也一樣。 不會產生任何錯誤。

例如，如果未在 WSALookupServiceBegin 指定LUP_RETURN_BLOB，但在 WSALookupServiceNext指定，則傳回的資訊不包含私人資料。 不會產生任何錯誤。

如果 WSALookupServiceNext 函式失敗，且發生 WSAEFAULT錯誤，這表示 lpqsResults 參數所指向的緩衝區太小而無法包含查詢結果。 WSAQUERYSET的新緩衝區應以lpdwBufferLength參數所指向的值所指定的大小提供。 WSAQUERYSET的新緩衝區必須有一些指定的WSAQUERYSET成員，然後再再次呼叫WSALookupServiceNext函式。 至少，WSAQUERYSET的dwSize成員必須設定為緩衝區的新大小。

查詢結果

下表描述如何在 WSAQUERYSET 結構中表示查詢結果。
WSAQUERYSET 成員 結果解譯
dwSize 將會設定為 sizeof ( WSAQUERYSET) 。 這會作為版本設定機制使用。
dwOutputFlags RESULT_IS_ALIAS旗標表示這是別名結果。
lpszServiceInstanceName 參考的字串包含服務名稱。
lpServiceClassId 對應至服務類別的 GUID。
lpVersion 參考特定服務實例的版本號碼。
lpszComment 服務實例指定的選擇性批註字串。
dwNameSpace 找到服務實例的命名空間。
lpNSProviderId 識別提供此查詢結果的特定命名空間提供者。
lpszCoNtext 指定服務所在階層命名空間中的內容點。
dwNumberOfProtocols 針對結果未定義。
lpafpProtocols 針對結果未定義，所有必要的通訊協定資訊都位於 CSADDR_INFO 結構中。
lpszQueryString 當 dwControlFlags包含LUP_RETURN_QUERY_STRING時，此參數會傳回原始查詢中所指定之 lpszServiceInstanceName的未剖析其餘部分。 例如，在以階層名稱識別服務的命名空間中，指定主機名稱和該主機內的檔案路徑，傳回的位址可能是主機位址，而未剖析的其餘部分可能是檔案路徑。 如果 lpszServiceInstanceName 已完整剖析，且使用LUP_RETURN_QUERY_STRING，此參數為 Null 或指向長度為零的字串。
dwNumberOfCsAddrs 指出 CSADDR_INFO 結構陣列中的專案數目。
lpcsaBuffer CSADDR_INFO結構的陣列指標，每個元素都包含一個完整的傳輸位址。
lpBlob (選擇性) 這是提供者特定實體的指標。
 

Windows Phone 8：Windows Phone 8 和更新版本上的 Windows Phone Store 應用程式支援WSALookupServiceNextW函式。

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

注意

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

規格需求

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

另請參閱

藍牙和 WSALookupServiceNext

WSALookupServiceBegin

WSALookupServiceEnd

WSAQUERYSET

Winsock 函式

Winsock 參考