Expand Minimize

WdfControlDeviceInitAllocate method

[Applies to KMDF only]

The WdfControlDeviceInitAllocate method allocates a WDFDEVICE_INIT structure that a driver uses when creating a new control device object.

Syntax


PWDFDEVICE_INIT WdfControlDeviceInitAllocate(
  [in]  WDFDRIVER Driver,
  [in]  const UNICODE_STRING *SDDLString
);

Parameters

Driver [in]

A handle to a framework driver object.

SDDLString [in]

A pointer to a UNICODE_STRING structure that describes a Unicode string. This string is a Security Descriptor Definition Language (SDDL) representation of a security descriptor. For more information, see the following Remarks section.

Return value

WdfControlDeviceInitAllocate returns a pointer to a framework-allocated WDFDEVICE_INIT structure, if the operation succeeds. Otherwise, the method returns NULL.

Remarks

If you want your driver to create a control device object, the driver must call WdfControlDeviceInitAllocate to obtain a WDFDEVICE_INIT structure that it can pass to WdfDeviceCreate.

Your driver can specify a security setting by using a subset of SDDL. The Wdmsec.h file defines a set of SDDL_DEVOBJ_Xxx-formatted constants that you can use. For more information about security descriptors and SDDL, see Securing Device Objects.

The WdfDeviceInitAssignSDDLString method overwrites the security setting, if any, that WdfControlDeviceInitAllocate specifies.

For more information about calling WdfControlDeviceInitAllocate, see Using Control Device Objects.

Examples

The following code example allocates a DEVICE_INIT structure, assigns a device object name, registers a shutdown notification callback function, and creates a control device object. For a more complex example that uses WdfControlDeviceInitAllocate, see the NONPNP sample driver or the NDISProt sample driver.


PWDFDEVICE_INIT  deviceInit = NULL;
NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  objectAttribs;

deviceInit = WdfControlDeviceInitAllocate(
                                          hDriver,
                                          &SDDL_DEVOBJ_SYS_ALL_ADM_RWX_WORLD_RW_RES_R
                                          );
if (deviceInit == NULL) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    goto Error;
}
status = WdfDeviceInitAssignName(
                                 deviceInit,
                                 &ntDeviceName
                                 );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlDeviceInitSetShutdownNotification(
                                            deviceInit,
                                            EvtShutdownNotification,
                                            WdfDeviceShutdown
                                            );
WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);

status = WdfDeviceCreate(
                         &deviceInit,
                         &objectAttribs,
                         &controlDevice
                         );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlFinishInitializing(controlDevice);

Requirements

Minimum KMDF version

1.0

Header

Wdfcontrol.h (include Wdf.h)

Library

Wdf01000.sys (see Framework Library Versioning.)

IRQL

PASSIVE_LEVEL

DDI compliance rules

ControlDeviceInitAPI, CtlDeviceFinishInitDeviceAdd, CtlDeviceFinishInitDrEntry, DriverCreate, InitFreeDeviceCallback, InitFreeDeviceCreate, InitFreeDeviceCreateType2, InitFreeDeviceCreateType4, KmdfIrql, KmdfIrql2

See also

WDF_OBJECT_ATTRIBUTES_INIT
WDFDEVICE_INIT
WdfControlFinishInitializing
WdfDeviceInitAssignName
WdfControlDeviceInitSetShutdownNotification
WdfDeviceCreate
WdfDeviceInitAssignSDDLString

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft