Methods, Properties, and Events
Methods are functions that perform an action on an object, such as creating or deleting the object. KMDF methods are named according to the following pattern:
where Object specifies the KMDF object on which the method operates, and Operation indicates what the method does. For example, the WdfDeviceCreate method creates a framework device object.
Properties are functions that read and write data fields in an object, thus defining object behavior and defaults. Properties are named according to the following pattern:
where Object specifies the KMDF object on which the function operates, and Data specifies the field that the function reads or writes. Some properties can be read and written without failure, but others can sometimes fail. Functions with Set and Get in their names read and write fields without failure. The Set functions return VOID, and the Get functions typically return the value of the field. Functions with Assign and Retrieve in their names read and write fields but can fail. These functions return an NTSTATUS value.
For example, the WDFINTERRUPT object represents the interrupt object for a device. Each interrupt object is described by a set of characteristics that indicate the type of interrupt (message-signaled or IRQ-based) and provide additional information about the interrupt. The WdfInterruptGetInfo method returns this information. No corresponding method to set the value is available, because the driver initializes this information when it creates the interrupt object and cannot change it during device operation.
Events represent runtime states to which a driver can respond or during which a driver can participate. A driver registers callbacks only for the events that are important to its operation. When the event occurs, the framework invokes the callback, passing as a parameter a handle to the object for which the callback is registered. For example, the ejection of a device is a Plug and Play event. If a device can be ejected, its driver registers an EvtDeviceEject callback routine, which performs device-specific operations upon ejection. KMDF calls this routine with a handle to the device object when the Plug and Play manager sends an IRP_MN_EJECT request for the device. If the device cannot be ejected, the driver doesn't require such a callback.
For most events, a driver can either provide a callback routine or allow KMDF to perform a default action in response. For a few events, however, a driver-specific callback is required. For example, adding a device is an event for which every Plug and Play driver must include a callback. The driver's EvtDriverDeviceAdd callback creates the device object and sets device attributes.
KMDF events are not related to the kernel-dispatcher events that Windows provides as synchronization mechanisms. A driver cannot create, manipulate, or wait on a KMDF event. Instead, the driver registers a callback for the event, and KMDF calls the driver when the event occurs. (For time-related waits, KMDF provides a timer object.)