LPNSPV2LOOKUPSERVICEBEGIN

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

ルーチンが成功した場合、この関数は NO_ERROR (ゼロ) を返します。ルーチンが失敗した場合は SOCKET_ERROR (つまり 1) を返し、 WSASetLastError を使用して適切なエラー コードを設定する必要があります。

NSPv2LookupServiceBegin 関数は、Windows Vista 以降で利用できるネームスペース サービス プロバイダー バージョン 2 (NSPv2) アーキテクチャの一部として使用されます。

Windows Vista および Windows Server 2008 では、NSPv2LookupServiceBegin 関数は NS_EMAIL ネームスペース プロバイダーに対する操作にのみ使用できます。

            <a href="/windows/desktop/api/ws2spi/nc-ws2spi-lpnsplookupservicebegin">NSPv2LookupServiceBegin</a> 関数はハンドルのみを返します。実際の結果を取得するには、以降の

NSPv2LookupServiceNextEx の呼び出しでこのハンドルを使用します。この操作は取り消せないため、短時間で実行されるように実装してください。ネットワーク クエリを開始することは差し支えありませんが、この関数は正常に復帰するために応答を待つ必要がないようにしてください。

NSPv2Startup 関数は、新しいクライアント プロセスがネームスペース プロバイダーの使用を開始するたびに呼び出されます。プロバイダーは、ppvClientSessionArg パラメーターが指すクライアント セッション引数を使用して、このセッションに関する情報を格納できます。NSPv2Startup 関数の呼び出しでクライアント セッション引数に値が指定されていた場合、同じクライアント セッション引数が NSPv2LookupServiceBegin 関数の lpvClientSessionArg パラメーターに渡されます。

呼び出しで 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 ポインターとして指定できます。詳細については、クエリ関連のデータ構造を参照してください。