WdfDeviceCreate 関数 (wdfdevice.h)

[KMDF と UMDF に適用されます]

WdfDeviceCreate メソッドは、フレームワーク デバイス オブジェクトを作成します。

構文

NTSTATUS WdfDeviceCreate(
  [in, out]      PWDFDEVICE_INIT        *DeviceInit,
  [in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
  [out]          WDFDEVICE              *Device
);

パラメーター

[in, out] DeviceInit

WDFDEVICE_INIT構造体へのポインターのアドレス。 WdfDeviceCreate でエラーが発生しない場合は、ポインターを NULL に設定します。

[in, optional] DeviceAttributes

新しいオブジェクトの属性を含む呼び出し元によって割り当てられた WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 (構造体の ParentObject メンバーは NULL である必要があります)。このパラメーターは省略可能で、WDF_NO_OBJECT_ATTRIBUTESできます。

[out] Device

新しいフレームワーク デバイス オブジェクトへのハンドルを受け取る場所へのポインター。

戻り値

WdfDeviceCreate メソッドでエラーが発生しない場合は、STATUS_SUCCESSが返されます。 その他の戻り値は次のとおりです。

リターン コード 説明
STATUS_INVALID_PARAMETER
無効な Device または DeviceInit ハンドルが指定されています。
STATUS_INVALID_DEVICE_STATE
ドライバーは、デバイスのデバイス オブジェクトを既に作成しています。
STATUS_INVALID_SECURITY_DESCR
WdfDeviceInitAssignSDDLString または WdfDeviceInitSetDeviceClass というドライバーが、デバイス オブジェクトの名前を指定しませんでした。
STATUS_INSUFFICIENT_RESOURCES
デバイス オブジェクトを割り当てませんでした。
STATUS_OBJECT_NAME_COLLISION
WdfDeviceInitAssignName の呼び出しによって指定されたデバイス名が既に存在します。 ドライバーは 、WdfDeviceInitAssignName をもう一度呼び出して新しい名前を割り当てることができます。
 

WdfDeviceCreate が返すことができるその他の戻り値の一覧については、「 Framework オブジェクト作成エラー」を参照してください。

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

注釈

WdfDeviceCreate を呼び出す前に、ドライバーは、WDFDEVICE_INIT構造体を初期化するフレームワーク提供の関数を呼び出す必要があります。 この構造体の初期化の詳細については、 WDFDEVICE_INITを参照してください。 初期化関数の呼び出し中にドライバーでエラーが発生した場合は、 WdfDeviceCreate を呼び出してはなりません。 この場合、ドライバーは WdfDeviceInitFree を呼び出す必要があります。 WdfDeviceInitFree を呼び出すタイミングについては、「WdfDeviceInitFree」を参照してください。

WdfDeviceCreate を呼び出すと、機能デバイス オブジェクト (FDO) または物理デバイス オブジェクト (PDO) を表すフレームワーク デバイス オブジェクトが作成されます。 関数が作成するデバイス オブジェクトの種類は、ドライバーがWDFDEVICE_INIT構造体を取得した方法によって異なります。

  • ドライバーが EvtDriverDeviceAdd コールバックからWDFDEVICE_INIT構造体を受け取った場合、 WdfDeviceCreate は FDO を作成します。
  • ドライバーが EvtChildListCreateDevice コールバックから、または WdfPdoInitAllocate への呼び出しから、WDFDEVICE_INIT構造体を受信した場合、 WdfDeviceCreate は PDO を作成します。
ドライバーが WdfDeviceCreate を呼び出した後、WDFDEVICE_INIT構造体にアクセスできなくなります。

フレームワークを使用するミニポート ドライバーは 、WdfDeviceCreate ではなく WdfDeviceMiniportCreate を呼び出 必要があります。

各フレームワーク デバイス オブジェクトの親は、ドライバーのフレームワーク ドライバー オブジェクトです。 ドライバーはこの親を変更できず、WDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーは NULL である必要があります。 プラグ アンド プレイ (PnP) マネージャーがデバイスが削除されたと判断すると、フレームワークは各フレームワーク デバイス オブジェクト (一部のコントロール デバイス オブジェクトを除く) を削除します。

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

デバイス オブジェクトの作成の詳細については、「 Framework デバイス オブジェクトの作成」を参照してください。

次のコード例は、 EvtDriverDeviceAdd コールバック関数がデバイス オブジェクトを初期化して作成する方法を示しています。

NTSTATUS
MyEvtDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_PNPPOWER_EVENT_CALLBACKS  pnpPowerCallbacks;
    WDF_OBJECT_ATTRIBUTES  attributes;
    NTSTATUS  status;
    WDFDEVICE  device;
 
    //
    // Initialize the WDF_PNPPOWER_EVENT_CALLBACKS structure.
    //
    WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
    pnpPowerCallbacks.EvtDevicePrepareHardware = MyEvtDevicePrepareHardware;
    pnpPowerCallbacks.EvtDeviceD0Entry = MyEvtDeviceD0Entry;
    pnpPowerCallbacks.EvtDeviceD0Exit  = MyEvtDeviceD0Exit;
    WdfDeviceInitSetPnpPowerEventCallbacks(
                                           DeviceInit,
                                           &pnpPowerCallbacks
                                           );
    //
    // This driver uses buffered I/O.
    //
    WdfDeviceInitSetIoType(
                           DeviceInit,
                           WdfDeviceIoBuffered
                           );
 
    //
    // Specify the device object's context space by
    // using a driver-defined DEVICE_CONTEXT structure.
 //
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                            &attributes,
                                            DEVICE_CONTEXT
                                            );
 //
    // Create the device object.
    //
    status = WdfDeviceCreate(
                             &DeviceInit,
                             &attributes,
                             &device
                             );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    return STATUS_SUCCESS;
}

要件

   
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header wdfdevice.h (Wdf.h を含む)
Library Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 AccessHardwareKey(kmdf)AddPdoToStaticChildList(kmdf)ChangeQueueState(kmdf)ChildDeviceInitAPI(kmdf)ChildListConfiguration(kmdf)ControlDeviceDeleted(kmdf)ControlDeviceInitAllocate(kmdf)ControlDeviceInitAPI(kmdf)CtlDeviceFinishInitDeviceAdd(kmdf)CtlDeviceFinishInitDrEntry(kmdf)DeviceCreateFail(kmdf)DeviceInitAllocate(kmdf)DeviceInitAPI(kmdf)DriverCreate(kmdf)InitFreeDeviceCreate(kmdf)InitFreeDeviceCreateType2(kmdf)InitFreeDeviceCreateType4(kmdf)InitFreeNull(kmdf)KmdfIrql(kmdf)KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 PdoDeviceInitAPI(kmdf)PdoInitFreeDeviceCreate(kmdf)PdoInitFreeDeviceCreateType2(kmdf)PdoInitFreeDeviceCreateType4(kmdf)

こちらもご覧ください

WDFDEVICE_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WDF_PNPPOWER_EVENT_CALLBACKS_INIT

WdfDeviceInitFree

WdfDeviceInitSetIoType

WdfDeviceInitSetPnpPowerEventCallbacks

WdfDeviceMiniportCreate