WdfCmResourceListInsertDescriptor 関数 (wdfresource.h)

[アーティクル]
08/08/2023

[KMDF にのみ適用]

WdfCmResourceListInsertDescriptor メソッドは、指定したリソースリストにリソース記述子を挿入します。

構文

NTSTATUS WdfCmResourceListInsertDescriptor(
  [in] WDFCMRESLIST                    List,
  [in] PCM_PARTIAL_RESOURCE_DESCRIPTOR Descriptor,
  [in] ULONG                           Index
);

パラメーター

[in] List

デバイスのハードウェアリソースの一覧を表すフレームワークリソースリストオブジェクトへのハンドル。

[in] Descriptor

ハードウェアリソースを記述する CM_PARTIAL_RESOURCE_DESCRIPTOR 構造体へのポインター。

[in] Index

List が指定する論理構成のインデックスとして使用される 0 から始まる値。リソース一覧の末尾にリソース記述子を追加するには、WDF_INSERT_AT_ENDまたは WdfCmResourceListGetCount からの戻り値を指定します。

戻り値

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

リターンコード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが指定されました。
STATUS_ACCESS_DENIED	ドライバーは、List パラメーターが指定した論理構成に記述子を追加できませんでした。たとえば、ドライバーは、その EvtDevicePrepareHardware または EvtDeviceReleaseHardware コールバック関数が受信した論理構成を変更できませんでした。
STATUS_INSUFFICIENT_RESOURCES	フレームワークでは、 Descriptor パラメーターが指す記述子を格納する領域を割り当てませんでした。
STATUS_ARRAY_BOUNDS_EXCEEDED	Index パラメーターが指定した値が大きすぎます。

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

注釈

WdfCmResourceListInsertDescriptor メソッドは、Index 値が識別するリソース記述子の前に、List が指定するリソースリストに Descriptor が指定するリソース記述子を挿入します。

リソースリストの末尾にリソース記述子を追加するには、WDF_INSERT_AT_ENDまたは WdfCmResourceListGetCount からの戻り値を Index 値として指定します。または、 WdfCmResourceListAppendDescriptor メソッドを使用します。

フレームワークは、CM_PARTIAL_RESOURCE_DESCRIPTOR 構造体の内容を内部ストレージにコピーするため、 WdfCmResourceListInsertDescriptor を呼び出すドライバールーチンは、構造体をローカルに割り当てることができます。ドライバーは 、WdfCmResourceListInsertDescriptor を呼び出した後、CM_PARTIAL_RESOURCE_DESCRIPTOR構造体を再利用できます。

リソースリストの詳細については、「 Framework-Based ドライバーのハードウェアリソース」を参照してください。

例

次のコード例では、 EvtDeviceResourcesQuery コールバック関数が受け取るリソースリストの末尾にリソース記述子を追加します。

NTSTATUS
PdoEvtDeviceResourcesQuery(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  Resources
    )
{
    CM_PARTIAL_RESOURCE_DESCRIPTOR newDescriptor;
...
    newDescriptor.Type = CmResourceTypePort;
    newDescriptor.ShareDisposition = CmResourceShareDeviceExclusive;
    newDescriptor.Flags = CM_RESOURCE_PORT_IO|CM_RESOURCE_PORT_16_BIT_DECODE;
    newDescriptor.u.Port.Length = 1;
    newDescriptor.u.Port.Start = 0;

    status = WdfCmResourceListInsertDescriptor(
                                               Resources,
                                               &newDescriptor,
                                               WDF_INSERT_AT_END
                                               );
...

}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfresource.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)