WdfRegistryQueryMultiString 関数 (wdfregistry.h)

[アーティクル]
02/07/2025

[KMDF と UMDF に適用]

WdfRegistryQueryMultiString メソッドは、指定された複数文字列レジストリ値に現在割り当てられている文字列を取得し、各文字列のフレームワーク文字列オブジェクトを作成し、各文字列オブジェクトを指定したオブジェクトコレクションに追加します。

構文

NTSTATUS WdfRegistryQueryMultiString(
  [in]           WDFKEY                 Key,
  [in]           PCUNICODE_STRING       ValueName,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringsAttributes,
  [in]           WDFCOLLECTION          Collection
);

パラメーター

[in] Key

開かれたレジストリキーを表すレジストリキーオブジェクトへのハンドル。

[in] ValueName

値名を含む UNICODE_STRING 構造体へのポインター。

[in, optional] StringsAttributes

新しい各文字列オブジェクトのオブジェクト属性を含む WDF_OBJECT_ATTRIBUTES 構造体へのポインター。このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[in] Collection

ドライバーが提供するフレームワークコレクションオブジェクトへのハンドル。

戻り値

WdfRegistryQueryMultiString 、操作が成功した場合にSTATUS_SUCCESSを返します。それ以外の場合、メソッドは次のいずれかの値を返す可能性があります。

リターンコード	形容
STATUS_INVALID_DEVICE_REQUEST	IRQL = PASSIVE_LEVEL で WdfRegistryQueryMultiString が呼び出されませんでした。
STATUS_INVALID_PARAMETER	無効なパラメーターが指定されました。
STATUS_INSUFFICIENT_RESOURCES	文字列オブジェクトを割り当てませんでした。
STATUS_ACCESS_DENIED	ドライバーが、KEY_QUERY_VALUE、KEY_READ、またはKEY_ALL_ACCESSアクセス権を持つレジストリキーを開けませんでした。
STATUS_OBJECT_TYPE_MISMATCH	指定された ValueName パラメーターがREG_MULTI_SZされなかったレジストリ値のデータ型。
STATUS_OBJECT_NAME_NOT_FOUND	レジストリ値を使用できませんでした。
STATUS_RESOURCE_DATA_NOT_FOUND	レジストリ値は、指定したキーの下に存在しますが、空です。

WdfRegistryQueryMultiString メソッドが返す可能性があるその他の戻り値の一覧については、「Framework オブジェクト作成エラー」を参照してください。

このメソッドは、他のNTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

備考

ドライバーが WdfRegistryQueryMultiString 呼び出す前に、コレクションオブジェクト作成する WdfCollectionCreate を呼び出す必要があります。

呼び出し元が StringsAttributes パラメーターを指定しない場合、フレームワークによって作成されたすべての WDFSTRING オブジェクトは、既定で WDFDRIVER に親されます。

WdfRegistryQueryMultiString 戻った後、ドライバーは WdfCollectionGetCount を呼び出して取得した文字列の数を取得し、WdfCollectionGetItem をしてコレクションから文字列オブジェクトを取得できます。

ドライバーが WdfRegistryQueryMultiString メソッドを呼び出す前に、コレクションにオブジェクトが含まれている場合、メソッドはこれらのオブジェクトを削除したり、インデックス値を変更したりしません。新しいオブジェクトがコレクションの末尾に追加されます。

文字列オブジェクトから文字列を取得するには、ドライバーは WdfStringGetUnicodeString 呼び出すことができます。

レジストリキーオブジェクトの詳細については、「Framework-Based ドライバーでのレジストリの使用」を参照してください。

例

次のコード例では、コレクションオブジェクトを作成し、コレクションオブジェクトがコレクションに対してフレームワークによって作成されるすべての文字列オブジェクトの親になるように WDF_OBJECT_ATTRIBUTES 構造体を初期化し、複数文字列レジストリ値から文字列を取得します。最後に、フレームワークがコレクションに追加した文字列オブジェクトの数を取得します。

WDF_OBJECT_ATTRIBUTES stringAttributes;
WDFCOLLECTION col;
NTSTATUS status;
ULONG count;
DECLARE_CONST_UNICODE_STRING(valueMultiSz, VALUE_MULTI_SZ);

status = WdfCollectionCreate(
                             NULL,
                             &col
                             );
ASSERT(NT_SUCCESS(status));

WDF_OBJECT_ATTRIBUTES_INIT(&stringAttributes);
stringAttributes.ParentObject = col;

status = WdfRegistryQueryMultiString(
                                     Key,
                                     &valueMultiSzEmpty,
                                     &stringAttributes,
                                     col
                                     );

count = WdfCollectionGetCount(col);

必要条件

要件	価値
ターゲットプラットフォームの	万国
最小 KMDF バージョン	1.0
UMDF の最小バージョンをする	2.0
ヘッダー	wdfregistry.h (Wdf.h を含む)
ライブラリ	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則をする	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

次の方法で共有

WdfRegistryQueryMultiString 関数 (wdfregistry.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース