WdfDeviceCreate 함수(wdfdevice.h)

아티클
08/08/2023

[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에서 반환할 수 있는 다른 반환 값 목록은 프레임워크 개체 만들기 오류를 참조하세요.

메서드는 다른 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 이러한 콜백 함수를 호출합니다.

디바이스 개체를 만드는 방법에 대한 자세한 내용은 프레임워크 디바이스 개체 만들기를 참조하세요.

예제

다음 코드 예제에서는 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
머리글	wdfdevice.h(Wdf.h 포함)
라이브러리	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)