WSALookupServiceNextA 函式 (winsock2.h)

  • 發行項

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

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

語法

INT WSAAPI WSALookupServiceNextA(
  [in]      HANDLE         hLookup,
  [in]      DWORD          dwControlFlags,
  [in, out] LPDWORD        lpdwBufferLength,
  [out]     LPWSAQUERYSETA 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 8.1、Windows Server 2012 R2 及更新版本的 Windows 市集應用程式支援WSALookupServiceNextW函式。

注意

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 參考