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 ヘッダー ファイルで定義されている次の値の組み合わせを指定できます。
| 値 | 意味 |
|---|---|
|
最初のレベルではなく、プロバイダーの階層をクエリダウンします。 |
|
コンテナーのみを返します。 |
|
コンテナーを返しません。 |
|
可能であれば、 は距離の順序で結果を返します。 距離のメジャーはプロバイダー固有です。 |
|
名前を **lpszServiceInstanceName** として取得します。 |
|
型を **lpServiceClassId** として取得します。 |
|
バージョンを **lpVersion** として取得します。 |
|
コメントを **lpszComment** として取得します。 |
|
アドレスを **lpcsaBuffer** として取得します。 |
|
プライベート データを **lpBlob** として取得します。 |
|
NSPv2LookupServiceNextEx を連続して呼び出すと、使用可能なエイリアス情報が返され、返される各エイリアスには **RESULT_IS_ALIAS** フラグが設定されます。 |
|
クエリ文字列を **lpszQueryString** として取得します。 |
|
名前、型、バージョン、コメント、アドレス、BLOB、エイリアス、クエリ文字列などの情報を取得します。 |
|
プロバイダーにキャッシュされた情報がある場合は、キャッシュを無視し、名前空間自体に対してクエリを実行します。 |
|
NSPv2LookupServiceNextEx の dwControlFlags パラメーターの値として使用されます。 このフラグを設定すると、プロバイダーは、指定されたバッファーに対して大きすぎた最後の結果セットを破棄し、次の結果セットに進むよう指示します。 |
|
名前空間プロバイダーに名前の権限のない結果を含める必要があることを示します。 |
|
素数応答が構造体のリモート部分とローカル部分のどちらにあるかを示 CSADDR_INFO 。 どちらの場合も、もう 1 つの部分を使用できる必要があります。 このオプションは、サービス インスタンス要求にのみ適用されます。 |
|
名前空間プロバイダーがセキュリティで保護されたクエリを使用する必要があることを示します。 このオプションは、名前クエリ要求にのみ適用されます。 |
|
名前空間プロバイダーが優先名のみを返す必要があることを示します。 |
|
名前空間プロバイダーがアドレス構成を返す必要があることを示します。 |
|
名前空間プロバイダーがデュアル アドレスを返す必要があることを示します。 このオプションは、デュアルモード ソケット (IPv6 および IPv4 にマップされたアドレス) にのみ適用されます。 |
|
名前空間プロバイダーが国際ドメイン名の自動エンコードを無効にする必要があることを示します。
この値は、Windows 8およびWindows Server 2012でサポートされています |
[out] lpvClientSessionArg
クライアント セッションへのポインター。
[out] lphLookup
結果セットを取得するために NSPv2LookupServiceNextEx の後続の呼び出しで使用されるハンドルへのポインター。
戻り値
ルーチンが成功した場合、関数は NO_ERROR (ゼロ) を返す必要があります。 ルーチン が 失敗し、 WSASetLastError を使用して適切なエラー コードを設定する必要がある場合は、SOCKET_ERROR (つまり 1) を返す必要があります。
| エラー コード | 意味 |
|---|---|
| このプロバイダーに対して、1 つ以上のパラメーターが無効であるか、不足しています。 | |
| 名前がデータベースで見つかりましたが、解決対象の正しいデータが関連付けされていません。 | |
| サービスが不明です。 指定した名前空間にサービスが見つかりません。 | |
| この操作を実行するのに十分なメモリがありません。 |
注釈
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 |