LPNSPV2LOOKUPSERVICEBEGIN コールバック関数 (ws2spi.h)

  • [アーティクル]

NSPv2LookupServiceBegin 関数は、WSAQUERYSET2構造体に含まれる情報によって制約される名前空間バージョン 2 サービス プロバイダーのクライアント クエリを開始します。

構文

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 。 どちらの場合も、もう 1 つの部分を使用できる必要があります。 このオプションは、サービス インスタンス要求にのみ適用されます。
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 (ゼロ) を返す必要があります。 ルーチン が 失敗し、 WSASetLastError を使用して適切なエラー コードを設定する必要がある場合は、SOCKET_ERROR (つまり 1) を返す必要があります。

エラー コード 意味
WSAEINVAL
 このプロバイダーに対して、1 つ以上のパラメーターが無効であるか、不足しています。
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** を使用してクエリを作成する方法について説明します。 NSPv2 プロバイダーの要件に依存する省略可能なラベルが付いたメンバーは、名前空間プロバイダーによって検索条件として使用されていない場合は、**NULL** ポインターとして指定できます。 詳細については、「 クエリ関連のデータ構造」を参照してください。
メンバー名WSAQUERYSET2 クエリの解釈
**Dwsize** sizeof(WSAQUERYSET2) に設定されます。 これはバージョン管理メカニズムです。
**lpszServiceInstanceName** サービス名を含む文字列。 文字列内のワイルドカードのセマンティクスは定義されていませんが、特定の名前空間プロバイダーでサポートできます。 このメンバーは省略可能であり、NSPv2 サービス プロバイダーの要件に応じて異なります。
**lpVersion** バージョン比較セマンティクスを提供する目的のバージョン番号 (つまり、バージョンが正確に一致する必要がある、または version が指定された値より小さい値ではない必要があります)。 このメンバーは省略可能であり、NSPv2 サービス プロバイダーの要件に応じて異なります。
**lpszComment** このメンバーはクエリでは無視されます。
**dwNameSpace** 検索を制限する 1 つの名前空間の識別子。すべての名前空間を含めるには **NS_ALL**。
**lpNSProviderId** クエリをこのプロバイダーのみに制限する特定の名前空間プロバイダーの GUID。 このメンバーは省略可能であり、NSPv2 サービス プロバイダーの要件に応じて異なります。
**lpszContext** 階層型名前空間内のクエリの開始点。 このメンバーは省略可能であり、NSPv2 サービス プロバイダーの要件に応じて異なります。
**dwNumberOfProtocols** プロトコル制約配列内のエントリ数のサイズ (バイト単位)。 このメンバーは 0 にすることができます。
**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