Win32 API 日本語リファレンス
ホーム › Networking.WinSock › LPNSPV2LOOKUPSERVICENEXTEX

LPNSPV2LOOKUPSERVICENEXTEX

コールバック

シグネチャ

void LPNSPV2LOOKUPSERVICENEXTEX(
    HANDLE hAsyncCall,
    HANDLE hLookup,
    DWORD dwControlFlags,
    DWORD* lpdwBufferLength,
    WSAQUERYSET2W* lpqsResults
);

パラメーター

フィールド型説明
hAsyncCallHANDLE非同期呼び出しに使用される、 NSPv2LookupServiceBegin の前回の呼び出しから返されたハンドルです。
hLookupHANDLENSPv2LookupServiceBegin の前回の呼び出しから返されたハンドルです。
dwControlFlagsDWORD次の操作を制御するために使用されるフラグです。現在は、大きすぎる結果セットを処理する手段として LUP_FLUSHPREVIOUS のみが定義されています。アプリケーションが十分な大きさのバッファーを用意できない場合、LUP_FLUSHPREVIOUS を設定すると、大きすぎた直前の結果セットを破棄し、この呼び出しで次のセットへ進むようプロバイダーに指示します。
lpdwBufferLengthDWORD*入力時は、lpqsResults が指すバッファーに含まれるサイズ (バイト単位) です。出力時は、関数が失敗してエラーが WSAEFAULT の場合、レコードを取得するために lpqsResults に渡す必要がある最小サイズ (バイト単位) が格納されます。
lpqsResultsWSAQUERYSET2W*戻り時に 1 つの結果セットが WSAQUERYSET2 構造体として格納されるメモリ ブロックへのポインターです。

公式ドキュメント

NSPv2LookupServiceNextEx 関数は、 NSPv2LookupServiceBegin の前回の呼び出しでハンドルを取得した後に呼び出され、ネームスペース バージョン 2 のサービス プロバイダーから要求された情報を取得します。

戻り値

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

エラー コード 意味
WSA_E_CANCELLED
 この呼び出しの処理中に NSPv2LookupServiceEnd が呼び出されました。呼び出しはキャンセルされました。lpqsResults バッファー内のデータは未定義です。

Windows Sockets 2 では、WSAECANCELLED (10103) と WSA_E_CANCELLED (10111) という競合するエラー コードが定義されています。エラー コード WSAECANCELLED は将来のバージョンで削除され、WSA_E_CANCELLED のみが残ります。ネームスペース プロバイダーは、可能な限り広範なアプリケーションとの互換性を維持するために WSA_E_CANCELLED エラー コードを使用してください。
WSA_E_NO_MORE
 利用可能なデータはこれ以上ありません。

Windows Sockets 2 では、WSAENOMORE (10102) と WSA_E_NO_MORE (10110) という競合するエラー コードが定義されています。エラー コード WSAENOMORE は将来のバージョンで削除され、WSA_E_NO_MORE のみが残ります。ネームスペース プロバイダーは、可能な限り広範なアプリケーションとの互換性を維持するために WSA_E_NO_MORE エラー コードを使用してください。
WSAEFAULT
 lpqsResults バッファーが小さすぎて WSAQUERYSET セットを格納できませんでした。
WSAEINVAL
 このプロバイダーにとって、1 つ以上のパラメーターが無効であるか、不足しています。
WSA_INVALID_HANDLE
 指定された検索ハンドルが無効です。
WSANO_DATA
 名前はデータベース内で見つかりましたが、指定された制限に一致するデータは見つかりませんでした。
WSASERVICE_NOT_FOUND
 サービスが不明です。指定されたネームスペース内にサービスが見つかりません。
WSA_NOT_ENOUGH_MEMORY
 この操作を実行するための十分なメモリがありません。

解説(Remarks)

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

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

プロバイダーは、lpqsResults バッファーに WSAQUERYSET2 構造体を渡します。クライアントは、すべての WSAQUERYSET2 構造体が返されたことを示す WSA_E_NOMORE が返されるまで、NSPv2LookupServiceNextEx 関数を呼び出してください。

この関数で指定される dwControlFlags と、 NSPv2LookupServiceBegin の時点で指定されたものは、組み合わせの観点では「制限」として扱われます。制限は、 NSPv2LookupServiceBegin 時のものと NSPv2LookupServiceNextEx 時のものとの間で結合されます。したがって、 NSPv2LookupServiceNextEx でのフラグによって、 NSPv2LookupServiceBegin で要求された範囲を超えて返されるデータが増えることはありません。ただし、より多くの、またはより少ないフラグを指定してもエラーにはなりません。ある NSPv2LookupServiceNextEx で指定されたフラグは、その呼び出しにのみ適用されます。

dwControlFlags の LUP_FLUSHPREVIOUS と LUP_RES_SERVICE は、制限を結合する規則の例外です (これらは「制限」フラグではなく動作フラグであるため)。いずれかのフラグが NSPv2LookupServiceNextEx で使用された場合、 NSPv2LookupServiceBegin における同じフラグの設定に関係なく、定義された効果を持ちます。

たとえば、 NSPv2LookupServiceBegin で LUP_RETURN_VERSION が指定されている場合、サービス プロバイダーはバージョンを含むレコードを取得します。 NSPv2LookupServiceNextEx で LUP_RETURN_VERSION が指定されていない場合、バージョンが利用可能であっても、返される情報にバージョンは含まれません。エラーは発生しません。

もう 1 つの例として、 NSPv2LookupServiceBegin で LUP_RETURN_BLOB が指定されておらず、 NSPv2LookupServiceNextEx で指定された場合、返される情報にプライベート データは含まれません。エラーは発生しません。

NSPv2LookupServiceNextEx 関数は、通常少なくとも 2 回呼び出されます。1 回目は lpqsResults パラメーターが指す WSAQUERYSET2 を受け取るために必要なバッファーのサイズを取得するため、2 回目は実際のクエリ結果セットを取得するためです。1 回目の呼び出しでは、NSPv2 プロバイダーは WSAQUERYSET2 の結果に必要なサイズを返します。

返される lpqsResults パラメーターが指す WSAQUERYSET2 構造体は、同じプロセス コンテキスト内でのみ有用です。これは、WSAQUERYSET2 構造体のいくつかのメンバーが、返される実際のデータへのポインターを含んでいるためです。クエリ結果を (たとえば RPC を使用して) 別のプロセスに渡す必要がある場合は、WSAQUERYSET2 構造体のメンバーが指すデータも含めて、lpqsResults パラメーターが指す WSAQUERYSET2 構造体で返されたデータをシリアル化してマーシャリングする必要があります。データは、プロセス境界を越えて渡せる形式でシリアル化する必要があります。WSAQUERYSET2 構造体のコピーを渡すだけでは不十分です。データへのポインターのみが渡され、実際のデータは他のプロセスから利用できないためです。

クエリ結果

次の表は WSAQUERYSET2 を示し、クエリ結果が **WSAQUERYSET2** 構造体でどのように表現されるかを説明します。詳細については、クエリ関連のデータ構造を参照してください。
WSAQUERYSET2 のメンバー名 結果の解釈
**dwSize** WSAQUERYSET2 構造体のサイズ (バイト単位) です。これはバージョン管理の仕組みとして使用されます。
**lpszServiceInstanceName** サービス名を含む文字列です。
**lpVersion** 特定のサービス インスタンスのバージョン番号を参照します。
**lpszComment** サービス インスタンスによって提供されるコメント文字列です。このメンバーは省略可能であり、NSPv2 サービス プロバイダーの要件に依存します。
**dwNameSpace** 名前またはサービス インスタンスが見つかったネームスペースの識別子です。
**lpNSProviderId** このクエリ結果を提供した特定のネームスペース プロバイダーです。
**lpszContext** 階層型ネームスペースにおいて、そのサービスが位置するコンテキスト ポイントです。
**dwNumberOfProtocols** このメンバーは結果に対しては未定義です。
**lpafpProtocols** このメンバーは結果に対しては未定義です。必要なプロトコル情報はすべて CSADDR_INFO 構造体に含まれます。
**lpszQueryString** dwControlFlags に **LUP_RETURN_QUERY_STRING** が含まれる場合、このメンバーは、元のクエリで指定された **lpszServiceInstanceName** のうち解析されずに残った部分を返します。たとえば、ホスト名とそのホスト内のファイル パスを指定する階層的な名前でサービスを識別するネームスペースでは、返されるアドレスはホスト アドレスとなり、解析されずに残った部分はファイル パスとなる場合があります。**lpszServiceInstanceName** が完全に解析され、かつ **LUP_RETURN_QUERY_STRING** が使用されている場合、このメンバーは null になるか、長さ 0 の文字列を指します。
**dwNumberOfCsAddrs** CSADDR_INFO 構造体の配列に含まれる要素数です。
**lpcsaBuffer** CSADDR_INFO 構造体の配列へのポインターです。各要素には 1 つの完全なトランスポート アドレスが含まれます。
**dwOutputFlags** **RESULT_IS_ALIAS** フラグは、これがエイリアスの結果であることを示します。
**lpBlob** プロバイダー固有のエンティティへのポインターです。このメンバーは省略可能であり、NSPv2 サービス プロバイダーの要件に依存します。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)