LPNSPV2LOOKUPSERVICEBEGIN回呼函式 (ws2spi.h)

  • 發行項

NSPv2LookupServiceBegin 函式會起始命名空間第 2 版服務提供者的客戶端查詢，此查詢受限於WSAQUERYSET2結構內所包含的資訊。

語法

LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;

INT Lpnspv2lookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSET2W lpqsRestrictions,
  [in]  DWORD dwControlFlags,
  [out] LPVOID lpvClientSessionArg,
  [out] LPHANDLE lphLookup
)
{...}

參數

[in] lpProviderId

要查詢之命名空間服務提供者標識碼的指標。

[in] lpqsRestrictions

搜尋準則的指標。 請參閱＜備註＞。

[in] 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
 任何可用的別名信息都會在 對 NSPv2LookupServiceNextEx 的後續呼叫中傳回，而傳回的每個別名都會設定 **RESULT_IS_ALIAS** 旗標。
LUP_RETURN_QUERY_STRING
0x0800
 將查詢字串擷取為 **lpszQueryString**。
LUP_RETURN_ALL
0x0ff0
 擷取資訊，包括名稱、類型、版本、批注、位址、Blob、別名和查詢字串。
LUP_FLUSHCACHE
0x1000
 如果提供者已快取資訊，請忽略快取並查詢命名空間本身。
LUP_FLUSHPREVIOUS
0x2000
 當做 NSPv2LookupServiceNextEx 中 dwControlFlags 參數的值使用。 設定此旗標會指示提供者捨棄最後一個結果集，這對提供的緩衝區太大，並移至下一個結果集。
LUP_NON_AUTHORITATIVE
0x4000
 指出命名空間提供者應該包含名稱的非授權結果。
LUP_RES_RESERVICE
0x8000
 指出主要回應是否位於 CSADDR_INFO 結構的遠端或本機部分。 在這兩種情況下，其他部分都必須可用。 此選項僅適用於服務實例要求。
LUP_SECURE
0x8000
 指出命名空間提供者應該使用安全查詢。 這個選項僅適用於名稱查詢要求。
LUP_RETURN_PREFERRED_NAMES
0x10000
 指出命名空間提供者應該只傳回慣用的名稱。
LUP_ADDRCONFIG
0x100000
 指出命名空間提供者應該傳回位址組態。
