次の方法で共有

WdfWorkItemCreate 関数 (wdfworkitem.h)

  • [アーティクル]

[KMDF と UMDF に適用]

WdfWorkItemCreate メソッドは、フレームワークの作業項目オブジェクトを作成します。このオブジェクトは、その後、システムの作業項目キューに追加できます。

構文

NTSTATUS WdfWorkItemCreate(
  [in]  PWDF_WORKITEM_CONFIG   Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFWORKITEM            *WorkItem
);

パラメーター

[in] Config

呼び出し元によって割り当てられた WDF_WORKITEM_CONFIG 構造体へのポインター。ドライバーは 、WDF_WORKITEM_CONFIG_INITを呼び出すことによって既に初期化されている必要があります。

[in] Attributes

作業項目オブジェクトの属性を指定する呼び出し元によって割り当てられた WDF_OBJECT_ATTRIBUTES 構造体へのポインター。

[out] WorkItem

新しい作業項目オブジェクトへのハンドルを受け取る変数へのポインター。

戻り値

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

リターン コード 説明
STATUS_INVALID_PARAMETER
 無効なパラメーターが指定されました。
STATUS_INVALID_DEVICE_REQUEST
 作業項目オブジェクトの親は、デバイス オブジェクトまたはデバイス オブジェクトの先祖ではありません。
STATUS_INSUFFICIENT_RESOURCES
 作業項目オブジェクトを作成するためのシステム リソースが不足していました。
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL
 Config パラメーターが指すWDF_WORKITEM_CONFIG構造体の AutomaticSerialization メンバーは TRUE ですが、親オブジェクトの実行レベルは WdfExecutionLevelPassive ではありません。
STATUS_WDF_PARENT_NOT_SPECIFIED
 Attributes パラメーターが NULL であるか、Attributes が指定するWDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーが NULL でした。

注釈

ドライバーは WdfWorkItemCreate を呼び出して作業項目を作成した後、通常、アイテム固有の情報を作業項目オブジェクトのコンテキスト メモリに格納します。 作業項目のタスクを実行するドライバーの EvtWorkItem コールバック関数は、この情報にアクセスして、実行する必要があるタスクを決定できます。 (コンテキスト メモリに情報を格納する方法の詳細については、「 Framework オブジェクト コンテキスト空間」を参照してください)。

作業項目情報を格納した後、ドライバーは WdfWorkItemEnqueue を呼び出して、作業項目をシステムの作業項目キューに追加する必要があります。 システム ワーカー スレッドが使用可能になると、スレッドはキューから作業項目を削除し、 EvtWorkItem コールバック関数を呼び出します。

ドライバーは、作業項目オブジェクトを作成するときに、WDF_OBJECT_ATTRIBUTES構造体のParentObject メンバー内の作業項目オブジェクトの親オブジェクトを指定する必要があります。 親オブジェクトは、フレームワーク デバイス オブジェクト、または親のチェーンがフレームワーク デバイス オブジェクトにつながる任意のオブジェクトである必要があります。 フレームワークは、デバイス オブジェクトを削除すると、作業項目オブジェクトを削除します。

前に作業項目オブジェクトを削除するには、「フレームワーク作業項目の使用」の説明に従って、ドライバーは WdfObjectDelete を呼び出すことができます。

ドライバーは 、WdfWorkItemGetParentObject を呼び出すことによって、作業項目の親オブジェクトを取得できます。

ドライバーが作業項目オブジェクト の EvtCleanupCallback または EvtDestroyCallback コールバック関数を提供する場合、フレームワークは IRQL = PASSIVE_LEVEL でこれらのコールバック関数を呼び出します。

作業項目の詳細については、「フレームワーク作業項目の 使用」を参照してください。

例

次のコード例では、 WDF_OBJECT_ATTRIBUTES 構造体を初期化し、 WDF_WORKITEM_CONFIG 構造体を初期化し、 WdfWorkItemCreate を呼び出します。

NTSTATUS  status = STATUS_SUCCESS;
PWORKER_ITEM_CONTEXT  context;
WDF_OBJECT_ATTRIBUTES  attributes;
WDF_WORKITEM_CONFIG  workitemConfig;
WDFWORKITEM  hWorkItem;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &attributes,
                                       WORKER_ITEM_CONTEXT
                                       );
attributes.ParentObject = FdoData->WdfDevice;

WDF_WORKITEM_CONFIG_INIT(
                         &workitemConfig,
                         CallbackFunction
                         );

status = WdfWorkItemCreate(
                            &workitemConfig,
                            &attributes,
                            &hWorkItem
                            );
if (!NT_SUCCESS(status)) {
    return status;
}

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header wdfworkitem.h (Wdf.h を含む)
Library Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)

こちらもご覧ください

WdfWorkItemEnqueue