LPNSPV2LOOKUPSERVICENEXTEX回呼函式 (ws2spi.h)

  • 發行項

從先前呼叫NSPv2LookupServiceBegin取得控制碼之後，會呼叫NSPv2LookupServiceNextEx函式，以便從命名空間第 2 版服務提供者擷取要求的資訊。

語法

LPNSPV2LOOKUPSERVICENEXTEX Lpnspv2lookupservicenextex;

void Lpnspv2lookupservicenextex(
  [in]      HANDLE hAsyncCall,
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSET2W lpqsResults
)
{...}

參數

[in] hAsyncCall

從先前呼叫 NSPv2LookupServiceBegin 傳回的控制碼，用於非同步呼叫。

[in] hLookup

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

[in] dwControlFlags

用來控制下一個作業的旗標。 目前，只有 LUP_FLUSHPREVIOUS 定義為處理太大結果集的方法。 如果應用程式無法提供足夠的緩衝區，設定 LUP_FLUSHPREVIOUS 會指示提供者捨棄最後一個結果集，這太大，並移至這個呼叫的下一個集合。

[in, out] lpdwBufferLength

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

[out] lpqsResults

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

傳回值

如果常式成功，函式應該傳回 NO_ERROR (零) 。 它應該傳回 SOCKET_ERROR (，也就是說，常式失敗時為 1) ，而且必須使用 WSASetLastError設定適當的錯誤碼。

錯誤碼 意義
WSA_E_CANCELLED
 呼叫 NSPv2LookupServiceEnd 時，此呼叫仍在處理中。 呼叫已取消。 lpqsResults緩衝區中的資料未定義。

在 Windows Sockets 2 中， WSAECANCELLED (10103) 定義衝突的錯誤碼，WSA_E_CANCELLED ( 10111) 。未來版本將會移除錯誤碼 WSAECANCELLED ，且只會保留WSA_E_CANCELLED。 命名空間提供者應該使用 WSA_E_CANCELLED 錯誤碼來維持與最廣泛的應用程式相容性。
WSA_E_NO_MORE
 沒有其他可用的資料。

在 Windows Sockets 2 中， WSAENOMORE (10102) 定義衝突的錯誤碼，WSA_E_NO_MORE ( 10110) 。未來版本將會移除錯誤碼 WSAENOMORE ，且只會保留WSA_E_NO_MORE。 命名空間提供者應該使用 WSA_E_NO_MORE 錯誤碼來維持與最廣泛的應用程式相容性。
WSAEFAULT
 lpqsResults緩衝區太小而無法包含WSAQUERYSET集合。
WSAEINVAL
 此提供者的一或多個參數無效或遺失。
WSA_INVALID_HANDLE
 指定的查閱控制碼無效。
WSANO_DATA
 在資料庫中找到名稱，但找不到符合指定限制的資料。
WSASERVICE_NOT_FOUND
 服務未知。 在指定的命名空間中找不到服務。
WSA_NOT_ENOUGH_MEMORY
 記憶體不足，無法執行這項作業。

備註

NSPv2LookupServiceNextEx函式會用來作為 Windows Vista 和更新版本上可用的命名空間服務提供者版本 2 (NSPv2) 架構的一部分。

在 Windows Vista 和 Windows Server 2008 上， NSPv2LookupServiceNextEx 函式只能用於NS_EMAIL命名空間提供者上的作業。

提供者會在lpqsResults緩衝區中傳遞WSAQUERYSET2結構。 用戶端應該呼叫 NSPv2LookupServiceNextEx 函式，直到傳回 WSA_E_NOMORE為止，表示所有 WSAQUERYSET2 結構都已傳回。

在此函式中指定的 dwControlFlags ， 以及 NSPv2LookupServiceBegin 時所指定的 dwControlFlags 會以「限制」的形式處理，以供組合之用。 限制會結合 NSPv2LookupServiceBegin 時間的限制，以及 NSPv2LookupServiceNextEx 時間的限制。 因此， NSPv2LookupServiceNextEx 的 旗標永遠不會增加超過 NSPv2LookupServiceBegin要求的資料量，不過指定更多或更少旗標並不錯誤。 指定于指定 NSPv2LookupServiceNextEx 的旗標僅適用于該呼叫。

dwControlFlagsLUP_FLUSHPREVIOUS和LUP_RES_SERVICE是合併的限制規則 (的例外狀況，因為它們是行為旗標，而不是) 的「限制」旗標。 如果 NSPv2LookupServiceNextEx中使用任一旗標，無論 NSPv2LookupServiceBegin上的相同旗標設定為何，它們都有其已定義的效果。

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

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

NSPv2LookupServiceNextEx函式通常至少呼叫兩次。 第一次取得所需緩衝區的大小，以接收lpqsResults參數所指向的WSAQUERYSET2，第二次取得實際的查詢結果集。 在第一次呼叫時，NSPv2 提供者應該傳回 WSAQUERYSET2 結果所需的大小。

傳回之 lpqsResults參數所指向的WSAQUERYSET2結構只有在相同的進程內容中才有用，因為WSAQUERYSET2結構中的數個成員包含所傳回實際資料的指標。 如果需要使用 RPC 將查詢結果傳遞至另一個進程 (，例如) ，則必須序列化和封送處理lpqsResults參數所指向之WSAQUERYSET2結構中所傳回的資料，包括WSAQUERYSET2結構中成員所指向的資料。 資料必須以可跨進程界限傳遞的表單序列化。 只要傳遞 WSAQUERYSET2 結構的複本就不足，因為只會傳遞資料的指標，而實際資料將無法供其他進程使用。

查詢結果

下表列出 WSAQUERYSET2 ，並描述如何在 **WSAQUERYSET2** 結構中表示查詢結果。 如需詳細資訊，請參閱 查詢相關資料結構。
WSAQUERYSET2成員名稱 結果解譯
**dwSize** WSAQUERYSET2 結構的大小 ，以位元組為單位。 這會作為版本設定機制使用。
**lpszServiceInstanceName** 包含服務名稱的字串。
**lpVersion** 參考特定服務實例的版本號碼。
**lpszComment** 服務實例所提供的批註字串。 此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
**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結構的陣列指標，每個元素都包含一個完整的傳輸位址。
**dwOutputFlags** **RESULT_IS_ALIAS** 旗標表示這是別名結果。
**lpBlob** 提供者特定實體的指標。 此成員是選擇性的，取決於 NSPv2 服務提供者的需求。

規格需求

   
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 ws2spi.h

另請參閱

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceBegin

NSPv2LookupServiceEnd

NSPv2SetServiceEx

NSPv2Startup

WSAQUERYSET2

WSASetLastError