WSALookupServiceBeginA 関数 (winsock2.h)
WSALookupServiceBegin 関数は、WSAQUERYSET 構造体に含まれる情報によって制約されるクライアント クエリを開始します。 WSALookupServiceBegin はハンドルのみを返します。これは、実際の結果を取得するために 、WSALookupServiceNext の後続の呼び出しで使用する必要があります。
構文
INT WSAAPI WSALookupServiceBeginA(
[in] LPWSAQUERYSETA lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPHANDLE lphLookup
);
パラメーター
[in] lpqsRestrictions
検索条件へのポインター。 詳細については、「解説」を参照してください。
[in] dwControlFlags
検索の深さを制御するフラグのセット。
dwControlFlags パラメーターでサポートされる値は、Winsock2.h ヘッダー ファイルで定義され、次のオプションの組み合わせにすることができます。
| フラグ | 説明 |
|---|---|
|
最初のレベルではなく、深いクエリ。 |
|
コンテナーのみを返します。 |
|
コンテナーを返さないでください。 |
|
可能であれば、 は距離の順序で結果を返します。 距離のメジャーはプロバイダー固有です。 |
|
名前を lpszServiceInstanceName として取得します。 |
|
lpServiceClassId として型を取得します。 |
|
バージョンを lpVersion として取得します。 |
|
コメントを lpszComment として取得します。 |
|
アドレスを lpcsaBuffer として取得します。 |
|
プライベート データを lpBlob として取得します。 |
|
WSALookupServiceNext を連続して呼び出すと、使用可能なエイリアス情報が返され、返される各エイリアスには RESULT_IS_ALIAS フラグが設定されます。 |
|
要求に使用されるクエリ文字列を取得します。 |
|
すべてのLUP_RETURN_* 値を取得するフラグのセット。 |
|
WSALookupServiceNext の dwControlFlags パラメーターの値として使用されます。 このフラグを設定すると、指定したバッファーに対して大きすぎる最後の結果セットを破棄し、次の結果セットに進むようプロバイダーに指示します。 |
|
プロバイダーが情報をキャッシュしている場合、キャッシュは無視され、名前空間自体に対してクエリが実行されます。 |
|
これは、素応答が構造体のリモート部分とローカル部分のどちらにあるかを示 CSADDR_INFO 。 どちらの場合も、もう 1 つの部分を使用できる必要があります。 |
[out] lphLookup
結果セットの取得を開始するために WSALookupServiceNext を呼び出すときに使用するハンドル。
戻り値
操作が成功した場合、戻り値は 0 です。 それ以外の場合は、SOCKET_ERROR値が返され、 WSAGetLastError を呼び出すことによって特定のエラー番号を取得できます。
| エラー コード | 意味 |
|---|---|
| 操作を実行するためのメモリが不足していました。 | |
| このプロバイダーに対して 1 つ以上のパラメーターが見つからないか無効でした。 | |
| データベースで名前が見つかりましたが、指定された制限に一致するデータが見つかりませんでした。 | |
| WS2_32.DLL が初期化されていません。 アプリケーションは、Windows ソケット関数を呼び出す前に、まず WSAStartup を呼び出す必要があります。 | |
|
そのようなサービスは不明です。 指定された名前空間にサービスが見つかりません。
リモート Bluetooth デバイスが見つからなかった場合、Bluetooth サービス検出要求に対してこのエラーが返されます。 |
注釈
lpqsRestrictions パラメーターは、WSAQUERYSET 構造体を含むバッファーを指します。 WSALookupServiceBegin 関数を呼び出す前に、少なくとも WSAQUERYSET の dwSize メンバーをバッファーの長さに設定する必要があります。 アプリケーションでは、 WSAQUERYSET で他のメンバーを指定することで、クエリを制限できます。
ほとんどの場合、特定のトランスポート プロトコルのみに関心があるアプリケーションでは、dwNameSpace メンバー内の名前空間を指定するのではなく、WSAQUERYSET の dwNumberOfProtocols メンバーと lpafpProtocols メンバーを使用して、アドレス ファミリとプロトコルによってクエリを制限する必要があります。
サポートされているネットワーク トランスポート プロトコルに関する情報は、EnumProtocols、WSAEnumProtocols、WSCEnumProtocols、または WSCEnumProtocols32 関数を使用して取得できます。
クエリを 1 つの名前空間に制限することもできます。 たとえば、(ローカル ホスト ファイルやその他の名前付けサービスからの結果ではなく) DNS からの結果のみを求めるクエリでは、 dwNameSpace メンバーがNS_DNSに設定されます。 たとえば、bluetooth デバイス検出では 、dwNameSpace メンバーがNS_BTHに設定されます。
アプリケーションでは、 lpNSProviderId メンバーでプロバイダーの GUID へのポインターを指定することで、クエリを特定の名前空間プロバイダーに制限することもできます。
ローカル コンピューター上の名前空間プロバイダーに関する情報は、 WSAEnumNameSpaceProviders、 WSAEnumNameSpaceProvidersEx、 WSCEnumNameSpaceProviders32、または WSCEnumNameSpaceProvidersEx32 関数を使用して取得できます。
LUP_CONTAINERSが呼び出しで指定されている場合は、他の制限値は避ける必要があります。 いずれかが指定されている場合は、コンテナーに対するこの制限をサポートできるかどうかを決定するのは、名前サービス プロバイダー次第です。 できない場合は、エラーを返す必要があります。
一部の名前サービス プロバイダーには、コンテナーを検索する他の方法があります。 たとえば、コンテナーはすべて既知の型、または一連の既知の型である可能性があるため、それらを検索するためのクエリ制限を作成できます。 コンテナーを検索するためにサービス プロバイダーが持つ名前が他に何であれ、LUP_CONTAINERSとLUP_NOCONTAINERSが優先されます。 そのため、コンテナーを含むクエリ制限が指定されている場合、LUP_NOCONTAINERSを指定すると、コンテナー項目が返されなくなります。 同様に、クエリの制限に関係なく、LUP_CONTAINERSを指定した場合は、コンテナーのみを返す必要があります。 名前空間がコンテナーをサポートせず、LUP_CONTAINERSが指定されている場合は、 単に WSANO_DATA を返す必要があります。
別のコンテナー内のコンテナーを取得する推奨される方法は、 の呼び出しです。
dwStatus = WSALookupServiceBegin(
lpqsRestrictions,
LUP_CONTAINERS,
lphLookup);
この呼び出しの後に、 WSALookupServiceNext 呼び出しの必要な数が続きます。 これにより、開始コンテキスト内にすぐに含まれるすべてのコンテナーが返されます。つまり、ディープ クエリではありません。 これにより、階層を歩くことでアドレス空間構造をマップできます。たとえば、選択したコンテナーの内容を列挙します。 WSALookupServiceBegin の後続の使用では、前の呼び出しから返されたコンテナーが使用されます。
前述のように、 WSAQUERYSET 構造体は、クエリを修飾するために WSALookupBegin への入力パラメーターとして使用されます。 次の表は、 WSAQUERYSET を使用してクエリを作成する方法を示しています。 パラメーターが (省略可能) としてマークされている場合は、パラメーターが検索条件として使用されないことを示す NULL ポインターを指定できます。 詳細については、「 クエリ関連のデータ構造 」セクションを参照してください。
| WSAQUERYSET メンバー | クエリの解釈 |
|---|---|
| dwSize | sizeof(WSAQUERYSET) に設定する必要があります。 これはバージョン管理メカニズムです。 |
| dwOutputFlags | クエリでは無視されます。 |
| lpszServiceInstanceName | (省略可能)参照される文字列には、サービス名が含まれています。 文字列内のワイルドカードのセマンティクスは定義されていませんが、特定の名前空間プロバイダーでサポートできます。 |
| lpServiceClassId | (必須)サービス クラスに対応する GUID。 |
| lpVersion | (省略可能)目的のバージョン番号を参照し、バージョン比較セマンティクスを提供します (つまり、バージョンが正確に一致する必要があります。または、version が指定された値より小さくなければなりません)。 |
| lpszComment | クエリでは無視されます。 |
|
dwNameSpace
次の「重要な注意事項」を参照してください。 |
検索を制限する 1 つの名前空間の識別子。またはすべての名前空間を含むようにNS_ALL。 |
| lpNSProviderId | (省略可能)特定の名前空間プロバイダーの GUID を参照し、クエリをこのプロバイダーのみに制限します。 |
| lpszContext | (省略可能)階層型名前空間内のクエリの開始点を指定します。 |
| dwNumberOfProtocols | プロトコル制約配列のサイズは、0 にすることができます。 |
| lpafpProtocols | (省略可能) AFPROTOCOLS 構造体の配列を参照します。 これらのプロトコルを利用するサービスのみが返されます。 |
| lpszQueryString | (省略可能)一部の名前空間 (whois++など) では、単純なテキスト文字列に含まれるエンリッチされた SQL のようなクエリがサポートされています。 このパラメーターは、その文字列を指定するために使用されます。 |
| dwNumberOfCsAddrs | クエリでは無視されます。 |
| lpcsaBuffer | クエリでは無視されます。 |
| lpBlob | (省略可能)これは、プロバイダー固有のエンティティへのポインターです。 |
Windows 8.1およびWindows Server 2012 R2: WSALookupServiceBeginW 関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストア アプリでサポートされています。
注意
winsock2.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして WSALookupServiceBegin を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8.1、 Windows Vista [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winsock2.h |
| Library | Ws2_32.lib |
| [DLL] | Ws2_32.dll |