EvtDeviceSetLock function

[Applies to KMDF only]

A driver's EvtDeviceSetLock event callback function locks the specified device so that it cannot be ejected, or unlocks the device so that it can be ejected.

Syntax

C++


EVT_WDF_DEVICE_SET_LOCK EvtDeviceSetLock;

NTSTATUS EvtDeviceSetLock(
  _In_  WDFDEVICE Device,
  _In_  BOOLEAN IsLocked
)
{ ... }

Parameters

Device [in]: A handle to a framework device object.
IsLocked [in]: A Boolean value that indicates whether the driver must lock or unlock the device. If TRUE, the driver must lock the device so that it cannot be ejected. If FALSE, the driver must unlock the device so that it can be ejected.

Return value

If the driver successfully locks or unlocks the device, it must return STATUS_SUCCESS. Otherwise it must return an NTSTATUS value that NT_SUCCESS evaluates as FALSE.

For more information about this callback function's return values, see Reporting Device Failures.

Remarks

Framework-based bus drivers can provide an EvtDeviceSetLock callback function. To register this callback function, bus drivers call WdfPdoInitSetEventCallbacks.

The framework calls the driver's EvtDeviceSetLock callback function when the PnP manager requests the bus driver to lock or unlock one of its enumerated child devices.

Not implementing an EvtDeviceSetLock callback function for a device is equivalent to returning an NTSTATUS value that evaluates as FALSE.

For more information about return values, see Supporting Ejectable Devices.

Examples

To define an EvtDeviceSetLock callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtDeviceSetLock callback function that is named MyDeviceSetLock, use the EVT_WDF_DEVICE_SET_LOCK type as shown in this code example:


EVT_WDF_DEVICE_SET_LOCK  MyDeviceSetLock;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyDeviceSetLock (
    WDFDEVICE  Device,
    BOOLEAN  IsLocked
    )
  {...}

The EVT_WDF_DEVICE_SET_LOCK function type is defined in the Wdfpdo.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_DEVICE_SET_LOCK function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Minimum KMDF version	1.0
Header	Wdfpdo.h (include Wdf.h)
IRQL	PASSIVE_LEVEL