共用方式為


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
做為WSALookupServiceNextdwControlFlags參數的值。 設定此旗標會指示提供者捨棄最後一個結果集,這對指定的緩衝區太大,並移至下一個結果集。
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函式。 WSAQUERYSETdwSize成員至少必須設定為緩衝區的新大小。

查詢結果

下表描述 如何在 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.1Windows 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 參考