LPNSPLOOKUPSERVICENEXT 回呼函式 (ws2spi.h)

  • 發行項

從先前呼叫 NSPLookupServiceBegin 取得句柄之後，就會呼叫 NSPLookupServiceNext 函式，以擷取所要求的服務資訊。

提供者會在 lpqsResults 緩衝區中傳遞 WSAQUERYSET 結構。 客戶端應該呼叫此函式，直到傳回 WSA_E_NOMORE，指出所有 WSAQUERYSET 都已傳回。

語法

LPNSPLOOKUPSERVICENEXT Lpnsplookupservicenext;

INT Lpnsplookupservicenext(
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSETW lpqsResults
)
{...}

參數

[in] hLookup

從先前呼叫 WSALookupServiceBegin 傳回的句柄。

[in] dwControlFlags

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

[in, out] lpdwBufferLength

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

[out] lpqsResults

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

傳回值

如果例程成功，函式應該會 傳回NO_ERROR (零) 。 如果例程失敗，它應該會 傳回 SOCKET_ERROR (–1) ，而且必須使用 WSASetLastError 設定適當的錯誤碼。

錯誤碼 意義
WSA_E_CANCELLED
 呼叫 NSPLookupServiceEnd 是在此呼叫仍在處理時進行。 呼叫已取消。 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 錯誤碼來維持與最廣泛應用程式範圍的相容性。
WSA_INVALID_HANDLE
 指定的查閱句柄無效。
WSA_NOT_ENOUGH_MEMORY
 記憶體不足，無法執行這項作業。
WSAEFAULT
 lpqsResults 緩衝區太小，無法包含 WSAQUERYSET 集合。
WSAEINVAL
 此提供者的一或多個參數無效或遺失。
WSAEOPNOTSUPP
 不支援此作業。 如果命名空間提供者未實作此函式，就會傳回此錯誤。
WSANO_DATA
 在資料庫中找到名稱，但找不到符合指定限制的數據。
WSASERVICE_NOT_FOUND
 服務未知。 在指定的命名空間中找不到服務。

備註

此函式中指定的 dwControlFlags 和 NSPLookupServiceBegin 時所指定的 dwControlFlags 會以“restrictions” 處理，以供組合之用。 限制會在 NSPLookupServiceBegin 時間與 NSPLookupServiceNext 時間的限制之間合併。 因此， NSPLookupServiceNext 的旗標永遠不會增加 超過 NSPLookupServiceBegin 要求的數據量，不過指定更多或更少旗標不是錯誤。 在指定 NSPLookupServiceNext 指定的旗標僅適用於該呼叫。

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

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

例如，如果未在 NSPLookupServiceBegin 指定LUP_RETURN_BLOB，但在 NSPLookupServiceNext 指定，傳回的資訊就不會包含私人數據。 不會產生錯誤。

查詢結果

下表列出 WSAQUERYSET ，並描述 如何在 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 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 ws2spi.h

另請參閱

CSADDR_INFO

NSPLookupServiceBegin

NSPLookupServiceEnd

NSP_ROUTINE

WSAQUERYSET

WSASetLastError