LPNSPLOOKUPSERVICEBEGIN 回呼函式 (ws2spi.h)

  • 發行項

NSPLookupServiceBegin函式會起始名稱服務提供者的用戶端查詢，此查詢受限於WSAQUERYSET結構中包含的資訊。

NSPLookupServiceBegin 只會傳回控制碼，以供 後續對 NSPLookupServiceNext 的呼叫使用，以取得實際的結果。 由於無法取消此作業，因此應該實作以快速執行。 雖然可以接受起始網路查詢，但此函式不應要求回應成功傳回。

語法

LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;

INT Lpnsplookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in]  DWORD dwControlFlags,
  [out] LPHANDLE lphLookup
)
{...}

參數

[in] lpProviderId

要查詢的名稱服務提供者識別碼指標。

[in] lpqsRestrictions

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

[in] lpServiceClassInfo

WSASERVICECLASSINFO結構的指標，其中包含服務的架構資訊。

[in] dwControlFlags

值，控制搜尋的深度。

值 意義
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
 任何可用的別名資訊都會在 對 NSPLookupServiceNext的後續呼叫中傳回，而傳回的每個別名都會設定 **RESULT_IS_ALIAS** 旗標。
LUP_RETURN_QUERY_STRING
0x0800
 將查詢字串擷取為 **lpszQueryString**。
LUP_RETURN_ALL
0x0ff0
 擷取資訊，包括名稱、類型、版本、批註、位址、Blob、別名和查詢字串。
LUP_FLUSHCACHE
0x1000
 如果提供者已快取資訊，請忽略快取並查詢命名空間本身。
LUP_FLUSHPREVIOUS
0x2000
 當做NSPLookupServiceNext中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 對應位址的雙模式通訊端) 。

[out] lphLookup

要用於 後續對 NSPLookupServiceNext 之控制碼的指標，以便擷取結果集。

傳回值

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

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

備註

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

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

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

dwStatus = NSPLookupServiceBegin(
    lpqsRestrictions,
    LUP_CONTAINERS,
    lphLookup);

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

形成查詢

如前所述， WSAQUERYSET 結構會當做 NSPLookupServiceBegin 的輸入參數來限定查詢。 下表列出 WSAQUERYSET 成員名稱，並說明 如何使用 WSAQUERYSET 來建構查詢。 當成員標示為 (選擇性) 可以提供 null 指標時，表示參數不會當做搜尋準則使用。 如需詳細資訊，請參閱 查詢相關的資料結構。

WSAQUERYSET 成員名稱 查詢解譯
**dwSize** 將會設定為 sizeof (WSAQUERYSET) 。 這是版本設定機制。
**dwOutputFlags** 已忽略查詢。
**lpszServiceInstanceName** 選擇性。 參考的字串包含服務名稱。 不會定義字串內萬用字元的語意，但特定命名空間提供者可以支援。
**lpServiceClassId** 必要。 對應至服務類別的 GUID。
**lpVersion** 選擇性。 參考所需的版本號碼並提供版本比較語意 (，也就是版本必須完全相符，或版本不得小於) 提供的值。
**lpszComment** 已忽略查詢。
**dwNameSpace** 單一命名空間的識別碼，其中要限制搜尋，或 **NS_ALL** 包含所有命名空間。
**lpNSProviderId** 選擇性。 參考特定命名空間提供者的 GUID，並只限制此提供者的查詢。
**lpszCoNtext** 選擇性。 指定階層命名空間中查詢的起點。
**dwNumberOfProtocols** 在通訊協定條件約束陣列中，大小，以位元組為單位，可以是零。
**lpafpProtocols** 選擇性。 AFPROTOCOLS結構的陣列參考。 只會傳回使用這些通訊協定的服務。 允許值 **AF_UNSPEC** 顯示為通訊協定系列值，表示萬用字元。 不論位址系列為何，命名空間提供者都可以提供任何使用對應通訊協定之服務的相關資訊。
**lpszQueryString** 選擇性。 某些命名空間 (例如 Whois++) 支援簡單文字字串中包含的豐富類似 SQL 查詢。 此參數是用來指定該字串。
**dwNumberOfCsAddrs** 已忽略查詢。
**lpcsaBuffer** 已忽略查詢。
**lpBlob** 選擇性。 提供者特定實體的指標。

規格需求

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

另請參閱

AFPROTOCOLS

NSPLookupServiceEnd

NSPLookupServiceNext

NSP_ROUTINE

WSAQUERYSET

WSASERVICECLASSINFO

WSASetLastError