LUP_DUAL_ADDR
0x200000
 指出命名空間提供者應該傳回雙重位址。 此選項僅適用於) (IPv6 和 IPv4 對應位址的雙重模式套接字。
LUP_DISABLE_IDN_ENCODING
0x800000
 表示命名空間提供者應該停用自動國際域名編碼。

Windows 8和 Windows Server 2012 支援此值

[out] lpvClientSessionArg

用戶端會話的指標。

[out] lphLookup

要用於 後續對 NSPv2LookupServiceNextEx 之句柄的指標，以便擷取結果集。

傳回值

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

錯誤碼 意義
WSAEINVAL
 此提供者的一或多個參數無效或遺失。
WSANO_DATA
 在資料庫中找到名稱，但它沒有已解析的正確相關聯數據。
WSASERVICE_NOT_FOUND
 服務未知。 在指定的命名空間中找不到服務。
WSA_NOT_ENOUGH_MEMORY
 記憶體不足，無法執行這項作業。

備註

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

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

NSPv2LookupServiceBegin 函式只會傳回句柄，後續呼叫 NSPv2LookupServiceNextEx 時應該使用此句柄來取得實際結果。 因為無法取消此作業，所以應該實作以快速執行。 雖然可以接受起始網路查詢，但此函式不應要求回應才能成功傳回。

每次新的用戶端進程開始使用命名空間提供者時，都會呼叫 NSPv2Startup 函式。 提供者可以使用 ppvClientSessionArg 參數所指向的用戶端會話自變數來儲存此會話的相關信息。 如果在呼叫 NSPv2Startup 函式時為用戶端會話自變數指定值，則這個相同的用戶端會話自變數會在 lpvClientSessionArg 參數中傳遞至 NSPv2LookupServiceBegin 函式。

如果在呼叫中指定 LUP_CONTAINERS ，請避免所有其他限制值。 如果提供任何專案，則名稱服務提供者必須決定是否可以支援此限制的容器。 如果沒有，它應該會傳回錯誤。

某些名稱服務提供者可能會有其他尋找容器的方法。 例如，容器全都可以是某些已知的類型，或是一組已知的類型，因此可以建立查詢限制來尋找它們。 無論其他哪一個表示名稱服務提供者都有用來尋找容器， LUP_CONTAINERS 和 LUP_NOCONTAINERS 優先。 因此，如果指定包含容器的查詢限制， 則指定LUP_NOCONTAINERS 會防止傳回容器專案。 同樣地，無論查詢限制為何，如果 指定了LUP_CONTAINERS ，就應該只傳回容器。 如果命名空間不支援容器並指定 LUP_CONTAINERS ，則應該傳回 WSANO_DATA。

取得另一個容器內容器的慣用方法是呼叫：

dwStatus = NSPv2LookupServiceBegin(
    lpProviderId,
    lpqsRestrictions,
    LUP_CONTAINERS,
    lpClientSession,
    lphLookup);

後面接著 必要的 NSPv2LookupServiceNextEx 呼叫數目。 這會傳回在開始內容中立即包含的所有容器;也就是說，這不是深層查詢。 如此一來，您可以藉由逐步執行階層來對應位址空間結構，或許會列舉所選容器的內容。 NSPv2LookupServiceBegin 的後續使用會使用先前呼叫所傳回的容器。

形成查詢

WSAQUERYSET2 結構是用來作為 NSPv2LookupServiceBegin 的輸入參數，以限定查詢。 下表列出 **WSAQUERYSET2** 成員名稱，並描述如何使用 **WSAQUERYSET2** 來建構查詢。 當命名空間提供者未作為搜尋準則時，可能會以 **NULL** 指標的形式提供標示為選擇性且相依於 NSPv2 提供者需求的成員。 如需詳細資訊，請參閱 查詢相關數據結構。
WSAQUERYSET2成員名稱 查詢解譯
**dwSize** 將會設定為sizeof (WSAQUERYSET2) 。 這是版本設定機制。
**lpszServiceInstanceName** 包含服務名稱的字串。 未定義字串內通配符的語意，但可由特定命名空間提供者支援。 此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
**lpVersion** 提供版本比較語意 (所需的版本號碼，也就是版本必須完全相符，或版本不得小於) 提供的值。 此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
**lpszComment** 查詢會忽略這個成員。
**dwNameSpace** 單一命名空間的標識碼，其中要限制搜尋，或 **NS_ALL** 以包含所有命名空間。
**lpNSProviderId** 特定命名空間提供者的 GUID，只限制此提供者的查詢。 此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
**lpszContext** 階層命名空間中查詢的起點。 此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
**dwNumberOfProtocols** 通訊協議條件約束陣列中項目數目的大小，以位元組為單位。 這個成員可以是零。
**lpafpProtocols** AFPROTOCOLS 結構的陣列。 只會傳回使用這些通訊協議的服務。 允許值 **AF_UNSPEC** 顯示為通訊協定系列值，表示通配符。 不論位址系列為何，命名空間提供者都可以提供任何使用對應通訊協定之服務的相關信息。 此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
**lpszQueryString** 某些命名空間 (例如 whois++) 支援簡單文字字串中包含的豐富 SQL 類似查詢。 此參數是用來指定該字串。此成員是選擇性的，取決於 NSPv2 服務提供者的需求。
**dwNumberOfCsAddrs** 查詢會忽略這個成員。
**lpcsaBuffer** 查詢會忽略這個成員。
**dwOutputFlags** 查詢會忽略這個成員。
**lpBlob** 提供者特定實體的指標。 此成員是選擇性的，取決於 NSPv2 服務提供者的需求。

規格需求

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

另請參閱

AFPROTOCOLS

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceEnd

NSPv2LookupServiceNextEx

NSPv2SetServiceEx

NSPv2Startup

WSAQUERYSET2

WSASERVICECLASSINFO

WSASetLastError