User-Mode Driver Framework

[This is preliminary documentation and subject to change.]

Design Guide

Reference

This is a preliminary document and may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document.

Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2003 – 2006 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Visual Studio, Win32, Windows, Windows NT, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

© 2006 Microsoft Corporation
Send feedback on this topic
Built on May 25, 2006
Build machine: CAPEBUILD


User-Mode Driver Framework Design Guide

The following sections describe the Windows Driver Foundation (WDF) - User-Mode Driver Framework (UMDF) platform:

Introduction to UMDF

Installing UMDF Drivers

Initializing UMDF Drivers

UMDF Driver Tasks

Debugging UMDF Drivers


Introduction to UMDF

The next-generation driver model, the Microsoft Windows Driver Foundation (WDF), contains a framework for the creation of user-mode drivers. The User-Mode Driver Framework (UMDF) provides a unified model that can work across device classes. This framework integrates the installation and management of the devices with standard operating system facilities, such as Plug and Play (PnP) and power management.

The UMDF is designed to support protocol device classes such as cameras and portable music players. Moving drivers for such devices into user mode can simplify the drivers and improve the overall stability of the operating system.

The UMDF is based on the same conceptual driver programming model as the Kernel-Mode Driver Framework (KMDF), which is also part of WDF. However, the two frameworks implement the model with different components, device driver interfaces (DDIs), and data structures.

The UMDF contains a library that you can use to develop user-mode drivers. The library is included in the Microsoft Windows Vista version of the Windows Driver Kit (WDK). You can use the library, and the WDK, to develop drivers that run on Windows Vista and Windows XP. You cannot use the UMDF library to develop user-mode drivers that run on Windows Server 2003 and Windows 2000.

The following topics introduce the UMDF:

Advantages of Writing UMDF Drivers

Devices Supported by the UMDF

Overview of the UMDF

Architecture of the UMDF

UMDF Objects and Interfaces

UMDF Operation and Features


Advantages of Writing UMDF Drivers

UMDF drivers are Plug and Play (PnP) drivers that support protocol or serial bus-based devices. These drivers handle the same types of I/O requests as kernel-mode drivers and are installed by INF files, just as kernel-mode drivers are. However, writing UMDF drivers offers the following advantages (which are discussed further in the topics in this section) over writing kernel-mode drivers:

  • Greater stability and security
  • Expanded operating environments
  • UMDF drivers perform comparably to kernel-mode drivers

In addition, you can:

  • Use the Win32 API with UMDF drivers.
  • Use a user-mode debugger to debug UMDF drivers.
  • Program UMDF drivers in C++ and by using COM.


Greater Stability and Security Using UMDF Drivers

UMDF drivers contribute to greater operating system stability because they have access only to the address space of the process in which they run. Therefore, a corrupt or error-filled UMDF driver might cause its device to be inoperable, but the driver is much less likely to cause system-wide problems. A corrupt kernel-mode driver, however, has access to the system address space and calls kernel-mode functions that the operating system exposes and that directly manipulate important system structures. Errors in a kernel-mode driver can corrupt these structures and possibly cause the computer to fail.

UMDF drivers also contribute to greater operating system security by reducing the risk that is associated with an error-filled or compromised UMDF driver. Because UMDF drivers run under the LocalService account, they have limited access to a user's data or to system files except when they impersonate the client process (for more information about how UMDF handles impersonation, see Handling Impersonation). However, because UMDF drivers are susceptible to the same type of attacks as other services that run under the LocalService account, you should still write your UMDF driver using secure coding techniques and test your driver against attacks that you determine from a thorough threat analysis.


Expanded Environment for UMDF Drivers

The environment that UMDF drivers operate in is expanded from the environment of other user-mode driver models. The UMDF integrates support for Plug and Play (PnP) and power management, so UMDF drivers can participate fully in system-wide operations.

All user-mode drivers operate in a much simpler environment than kernel-mode drivers. Kernel-mode drivers must be programmed to avoid problems that are related to IRQL, page faults, and thread context, for example. In user mode, however, these issues do not exist. User-mode drivers always run in a different thread from the requesting process and can always take page faults.

To take advantage of this simpler environment, user-mode drivers for device groups (such as scanners, printers, cameras, and mobile devices) are developed by using their own user-mode driver models, which have been supported for several releases of the Microsoft Windows operating system. However, these models do not work with the PnP installation mechanism.


Use of the Win32 API by UMDF Drivers

Most application programmers are familiar with the Microsoft Win32 application programming interface (API). UMDF drivers call the Win32 API instead of calling kernel-mode functions. The Win32 API provides access to some services that are not available in kernel mode, such as cryptography. Because the Win32 API is a user-mode component, the operating system performs additional security and verification checks before making changes that a user-mode caller requests.


Debugging UMDF Drivers with a User-Mode Debugger

You can debug UMDF drivers by using a user-mode debugger instead of a kernel-mode debugger. Debugging and driver development in user mode can be faster because an error affects only the current process, not the entire computer, so you do not have to spend time to restart the computer. In addition, user-mode debugging requires only a single computer, whereas kernel-mode debugging requires both a host computer and a target computer. WDF includes several debugger extensions for use with UMDF drivers. For more information about these extensions, see Debugging UMDF Drivers.


Programming UMDF Drivers in C++ and Using COM

The UMDF is designed so that you can write drivers that use the object-oriented features of C++.

The UMDF is based on a subset of the Component Object Model (COM). You can use numerous COM tools, such as the active template library (ATL), to quickly generate code for your driver.


UMDF Drivers Perform Comparably to Kernel Mode Drivers

For the types of devices that UMDF drivers can support, I/O bandwidth is a greater issue than internal driver performance. For such devices, UMDF drivers are comparable in performance to kernel-mode drivers.

For more information about the types of devices that UMDF drivers support, see Devices Supported by the UMDF.


Devices Supported by the UMDF

The UMDF supports the development of drivers for protocol-based or serial bus–based devices, such as USB devices and network-connected devices. For example, you can write drivers for the following types of devices by using the UMDF:

  • Portable storage devices, such as PDAs and cell phones
  • Portable media players
  • USB bulk transfer devices
  • Auxiliary display and video devices

These devices can be directly connected, connected on the network, or connected through a wireless protocol such as Bluetooth.

UMDF drivers can support 32-bit or 64-bit devices for any Microsoft Windows hardware platform and can be distributed on Windows Update.

You cannot write UMDF drivers for drivers that require the following items; such drivers must be written as kernel-mode drivers.

  • Handling interrupts
  • Direct access to the hardware, such as direct memory access (DMA)
  • Strict timing loops
  • Use of nonpaged pool or other resources that are reserved for kernel mode


Overview of the UMDF

The User-Mode Driver Framework (UMDF) architecture allows hardware vendors to create user-mode drivers for their hardware that provides more security and stability to the operating system than kernel-mode drivers. If a kernel-mode driver crashes, then the entire system crashes; if a user-mode driver crashes, then only the process hosting the driver crashes, while the rest of the system remains stable. The UMDF architecture contains the following components:

  • UMDF drivers

    UMDF drivers abstract hardware functionality, run in the user-mode environment, and can access various services. UMDF drivers operate as part of a stack of drivers that manage a device. File system drivers, display drivers, and print drivers cannot be UMDF drivers.

  • Driver host process

    A driver host process contains UMDF drivers, the framework, and a runtime environment for the framework and drivers. The driver host process is isolated from the application process and other driver host processes. The driver host process runs in the LocalService account so that only one stack of drivers per device exists. The device stack consists of function and filter drivers for a particular device. The stack is accessible to applications running in different sessions and provides a central point for arbitrating access to the device. The runtime environment handles I/O dispatching, driver loading, driver layering, thread pool, and messages from the reflector and driver manager.

  • Reflector

    The reflector is a Microsoft Windows Driver Model (WDM) kernel-mode driver that permits an application and a driver host process to communicate. The reflector creates a separate device object for each device instance and handles Plug and Play (PnP) and power I/O requests associated with each device instance. All communication between the application and the driver host process happens through the reflector.

  • Driver manager

    The driver manager can be thought of as an extension to the reflector. The driver manager launches and tracks information about each driver host process, which is a child process of the driver manager. Only one driver manager exists per system. The driver manager starts during installation of the first UMDF device and runs on the system thereafter.

Similar to the kernel-mode driver framework (KMDF), the UMDF provides an event-driven driver model for UMDF drivers. UMDF drivers are stackable in a driver host process. UMDF drivers are loaded on behalf of device nodes enumerated in the PnP device tree. When a request is sent to a device, it travels from the top of the device stack down to the physical device. Each layer of the stack can contribute to the request as the request travels through the stack.

Each driver in a stack provides a standard interface for accepting requests from the driver above. A request travels down the stack in the form of a self-contained, asynchronous request packet. Whenever a request packet arrives at a driver, the packet enters one of the driver's request queues and waits for processing. After each driver finishes processing a request, it can either forward the request to the next driver layer for further processing or complete the request.

A device stack cannot be split across processes. All function and filter drivers for a given device must run in the same driver host process.


Architecture of the UMDF

The following sections describe the UMDF architecture:

Simplified View of the UMDF Architecture

Detailed View of the UMDF Architecture

UMDF Driver Host Process


Simplified View of the UMDF Architecture

The following figure shows a simplified view of the UMDF architecture:

UMDF architecture

In the preceding figure, all components run on the same computer. In the current version, the number of device stacks per host process is limited to one stack. Applications are not aware of which host process runs a particular device stack. Applications use the standard Microsoft Win32 file I/O functions (for example, CreateFile, ReadFileEx, CancelIoEx, DeviceIoControl, and so on) to interact with the device. The reflector routes each Win32 file I/O call to the appropriate host process. The host process in turn routes each call to the correct device stack.


Detailed View of the UMDF Architecture

The following figure shows a detailed view of the component interaction of the UMDF architecture:

UMDF architecture

Each Microsoft Win32 file I/O function call made by the application goes through standard security and parameter checking in the operating system and then is routed to the reflector. The reflector, which sits at the top of the kernel-mode stack, redirects each request to the driver host process. The driver host process forwards each request to the top of the user-mode stack. Each request is either completed by one of the drivers in the user-mode stack or forwarded by one of the drivers back to the kernel-mode stack for completion.

Note The reflector can receive requests from either the client application or the user-mode stack. The reflector handles requests of each type in the following ways:

  • Requests from the client application are sent to the driver host process.
  • Requests from the user-mode stack are sent down to the kernel-mode stack.

Similar to a kernel-mode stack, the construction and tear down of a user-mode stack is driven by Plug and Play (PnP) events. After the kernel-mode stack is built with the reflector at the top of the kernel stack, the reflector notifies the driver manager to start construction of the user-mode stack. The driver manager launches the driver host process and provides sufficient information to the launched process to build the user-mode stack. In this way, the user-mode stack can be considered an extension of the kernel-mode stack. The reflector uses a message-based interprocess communication mechanism to communicate with the driver manager and host process.

The driver host process provides the execution environment for user-mode drivers and routes messages between drivers in a stack. The driver host process contains:

  • Vendor UMDF drivers.
  • A set of objects that the driver host process and UMDF drivers use to interact with each other; this constitutes the framework. The framework and UMDF drivers communicate using the UMDF device driver interface (DDI). For more information, see the UMDF reference section.
  • A runtime environment that handles I/O dispatching, driver loading, driver layering, thread pool, and messages from the reflector and driver manager.

The complete stack is composed of user-mode drivers and kernel-mode drivers. User-mode drivers are above all kernel-mode drivers. Application requests are routed to the user-mode stack first.


UMDF Driver Host Process

The driver host process contains the following components:

  • UMDF drivers are in-process Component Object Model (COM) component servers and are built as dynamic-link libraries (DLLs). The DLLs are provided by hardware vendors.
  • The framework is a set of UMDF object interfaces that the UMDF drivers can use. The framework implements default behavior to limit the amount of code required in a UMDF driver. The framework is also packaged as an in-process COM component server and built as a DLL.
  • The runtime environment handles interprocess communication (IPC) between the driver manager and the reflector, I/O dispatching, driver loading, driver layering, and thread pool. A UMDF driver uses a dedicated thread for critical operations to ensure I/O does not block them. For example, Plug and Play/power management, cancellation, cleanup, and close are critical. A UMDF driver uses shared threads for noncritical operations. For example, I/O is noncritical. The runtime environment's thread pool can grow or shrink as required; however, in the current version, thread pool is fixed at two threads. For long operations, UMDF drivers should use work items rather than threads.

The following figure shows the interrelationship between the components of the driver host process. Note that each driver in a layered stack can interact with a different version of the framework.

Driver host process


UMDF Objects and Interfaces

The User-Mode Driver Framework (UMDF) is composed of a set of cooperating objects. The UMDF creates and manages a series of objects exposed to the user-mode device driver. Some of theses objects are created by the UMDF in response to application-triggered actions, such as an I/O request, while other UMDF objects are created when the driver calls UMDF interface methods. For example, to create an I/O queue object, the driver calls the IWDFDevice::CreateIoQueue method.

The following topics describe the core framework objects, the subset of the Component Object Model (COM) on which they are based, and the UMDF DDI programming model:

Framework Objects

Framework Object Hierarchy

UMDF Based on COM Subset

UMDF DDI Programming Model

Managing the Lifetime of Objects


Framework Objects

The following table provides basic information about each framework object, links to the object's interface, and links to more information about the core framework objects.

Object name | Object Interface | Purpose | Default parent | Can driver override default parent? | Can driver own?
Driver object | IWDFDriver | Represents a driver | None | No | No
Device object | IWDFDevice | Represents a device | Driver object | No | No
File object | IWDFFile | Represents a file | Device object | No | No, if created by framework; Yes, if created by driver
Queue object | IWDFIoQueue | Represents an I/O queue that receives I/O requests | Device object | No | Yes
Request object | IWDFIoRequest | Represents an I/O request | Device object | No, if created by framework; Yes, if created by driver | No, if created by framework (for example, redirected requests); Yes, if created by driver
Target object | IWDFIoTarget | Represents a driver that another driver sends requests to | Device object | Yes | No, for the default target; Yes, for all other targets
USB device object | IWDFUsbTargetDevice | Represents a device that is connected to USB | Device object | No | Yes (see target object)
USB pipe object | IWDFUsbTargetPipe | Represents a USB device pipe | Device object | No | Yes (see target object)
USB interface object | IWDFUsbInterface | Represents a USB device interface | Device object | No | Yes (see target object)
Base object | IWDFObject | Represents a general base object | Driver object | Yes | Yes, if created by driver
Memory object | IWDFMemory | Represents a memory object | Driver object | Yes | No, if created by framework; Yes, if created by driver


Framework Base Object

The framework base object is exposed to drivers by the IWDFObject interface. It provides basic functionality that is common across all framework object types. All framework objects are derived from this root object.

When drivers create framework base objects through a call to the IWDFDriver::CreateWdfObject method, they can initially register their IObjectCleanup interfaces so that the framework notifies the driver when the objects are about to be destroyed. Later, drivers can use the IWDFObject::AssignContext method to change how they receive notifications on the framework base object instance.


Framework Driver Object

The framework driver object is exposed to drivers by the IWDFDriver interface. It is the framework representation of the driver image loaded in the driver host process. The framework creates a new driver object for each driver loaded in the driver host process. The IWDFDriver interface is passed to the driver by the IDriverEntry::OnInitialize method, which is the main entry point for the user-mode driver.


Framework Device Object

The framework device object is exposed to drivers by the IWDFDevice interface. The framework device object is the framework representation of the device on the system. Each device object has a parent driver object.

When a new device arrives in the system, the framework calls the IDriverEntry::OnDeviceAdd method to notify the driver of the arrival and passes the IWDFDriver and IWDFDeviceInitialize interfaces in the call. The driver can call methods of the IWDFDeviceInitialize interface to initialize the new device. For example, the driver calls the IWDFDeviceInitialize::RetrieveDevicePropertyStore method to query for the device information that is provided as part of device installation. The driver can then call the IWDFDriver::CreateDevice method to configure and create the device object.

When drivers create a framework device object, they can register their IPnpCallback, IPnpCallbackSelfManagedIo, IPnpCallbackHardware, IFileCallbackCleanup, and IFileCallbackClose interfaces. The framework then notifies the driver when file cleanup and close and Plug and Play (PnP) and power management (PM) events occur. For more information about supporting PnP and PM, see Supporting PnP and Power Management in UMDF Drivers.


Framework File Object

The framework file object is exposed to drivers by the IWDFFile interface. It is the framework representation of the opened device. When an application opens the device through the Microsoft Win32 CreateFile function, the framework creates a file object to represent the opened device instance. Therefore, the framework file object is conceptually equivalent to the Win32 handle that is returned from the application's call to CreateFile. The framework can create multiple file objects associated with a single device. Each file object is created for each successful call to CreateFile. All I/O operations, like reads and writes, are targeted to a specific file-object instance.

Note All requests passed to UMDF drivers are associated with file objects. However, requests that are passed to WDM and KMDF drivers are sometimes not associated with file objects.

A UMDF driver can call the IWDFIoRequest::GetFileObject method to obtain the file object associated with a request.


Framework I/O Queue Object

The framework I/O queue object is exposed to drivers by the IWDFIoQueue interface. It represents an I/O queue, which is a container for I/O requests. An I/O queue controls the flow of requests into the driver. When an I/O request arrives, it is placed in the appropriate queue. I/O queue objects are children of UMDF device objects. A driver can call the IWDFDevice::CreateIoQueue method to create I/O queue objects. In the call to IWDFDevice::CreateIoQueue, the driver can specify whether the queue is the default queue.

When the driver creates an I/O queue, it specifies a dispatch model that controls the delivery of requests to the driver. For more information, see Configuring Dispatch Mode for an I/O Queue.

When drivers create I/O queues, they can provide interfaces for callback functions that the framework calls to notify the driver when events related to the interfaces occur. For more information, see I/O Queue Event Callback Functions.


Framework I/O Request Object

The framework I/O request object is exposed to drivers by the IWDFIoRequest interface. It encapsulates the details of an I/O operation. All I/O requests are represented as framework I/O request objects. The reflector notifies the driver host process when the reflector receives an I/O request packet (IRP) as the result of an application I/O operation, such as, a call to the Microsoft Win32 CreateFile or ReadFile function. The framework, in response to the reflector notification, constructs a new request object and puts it in the appropriate I/O queue. The queue configuration and the locking model chosen by the user-mode driver determine when the request is presented to the driver. For more information, see Configuring Dispatch Mode for an I/O Queue and Specifying a Callback Synchronization Mode.


Framework I/O Target Object

The framework I/O target object is exposed to drivers by the IWDFIoTarget interface. It retrieves information about an I/O target, which typically represents a lower driver in the stack but can also represent another UMDF driver or the kernel-mode portion of the stack. The I/O target object provides UMDF drivers a way to send requests to another device.

UMDF drivers can also use the IWDFIoTargetStateManagement interface to manage and monitor the state of an I/O target object.


Framework Memory Object

The framework memory object is exposed to drivers by the IWDFMemory interface. It provides access to a memory block.


Framework Object Hierarchy

The following figure shows the parent-child framework object hierarchy.

Framework Object Hierarchy

The lifetime scope of framework objects is determined by their location in the hierarchy and how the objects are created. The lifetime scope of framework objects falls into one of the following categories:

  • The framework controls the creation and destruction of the objects.

    The framework creates and destroys objects, such as the driver object and device object, in response to system events. When a user-mode driver calls the IWDFDriver::CreateDevice method to create the device object, the driver can optionally register to be notified by the framework before the device object is destroyed.

  • The framework creates the object; however, the driver controls when the object is released.

    The I/O request object follows this pattern when I/O is presented to the driver. The framework creates the request object, and the request object's lifetime is valid until the driver calls the IWDFIoRequest::Complete method.

  • The driver creates the object and associates the object with another framework object.

    Some framework objects are created by a method that is exposed by a parent framework object instance that the objects are to be associated to for lifetime-management purposes. The IWDFDevice::CreateIoQueue method is an example of this pattern. If a call to IWDFDevice::CreateIoQueue succeeds, the newly created I/O queue is associated with the device instance that the IWDFDevice interface represents. When the parent object is destroyed, the framework automatically cleans up child instances. Drivers are notified of these events if the drivers register appropriate callback functions with the framework.


UMDF Based on COM Subset

The framework objects and interfaces are based on the Component Object Model (COM) for the following reasons:

  • COM is familiar to many applications programmers.
  • C++ is the preferred language for programming COM applications.
  • COM interfaces enable logical groupings of functions, so that the device driver interface (DDI) is easy to understand and navigate.
  • Using COM enables the DDI to extend and evolve without requiring existing driver DLLs to be recompiled.
  • Numerous tools, including Microsoft Visual Studio and active template library (ATL), support COM-based applications and objects.

The framework uses only a small subset of COM; it does not depend on the entire COM infrastructure and runtime library. Instead, the framework uses only the query-interface and reference-counting features. Every framework interface derives from IUnknown and therefore supports the QueryInterface, AddRef, and Release methods by default. The AddRef and Release methods manage object lifetime. The QueryInterface method enables other components to determine which interfaces the driver supports.


UMDF DDI Programming Model

The framework and the UMDF driver communicate through the UMDF DDI. The UMDF DDI is similar to the KMDF DDI except that the UMDF DDI is based on COM. Therefore, driver writers familiar with KMDF will understand UMDF.

For each type of framework object, the UMDF defines an interface through which to manipulate instances of the object. Each interface supports methods and properties. Methods define actions that can be taken on behalf of the object and properties set and retrieve the characteristics of the object. Some interfaces are implemented by the framework and others are implemented by the driver. Interfaces that are exposed by a framework object are of the form IWDF<object>, while the event callback interfaces exposed by a driver are of the form I<object><action>, where <object> represents a queue, request, and so on, and <action> indicates what the interface does. Methods of the callback interfaces begin with “On”.

The UMDF driver communicates with the framework's objects through their methods and properties. The framework communicates with the driver through event notifications, which are callback functions that the framework can call to notify the driver about specific events. To register callback functions, the driver can call, for example, the following framework object methods and can pass a pointer to the IUnknown interface associated with all the interfaces for the callback functions that the driver supports.

  • IWDFDevice::CreateIoQueue
  • IWDFDriver::CreateDevice
  • IWDFDriver::CreateWdfObject

As an example of driver to framework communication, consider a device's default I/O queue object. A driver can call methods, such as IWDFIoQueue::GetState , to retrieve status information about the I/O queue, or IWDFIoQueue::RetrieveNextRequest to retrieve a request from the I/O queue. A driver can also request for notifications on the I/O queue by calling the IWDFDevice::CreateIoQueue method to register callback interfaces, such as IQueueCallbackRead and IQueueCallbackWrite. The methods of these interfaces are subsequently called by the framework when an application sends read and write requests.

The framework provides any synchronization required across driver callback methods. By default, the framework synchronizes at device object level; that is, the framework does not concurrently call the event callback methods at or below the device object level. A driver can override this default by requesting no synchronization. For more information, see Specifying a Callback Synchronization Mode.


Managing the Lifetime of Objects

UMDF uses a reference-counting scheme to manage the lifetime of callback objects and framework objects.

Callback Object Management

A UMDF driver passes callback object interfaces to a framework object. For example, the driver can pass the IQueueCallbackRead and IQueueCallbackWrite interfaces for a queue callback object in a call to the IWDFDevice::CreateIoQueue method of a framework device object.

To ensure that the callback object is still valid when the framework object calls a method of the callback object interface, the framework object takes a reference on the callback object interface.

In most cases, the driver is not required to keep a reference on one of its callback objects. If methods of the callback object interface are called only by the framework and by objects whose lifetimes depend on the callback object and the callback object's paired framework object, no driver reference is required. In other words, the driver or framework can safely call methods of object interfaces that are higher up the object hierarchy.

For example, an I/O request object can call methods on the device callback object interface. However, a device object cannot necessarily call methods on the request callback object interface without ensuring that the device object has a reference to either the request object or the request’s callback object.

Framework Object Management

The driver creates many of the framework objects, such as the device object (IWDFDevice) and the I/O queue objects (IWDFIoQueue). In such a situation, in Component Object Model (COM), the caller typically holds a reference to the object and releases the object when the caller no longer requires the object.

UMDF, however, tracks all of the framework objects in an object tree and keeps its own references on the framework objects. Therefore, the driver does not require a reference on these objects.

The reference count on a framework object is decreased by one when the IWDFObject::DeleteWdfObject method is called on the framework object to delete the framework object. Calling IWDFObject::DeleteWdfObject on the framework object triggers tear down of the framework object. During tear down, the framework object releases its references on the driver-implemented callback object that corresponds with the framework object and eventually deletes itself.

If the driver-implemented callback object that corresponds with a framework object takes a reference on that framework object, a circular reference between the callback object and framework object occurs. Because of the occurrence of a circular reference, the callback object typically should not take an explicit reference on its corresponding framework object. However, if the callback object must take a reference on its corresponding framework object, the callback object must also implement the IObjectCleanup interface. When IWDFObject::DeleteWdfObject is called on the framework object, the framework object calls its corresponding callback object's IObjectCleanup::OnCleanup method. The implementation of IObjectCleanup::OnCleanup must release the reference to the framework object, which allows tear down of the framework object to complete properly.

For driver-owned framework objects, the driver controls each object's lifetime. For such an object, the driver should call IWDFObject::DeleteWdfObject to delete the object when the driver finishes using the object. If no other outstanding references on the object exist, the framework then removes the object from the tree. Driver-owned framework objects include, for example, memory objects, queue objects, and request objects.

For most framework objects, however, the framework owns the objects and controls the lifetime of the objects. For example, the framework controls the device object and the default I/O queue object. If the driver calls IWDFObject::DeleteWdfObject on a framework-owned object, the framework fails the call and generates a driver stop.


UMDF Operation and Features

The following sections describe the operation of UMDF and its features:

UMDF Operation and Default Code

Handling Driver Failures

Handling Application Failures

Enforcing Time-Outs

Handling Impersonation

UMDF Verifier

UMDF Error Reporting


UMDF Operation and Default Code

A fundamental goal of the overall WDF model is to provide intelligent defaults, so that you can focus on your device hardware and avoid writing code to perform tasks that are common to most drivers. With UMDF, that type of code is built into the framework, so your drivers are smaller.

To achieve this goal, the UMDF is designed to work with drivers on an “opt-in” basis. A UMDF driver includes callback interfaces for only the events that affect its device. For example, some devices require intervention immediately after they are turned on and immediately before they are turned off. The driver for such a device can implement a callback interface that provides methods to be called at those times. If the device does not require such intervention, its driver does not implement the interface.

Plug and Play and power management

The “opt-in” approach is particularly valuable for Plug and Play (PnP) and power management features. Within WDF, PnP and power management are implemented as a state machine. (Both the UMDF and KMDF use the same implementation of the state machine.) At a given state, a predetermined set of events is valid for each type of object, and the framework calls the driver’s callback functions for these events in a defined order. Thus, a driver can determine that both the system and its device are in a particular state whenever the driver is called to perform a PnP or power management action.

The complicated logic that tracks system and device state is incorporated into the framework, not into the driver. This approach reduces the amount of decision-making that is required in the driver and eliminates the need to perform the same task in numerous places. Instead, the framework defines a state-related event, and the driver supplies a callback interface. The driver includes code to handle only those events that its device requires device-specific support for. All other events can be handled by framework defaults.

Queue management

PnP and power management support are integrated with queue management. A driver can configure power management support for its I/O queues so that the framework stops dispatching requests while the device is in a low-power state and resumes dispatching after the device has returned to the operational state. Similarly, if an I/O request arrives while the device is in a low-power state, the framework can automatically turn on the device.


Handling Driver Failures

When a UMDF driver fails, the UMDF and operating system do the following:

  • The operating system notifies the reflector (WUDFRd.sys).
  • The reflector tracks outstanding I/O in the host process:
    • The reflector completes outstanding I/O with the STATUS_DRIVER_PROCESS_TERMINATED error code.
    • Microsoft Win32 applications receive the ERROR_DRIVER_PROCESS_TERMINATED error code for the outstanding I/O.

    Note The reflector that runs on Microsoft Windows XP completes outstanding I/O with STATUS_DRIVER_INTERNAL_ERROR, and Win32 applications, in turn, receive the ERROR_IO_DEVICE error code for the outstanding I/O. Therefore, applications that run on Windows XP should not use ERROR_IO_DEVICE to detect a driver failure because they cannot determine any difference from the status that is returned from a typical I/O request (for example, the status that is returned from a call to the Win32 DeviceIoControl function).

  • The reflector sends the GUID_WUDF_DEVICE_HOST_PROBLEM custom Plug and Play (PnP) event to the operating system after the operating system reports a problem with the host process.

    If an application previously called the Win32 RegisterDeviceNotification function to register GUID_WUDF_DEVICE_HOST_PROBLEM for the device, that application will receive a DBT_CUSTOMEVENT notification when the host process fails. For more information about RegisterDeviceNotification and DBT_CUSTOMEVENT, see the Platform SDK documentation.

  • The operating system writes an entry to the system event log that indicates that the driver failed. It also indicates how many more times the operating system will restart the driver. This feature is currently supported only on Microsoft Windows Vista. The operating system writes the following event numbers into the system event log to indicate the specified problems:
    • 10110 if the host process was at fault
    • 10111 if the device went offline and was restarted
    • 10112 if the device went offline and was not restarted

    The operating system can restart a given instance of a device up to five times. After the operating system exhausts the restart attempts, it will not automatically restart the device again. If the user either disables and enables the device in the Device Manager or unplugs and plugs the device, the operating system makes a new instance of the device and resets the restart counter.

  • The operating system unloads the kernel drivers in the device stack.

    Note The operating system will not tear down and restart the device stack until all handles to the old stack have closed. An application will detect the device failure and a surprise removal notification for the device (DBT_REMOVEDEVICEPENDING). However, if any handle to the old stack is kept open, the device is not restarted.

  • The driver manager either restarts or disables the device. If the device is disabled, the operating system displays a yellow exclamation point in Device Manager.

Note After the UMDF driver fails, the following operations can occur in an arbitrary order:

  • The operating system tears down and restarts the device.
  • The reflector sends the GUID_WUDF_DEVICE_HOST_PROBLEM PnP event to the operating system.
  • The reflector completes outstanding I/O with STATUS_DRIVER_PROCESS_TERMINATED.

Therefore, an application might receive ERROR_DRIVER_PROCESS_TERMINATED for the outstanding I/O after the operating system has restarted the device. After receiving ERROR_DRIVER_PROCESS_TERMINATED, the application might also receive the DBT_CUSTOMEVENT notification that results from the GUID_WUDF_DEVICE_HOST_PROBLEM event.


Handling Application Failures

When an application fails, the UMDF and operating system do the following:

  • The reflector receives IRP_MJ_CLEANUP.
  • The cleanup request is sent to the host process on the “cancel” IPC channel.
  • The host process and UMDF driver complete pending I/O requests.


Enforcing Time-Outs

The UMDF enforces time-outs on the following types of critical operations:

  • Operations that run under system-wide locks. Plug and Play (PnP) and power management operations are examples of this type of critical operation because they run under a system-wide PnP lock. That is, they block other PnP operations.
  • Operations that affect the user experience. I/O cancellation is an example of this type of critical operation. Long-term operations must be cancelable because they adversely affect the user experience (that is, the application stops responding).

If operations do not complete on time, the reflector terminates the host process, and an error report is generated.

In the current version of the UMDF, time-out is set to one minute.


Handling Impersonation

UMDF drivers run in LocalService security context and can impersonate the client process only for I/O requests and not for Plug and Play (PnP) or other system messages.

UMDF handles impersonation in the following ways:

  • An application controls the allowed impersonation level in the quality of service (QoS) settings in the Microsoft Win32 CreateFile function. For more information about these settings, see the dwFlagsAndAttributes parameter of CreateFile in the Platform SDK documentation.
  • The UMDF driver's INF file sets the UMDF driver’s maximum allowable impersonation level, as follows:
    • The level is set during device installation.
    • To reduce the chance of an “elevation of privilege” attack, you should set the level as low as possible for your driver.

    For more information about setting the impersonation level, see Specifying WDF Directives.

  • The UMDF driver requests impersonation for a given I/O request, in the following ways:
    • The driver calls the IWDFIoRequest::Impersonate method to specify the required level and a callback function.
    • In the supplied callback function (IImpersonateCallback::OnImpersonate), the driver isolates the impersonated code and performs minimal work to reduce the attack surface. To ensure that impersonation does not leak across driver callback functions or between device drivers, OnImpersonate should not call any framework methods.


UMDF Verifier

The UMDF Verifier is a feature that verifies code in your UMDF driver. The following topics describe features of the UMDF Verifier and how it handles UMDF driver failures:

UMDF Verifier Features

Handling UMDF Verifier Failures


UMDF Verifier Features

The UMDF Verifier verifies problems in framework code and problems in the UMDF driver code.

The UMDF Verifier is always enabled (that is, it is enabled in both the free and checked build environments). Therefore, problems in the UMDF driver code are always fatal unless a debugger is attached to the computer. That is, problems in the UMDF driver code cause the host process to stop responding.

Misuse of the UMDF device driver interface (DDI) causes a verifier failure. Misuse includes passing incorrect parameters, including NULL, in the DDI and calling DDI functions in an incorrect sequence. Verifier failures cause a UMDF bug check. For more information about these failures, see Handling UMDF Verifier Failures.


Handling UMDF Verifier Failures

The UMDF Verifier causes failures in UMDF driver code to bug check the host process. However, a UMDF bug check does not cause a blue text screen to appear with information about the error. Instead, a UMDF bug check:

  • Creates a memory dump file and saves the file to the computer's log file directory (for example, %windir%\System32\LogFiles\WUDF\Xxx.dmp).
  • Creates an error report for Microsoft (opt-in).
  • Breaks into the debugger if one is attached to the computer. The debugger prints an out error message. You can continue but the computer might stop responding again.
  • Terminates the host process and disables the device.


UMDF Error Reporting

UMDF error reports provide the following benefits over kernel-mode error reports:

  • UMDF error reports are separated into distinct categories so less information is collected.
  • UMDF error reports are specialized so irrelevant state is not mixed in.
  • UMDF error reports are more comprehensive; that is, UMDF error reports are not limited by crash dumps.

The UMDF reports problems through Microsoft Windows Error Reporting (WER). The UMDF queues reports for later approval and upload. WER provides for a global “opt-in” to upload more quickly. No modal crash dialog boxes are displayed in this situation. Instead, a bubble on the task bar indicates an incident occurred.

The UMDF reports the following types of errors:

  • UMDF Verifier failures.
  • Unhandled exceptions in the host process.
  • Unexpected termination of the host process.
  • Failure or time-out of critical operations. For more information about time-outs, see Enforcing Time-Outs.

A UMDF error report can contain the following information. The contents of the report depend on the problem that is detected.

  • A memory dump of the host process
  • A copy of the UMDF’s internal trace log
  • Configuration information about the device, which can include the device name, manufacturer, drivers that are installed, and driver binary versions
  • Internal analysis of the problem, which can include the address of the last driver-to-framework call (or vice versa), problem code, exception information, and so on


Installing UMDF Drivers

A User-Mode Driver Framework (UMDF) driver is installed on the operating system by using an INF file. An INF file for a UMDF driver is identical to INF files for Microsoft Windows Driver Model (WDM) and Windows Driver Foundation (WDF) - Kernel-Mode Driver Framework (KMDF) drivers. However, an INF file for a UMDF driver also includes information to:

Request to use the UMDF coinstaller.

Restrict where UMDF drivers are loaded from.

Specify WDF directives.

Add the reflector.

You should refer to the Creating an INF File and INF File Sections and Directives sections for general help in creating a UMDF INF file.


Requesting to Use the UMDF Coinstaller

A UMDF driver can install and start to run on the operating system with the help of the system-supplied UMDF coinstaller (WUDFCoInstaller.dll). To request to use the system-supplied UMDF coinstaller, the INF file for the UMDF driver must include a DDInstall.CoInstallers section that is similar to the following code example.

[Skeleton_Install.CoInstallers]
AddReg=Skeleton_Install.CoInstallers_AddReg

An AddReg directive in the CoInstallers section should reference an add-registry-section similar to the following code example.

[Skeleton_Install.CoInstallers_AddReg]
HKR,,CoInstallers32,0x00010000,"WUDFCoInstaller.dll"

The CoInstallers section can reference more than one coinstaller and can mix KMDF coinstallers with UMDF coinstallers. If the UMDF driver requires multiple major version numbers of UMDF (for example, 1.x and 2.x), the INF file for the driver must copy, by using the CopyFiles directive, the coinstaller for each version to the same location on the hard disk drive. However, the INF file should add only the highest version coinstaller for KMDF and UMDF to the CoInstallers32 registry value, by using add-registry-sections as shown in the preceding example.

The CoInstallers section can reference the system-supplied UMDF coinstaller (also known as the configurable coinstaller), a redistributable coinstaller (also known as an update coinstaller), or both. Microsoft supplies an update coinstaller (Wudf_Update_<Version>.dll) that you can reference in your INF files and include with your UMDF driver packages.

To start running on the operating system, the UMDF driver requires the UMDF driver manager. Therefore, the UMDF coinstaller sets the driver manager to start automatically when the UMDF coinstaller is called to install UMDF drivers for a device.


Restricting the Loading Location of UMDF Drivers

The UMDF platform will fail to load the main UMDF driver binaries from any location other than the %SystemRoot%\System32\Drivers\Umdf directory. Therefore, a UMDF INF file must restrict the location where it installs UMDF drivers to that directory. Installing in this directory also ensures that unprivledged users cannot tamper with the UMDF drivers.

To install UMDF driver binaries to %SystemRoot%\System32\Drivers\Umdf, the UMDF driver INF file must include an INF DestinationDirs Section that is similar to the following code example.

[DestinationDirs]
UMDriverCopy=12,UMDF ; copies to drivers\umdf

UMDriverCopy represents an INF-writer-determined name of a section that lists the UMDF driver binaries as shown in the following example.

[UMDriverCopy]
WUDFOsrUsbDriver.dll

The CopyFiles directive must also reference the UMDriverCopy section to indicate the list of UMDF driver binaries for the operating system to copy from the source media to the destination as shown in the following example.

[OsrUsb_Install.NT]
CopyFiles=UMDriverCopy


Specifying WDF Directives

An INF file that installs a UMDF driver must contain a Microsoft Windows Driver Foundation (WDF)-specific DDInstall section. However, the INF file can contain more that one WDF-specific DDInstall section if the INF file installs more than one WDF driver. Each WDF-specific DDInstall section:

  • Corresponds to the DDInstall and DDInstall.Services sections that are associated with a particular WDF driver.
  • Is processed by all of the loaded WDF coinstallers, which run in arbitrary order.
  • Contains WDF installation directives for a device. UMDF-specific directives begin with the UMDF prefix, and KMDF-specific directives begin with the KMDF prefix.

The following code example shows UMDF-specific directives in a WDF-specific DDInstall section.

[Skeleton_Install.Wdf]
UmdfService=UMDFSkeleton,UMDFSkeleton_Install
UmdfServiceOrder=UMDFSkeleton

Each UMDF-specific directive in the WDF-specific DDInstall section is described in the following list:

UmdfService = <serviceName>, <sectionName>
Associates a UMDF driver with a UMDF-service-install section that contains information that is required to install the UMDF driver. The serviceName parameter specifies the UMDF driver. The sectionName parameter references the UMDF-service-install section. A valid INF file typically requires at least one UmdfService directive. However, if a UMDF driver is part of the operating system, a UmdfService directive for the UMDF driver is not required. Therefore, a valid INF file might not have any UmdfService directives, although most INF files will have one UmdfService directive for each UMDF driver.
UmdfServiceOrder = <serviceName1> [, <serviceName2> …]
Lists the order that the coinstaller installs the UMDF drivers on the device stack. Even if the coinstaller installs only one UMDF driver on the device stack, the INF file must contain this directive. The serviceNameXx parameters correspond to the serviceName parameters for each UmdfService directive. Because the UMDF drivers are added to the device stack in the order that they are listed, the first parameter specifies the lowest UMDF driver in the device stack.

To ensure that a UMDF coinstaller installs the device, one and only one UmdfServiceOrder directive must be present in any given WDF-specific DDInstall section. That is, the UmdfServiceOrder directive cannot be imported by using the Include and Needs directives.

UmdfImpersonationLevel = <level>
Informs the framework about the maximum impersonation level that the UMDF driver can have. A UmdfImpersonationLevel directive is optional; if an impersonation level is not specified, the default is Identification. When an application opens a file handle, the application can grant a greater impersonation level to the driver. However, the driver cannot call the IWDFIoRequest::Impersonate method to request an impersonation level that is greater than the level that UmdfImpersonationLevel specifies. The possible values for this directive are:
  • Anonymous
  • Identification
  • Impersonation
  • Delegation
The preceding values correspond to the values that are specified in the SECURITY_IMPERSONATION_LEVEL enumeration.
UmdfMethodNeitherAction = <Reject | Copy>
Informs the framework about whether it should either copy to the driver's process (Copy) or automatically fail (Reject) METHOD_NEITHER types of I/O. A UmdfMethodNeitherAction directive is optional. If a value is not specified, the default is Reject.

UMDF cannot fully support METHOD_NEITHER types of I/O. The framework can successfully copy METHOD_NEITHER types of I/O to the driver's process only when the address and length of data buffers in the I/O are valid. If the I/O control overrides the length parameter, the framework cannot correctly copy the data. In some situations where data buffers only contain primitive data, you might want to enable the framework to copy METHOD_NEITHER types of I/O to the driver's process. For more information about METHOD_NEITHER, see Buffer Descriptions for I/O Control Codes.

UmdfDispatcher = <FileHandle | WinUsb>
Informs the framework about where it should send requests after they leave the device stack. A UmdfDispatcher directive is optional. The INF file should specify the UmdfDispatcher directive only if a driver in the stack uses a file-handle-based target (FileHandle) or a USB target (WinUsb). A UMDF driver calls the IWDFFileHandleTargetFactory::CreateFileHandleTarget method to create a file-handle-based target and the IWDFUsbTargetFactory::CreateUsbTargetDevice method to create a USB target. If a value for the UmdfDispatcher directive is not specified, the framework sends requests to the kernel stack (that is, the framework sends requests to the reflector).

The following code example shows the required directives in a UMDF-service-install section.

[UMDFSkeleton_Install]
UmdfLibraryVersion=1.0.0
ServiceBinary=%12%\UMDF\UMDFSkeleton.dll
DriverCLSID={d4112073-d09b-458f-a5aa-35ef21eef5de}

Each directive in the UMDF-service-install section is described in the following list:

UmdfLibraryVersion = <version>
Informs the coinstaller about the version number of the framework that the UMDF driver will use. The format of the version string is <major>.<minor>.<service>. When drivers on the device stack use more than one version of the framework, the INF file copies multiple coinstallers—one for each framework version—to the same location on the hard disk drive. However, the INF file adds only the highest version coinstaller to the CoInstallers32 registry value. For more information about copying coinstallers, see Requesting to Use the UMDF Coinstaller.

The coinstaller verifies the version string and uses it to locate the version-specific coinstaller for the UMDF driver. The coinstaller then extracts the framework from the version-specific coinstaller.

ServiceBinary = <binarypath>
Informs UMDF about where to place the UMDF driver binary on the hard disk drive.

UMDF drivers should be copied to and run from the \Windows\System32\Drivers\UMDF directory.

DriverCLSID = <{CLSID}>
Informs UMDF about the class identifier (CLSID) of the UMDF driver. When UMDF loads the UMDF driver, the UMDF host uses the UMDF driver's CLSID to create an instance of the UMDF driver's IDriverEntry interface.


Adding the Reflector

The INF file for a UMDF driver must install the reflector (WUDFRd.sys) as the highest driver in the kernel-mode stack. To add the reflector, the INF file for the UMDF driver must include an AddService directive in a DDInstall.Services section. The reflector can be an upper filter, a lower filter, or the service for the device, depending on the configuration of the user-mode stack. Regardless, no kernel-mode drivers can be loaded above the reflector.

If the UMDF driver is a function driver or if the user-mode stack contains a function driver in the case of multiple UMDF drivers, the AddService directive should assign the reflector as the associate service for the device. To assign the reflector as the associate service, the AddService directive specifies the SPSVCINST_ASSOCSERVICE flag (0x00000002).

If the UMDF driver is a filter driver or if the user-mode stack contains only filter drivers, the AddService directive should make the reflector the highest upper-filter driver in the kernel-mode stack.

If the device is not associated with a service (that is, the device is a raw accessible device), the AddService directive should make the reflector the highest lower-device filter.

The AddService directive should set the 0x000001f8 flags to prevent overwriting any preexisting configuration for the service. For more information about these flags, see the flags parameter of the AddService directive.

The following code example shows how the INF file for the UMDF driver might add the reflector.

[Skeleton_Install.Services]
AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall

The AddService directive references an add-service-section similar to the following code example. The ServiceType entry specifies 1 or 0x00000001, which indicates that the INF installs support for one or more devices. The StartType entry specifies when to start the driver. The ErrorControl entry specifies the level of error control that the driver provides. The ServiceBinary entry specifies the path to the binary (the reflector) for the service.

[WUDFRD_ServiceInstall]
ServiceType=1
StartType=3
ErrorControl=1
ServiceBinary=%12%\WUDFRd.sys

If the reflector is not added, UMDF is never loaded. The device might start, but the host process is not present and the device will not operate properly.


Initializing UMDF Drivers

Before a UMDF driver for a device is initialized, the driver manager and the reflector are loaded by the operating system and the driver host process is created. To ensure that a device starts successfully, the driver manager is loaded and fully initialized by the time the reflector initializes.

When the device is installed, the Plug and Play (PnP) subsystem loads the reflector, if not already loaded. The reflector then contacts the driver manager to create the driver host process. The framework within the newly created driver host process then calls the IDriverEntry::OnInitialize method to initialize the UMDF driver, if not already initialized.

The framework adds a new device object for each device loaded in the driver host process. The following sections show an overview and provide details on how the framework adds a new device:

Adding a Device Overview

Adding a Device


Adding a Device Overview

The following figure shows an overview of how the framework adds a new device:

Adding a Device


Adding a Device

The framework adds a device object for each device loaded in the driver host process. To add the device, the framework calls the driver's IDriverEntry::OnDeviceAdd method and passes the IWDFDriver and IWDFDeviceInitialize interfaces in the call. The supplied IWDFDeviceInitialize interface is only valid in the context of the OnDeviceAdd method. The driver can call the following methods of IWDFDeviceInitialize to perform the following operations:

  • The driver calls the IWDFDeviceInitialize::RetrieveDevicePropertyStore method to retrieve the IWDFNamedPropertyStore interface for the device property store. The driver can use IWDFNamedPropertyStore to retrieve and set properties for the device.
  • The driver calls the IWDFDeviceInitialize::SetLockingConstraint method to specify how its callback functions are called by the framework.
  • The driver calls the IWDFDeviceInitialize::SetFilter method to enable the device as a filter device.

After the driver uses IWDFDeviceInitialize to initialize the device, the driver passes a pointer to IWDFDeviceInitialize in a call to the IWDFDriver::CreateDevice method to create a UMDF device object for the device. After the framework device object is created, the driver makes calls to the IWDFDevice::CreateIoQueue method to create read and write I/O queues. In these IWDFDevice::CreateIoQueue calls, the driver must identify how it receives requests from the I/O queue. For more information, see Configuring Dispatch Mode for an I/O Queue.


UMDF Driver Tasks

The following sections discuss solutions for tasks that you can perform with UMDF drivers:

Creating Callback Objects

Supporting PnP and Power Management in UMDF Drivers

Specifying a Callback Synchronization Mode

I/O Queue Event Callback Functions

Configuring Dispatch Mode for an I/O Queue

Combining Dispatch and Synchronization Modes

Processing I/O Requests


Creating Callback Objects

A UMDF driver can create callback objects, which consist of context data and interface methods. The framework accesses the driver's callback objects through the driver's callback interface methods.

The following figure shows how the driver-implemented callback objects correspond to framework objects.

Callback Objects Correspond to Framework Objects

A UMDF driver creates the following types of callback objects:

  • Driver callback object

    The framework uses the driver callback object to initialize the driver and notify the driver of the arrival of a new device.

  • Device callback object

    The driver uses the device callback object to store device context and to handle the cleanup and closing of file objects and Plug and Play (PnP) and power management (PM) events.

  • Queue callback object

    The driver uses the queue callback object to process I/O.

The following figure shows how a UMDF driver creates a device callback object.

Creating a Callback Object

The following topics contain code examples that show how to create a callback object:

Creating Callback Objects Example

Defining Callback Objects Example

Associating Callback Interfaces Example


Creating Callback Objects Example

The following code example shows how a driver creates a device callback object in the implementation of its IDriverEntry::OnDeviceAdd method and then passes a pointer to the device callback interface in its call to the IWDFDriver::CreateDevice method to create the device.

   HRESULT CMyDriver::OnDeviceAdd(
              IWDFDriver*           pDriver,
              IWDFDeviceInitialize* pDeviceInit
              ) {
      IUnknown *pDeviceCallback = NULL;
      ...
      HRESULT hr;
      // Create callback object
      hr = CMyDevice::CreateInstance( &pDeviceCallback,
                                      pDeviceInit,
                                      completionPort );
      ...
      // Create WDF device
      hr = pDriver->CreateDevice( pDeviceInit,
                                  pDeviceCallback,
                                  &pIWDFDevice );
      ...
   }


Defining Callback Objects Example

The following code example shows how a driver inherits from the IPnpCallbackHardware interface to define a device callback object.

class CMyDevice :
       // Callback interface exposed to the framework
       public IDevicePnpHardware
{// The following data members make up the context
private:
   HANDLE                  m_CompletionPort;
   WINUSB_INTERFACE HANDLE m_UsbHandle;
   UCHAR                   m_BulkOutPipe;
   ULONG                   m_BulkOutMaxPacket;
   ...
// The following methods make up the callback interfaces
public:
   virtual HRESULT stdcall OnPrepareHardware(
                              IWDFDevice* pDevice
                              );
   STDMETHOD( OnReleaseHardware )( IWDFDevice *pDevice );

   // Method used to create a device callback object
   static HRESULT CreateInstance(
                     IUnknown **ppUnknown,
                     IWDFDeviceInitialize *pDeviceInit,
                     HANDLE CompletionPort
                     );
   ...
};


Associating Callback Interfaces Example

The following code example shows how a driver implements a create-instance method that the driver uses to create the device callback object. The driver allocates the callback context and associates the supplied IUnknown with one or more callback interfaces. The framework can subsequently use QueryInterface to discover the callback interfaces supported by the driver.

static HRESULT CreateInstance(
                  IUnknown **ppUnknown,
                  IWDFDeviceInitialize *pDeviceInit,
                  HANDLE CompletionPort
                  ) {
   ...
   // Allocate the callback context
   CMyDevice *pMyDevice = new CMyDevice();
   ...
   HRESULT hr;
   // Discover the callback interface
   hr = pMyDevice->QueryInterface(
                      __uuidof(IUnknown),
                      (void **) ppUnknown
                      );
   ...
   return hr;
}


Supporting PnP and Power Management in UMDF Drivers

When a new device arrives in the system, the framework calls the IDriverEntry::OnDeviceAdd method to notify the UMDF driver of the arrival and passes the IWDFDriver and IWDFDeviceInitialize interfaces in the call. The driver calls the IWDFDriver::CreateDevice method to create a framework device object for the device.

When drivers create a framework device object, they can register the following interfaces so that the framework notifies the driver—by calling the methods associated with the interfaces—when Plug and Play (PnP) and power management (PM) events occur.

IPnpCallback

IPnpCallbackSelfManagedIo

IPnpCallbackHardware


Specifying a Callback Synchronization Mode

The driver can specify how its callback functions are called by the framework. The driver specifies a synchronization (or locking) mode for a device before it calls the IWDFDriver::CreateDevice method to create a device object for the device. To specify synchronization mode, the driver should call the IWDFDeviceInitialize::SetLockingConstraint method. The driver receives a pointer to the IWDFDeviceInitialize interface when its IDriverEntry::OnDeviceAdd method is called to add the device to the system.

The driver can specify one of the following values from the WDF_CALLBACK_CONSTRAINT enumeration type in the LockType parameter of IWDFDeviceInitialize::SetLockingConstraint to identify the locking mode. The type of constraint (or locking) specified depends on how much parallelism the hardware device can exploit and how much the driver can handle.

Value | Meaning
None (0) | Indicates that no callback functions into the driver are synchronized.
WdfDeviceLevel (1) | Indicates that all queue callback functions into the driver are synchronized.

Note If the driver does not call IWDFDeviceInitialize::SetLockingConstraint to specify a value, the framework sets the default value of this property to WdfDeviceLevel.

Constraints apply only to queue callback functions and not to Plug and Play (PnP) and power management callback functions. Queue callback functions include the following:

  • Automatic dispatch callback functions, such as, IQueueCallbackRead::OnRead and IQueueCallbackWrite::OnWrite. For more information, see I/O Queue Event Callback Functions.
  • Queue state change callback functions, such as, IQueueCallbackStateChange::OnStateChange.
  • Request cancellation callback functions, such as, IRequestCallbackCancel::OnCancel.

Request completion callback functions (IRequestCallbackRequestCompletion::OnCompletion) are not queue callback functions. Therefore, they are not synchronized.


I/O Queue Event Callback Functions

When drivers create I/O queues, or configure default I/O queues, they can register the following interfaces so that the framework notifies the driver—by calling the methods associated with the interfaces—when events related to the interfaces occur. For more information about I/O queues and creating and configuring I/O queues, see Framework I/O Queue Object.

IQueueCallbackCreate

IQueueCallbackDeviceIoControl

IQueueCallbackRead

IQueueCallbackWrite

IQueueCallbackDefaultIoHandler


Configuring Dispatch Mode for an I/O Queue

When I/O requests from applications arrive, the framework places each request in the appropriate I/O queue. How and when the requests are delivered to the driver depend on how the driver configures dispatching for the I/O queue and on how the driver specifies callback-function synchronization. The I/O queue also interacts with the PnP and power management subsystem of UMDF to hold I/O requests in the queue until the device reaches the proper state.

Note The dispatch mode for the I/O queue is not related to the synchronization mode. The I/O queue's dispatch configuration controls the number of requests that the driver can accept for processing at any given time, while synchronization controls the simultaneous execution of event callback functions that are presenting or canceling requests. However, several modes of operation are created by combining dispatch and synchronization modes.

The driver configures dispatching for an I/O queue when the driver calls the IWDFDevice::CreateIoQueue method to configure the default queue or to create a secondary queue. The driver can specify one of the values from the WDF_IO_QUEUE_DISPATCH_TYPE enumeration type in the DispatchType parameter of IWDFDevice::CreateIoQueue to identify the dispatch mode. An I/O queue object can support the following dispatch modes:

  • Sequential

    The sequential dispatch mode is specified using the WdfIoQueueDispatchSequential value. In this dispatch mode, a queue in the processing state raises events so that a driver only processes one request at a time. The queue defers any additional requests until the driver finishes processing its current request or calls the IWDFIoRequest::ForwardToIoQueue method to requeue the request. When the current request completes or is forwarded, the queue raises an event to provide the next request.

  • Parallel

    The parallel dispatch mode is specified using the WdfIoQueueDispatchParallel value. In this dispatch mode, a queue in the processing state raises events as soon as I/O requests are ready for the driver. When the driver receives an I/O request, the driver can process the I/O request in one of the following ways:

    • The driver calls either the IWDFIoRequest::Complete or IWDFIoRequest::CompleteWithInformation method to complete the I/O request immediately. A driver completes the I/O request immediately if the I/O request is invalid, cannot ever be serviced, or can be completed by copying data from a buffer or cache that has the data.
    • The driver calls the IWDFIoRequest::ForwardToIoQueue method to requeue the I/O request.
    • The driver calls the IWDFIoRequest::Send method to pass the I/O request to a lower-level driver.

  • Manual

    The manual dispatch mode is specified using the WdfIoQueueDispatchManual value. In this dispatch mode, the I/O queue does not automatically notify the driver when requests arrive at the queue. The driver must call the IWDFIoQueue::RetrieveNextRequest method to retrieve requests manually from the queue. This is a polling model.

For all dispatch modes, the I/O queue object receives and tracks the request until the driver handles the request or the request is canceled.

If the driver configures the queue for serial or parallel dispatching, the framework notifies the driver of a request through the callback functions that are registered by the driver when the driver creates the queue or configures the default queue. For more information, see I/O Queue Event Callback Functions.


Combining Dispatch and Synchronization Modes

Combining a particular queue dispatch mode with a synchronization mode provides the following modes of operation:

Combining dispatch and synchronization modes

© 2006 Microsoft Corporation
Send feedback on this topic
Built on May 25, 2006
Build machine: CAPEBUILD


Processing I/O Requests

The following topics discuss how UMDF drivers process I/O requests:

I/O Request Processing Operation Flow

Sending I/O Requests to Lower Drivers

Obtaining Parameters for I/O Requests

Canceling I/O Requests

Completing I/O Requests


I/O Request Processing Operation Flow

All I/O operations occur in the context of a file object (that is, all I/O operations occur between calls that an application makes to the Microsoft Win32 CreateFile and CloseHandle functions). I/O operations are calls that an application makes to, for example, the Win32 ReadFileEx, WriteFileEx, and DeviceIoControl functions.

The following topics show the flow of operations that occur to and from UMDF drivers as a user I/O transaction begins, processes, and ends in a single device stack and in a double device stack:

Operation Flow with Single Device Stack

Operation Flow with Double Device Stack

Note All I/O that is initiated by applications is routed through kernel mode as shown in the figures in the Architecture of the UMDF section, even though the figures in the I/O Request Processing Operation Flow section do not show this situation.


Operation Flow with Single Device Stack

The following figure shows the flow of operations that occur to and from the UMDF functional driver in a single device stack.

Operation Flow with Single Device Stack

Note All I/O that is initiated by applications is routed through kernel mode as shown in the figures in the Architecture of the UMDF section, even though the preceding figure does not show this situation.

The UMDF driver calls the IWDFIoRequest::GetCreateParameters method only if it requires information about the file that is associated with the read request. The UMDF driver calls the IWDFIoRequest::GetReadParameters method only if it requires more information about the read request.

The UMDF driver can call the IWDFIoRequest::Complete method rather than the IWDFIoRequest::CompleteWithInformation method if specifying the number of bytes that are transferred in the read operation is not required. The UMDF driver calls Complete or CompleteWithInformation to signal that the read operation is complete; the application can then access the read data.


Operation Flow with Double Device Stack

The following figure shows the flow of operations that occur to and from UMDF filter and functional drivers in a double device stack.

Operation Flow with Double Device Stack

Note All I/O that is initiated by applications is routed through kernel mode as shown in the figures in the Architecture of the UMDF section, even though the preceding figure does not show this situation.

The UMDF filter and function drivers might also call the IWDFIoRequest::GetCreateParameters method if they require information about the file that is associated with the read request. The UMDF filter and function drivers might also call the IWDFIoRequest::GetReadParameters method if they require more information about the read request.

The UMDF functional driver calls the IWDFIoRequest::Complete or IWDFIoRequest::CompleteWithInformation method to signal to the filter driver that it is done with the read operation. The UMDF filter driver might also call methods of the IWDFIoRequestCompletionParams interface if it requires more information to complete the read request. The UMDF filter driver calls Complete or CompleteWithInformation to signal that the read operation is complete; the application can then access the read data.


Sending I/O Requests to Lower Drivers

When a driver receives an I/O request that it cannot fully process, the driver typically forwards the received request to the next lower driver in the stack. The driver calls the IWDFIoRequest::Send method to forward the request. To forward synchronously, the driver passes the WDF_REQUEST_SEND_OPTION_SYNCHRONOUS flag in the Flags parameter. Otherwise, the driver forwards the request asynchronously. Before the driver forwards the request, it should register a completion routine. For more information, see Completing I/O Requests.


Obtaining Parameters for I/O Requests

When a driver receives an I/O request, the driver can use the following methods of the IWDFIoRequest interface to obtain parameters related to the request:

IWDFIoRequest::GetCreateParameters

IWDFIoRequest::GetDeviceIoControlParameters

IWDFIoRequest::GetReadParameters

IWDFIoRequest::GetWriteParameters


Canceling I/O Requests

I/O requests are sent to an I/O queue either by the reflector or by the UMDF driver when it calls the IWDFIoRequest::ForwardToIoQueue method to forward (requeue) requests to the I/O queue. If the driver requeues the I/O requests, the I/O queue must be different from the I/O queue to which the requests were originally presented.

A request is canceled because either the application called the IoCancel, IoCancelEx, or CancelSynchronousIo function to explicitly request cancellation, or a system event like device removal occurred. Drivers are notified of the cancellation by the OnCancel method of the IRequestCallbackCancel interface, which is registered through a call to the IWDFIoRequest::MarkCancelable method to enable canceling of the request.

The request, at any given time, is in one of the following states:

  • The request is in the queue and has never been presented to the driver.
  • The request is “in-flight.” That is, it has been presented to the driver, but the driver has not yet completed it.

For the case where the request is canceled before it is presented to the driver, the framework automatically cancels the request. In this case, the driver’s IRequestCallbackCancel::OnCancel method is not called, even if the IRequestCallbackCancel interface was previously registered.

If the request is canceled before the driver can complete the request, the driver’s OnCancel method is called. For more information about completing a request, see Completing I/O Requests. The driver must complete the request only once regardless of whether the driver completes the request from either its OnCancel method or the main processing path.


Completing I/O Requests

Every I/O request must eventually be completed by one of the drivers in the stack that manages a device. To complete a request, a driver must call either the IWDFIoRequest::Complete or IWDFIoRequest::CompleteWithInformation method. Before the driver completes the request, it detects one of the following scenarios:

  • The requested I/O operation finished successfully.
  • The requested I/O operation started but failed before it finished.
  • The requested I/O operation is not supported or is not valid at the time it was received and therefore cannot communicate with the device.
  • The requested I/O operation was canceled.

The driver calls the IWDFIoRequest::CompleteWithInformation method to pass additional information about the request operation. For example, for a read operation, the driver should indicate the actual amount of bytes read.

If the driver previously sent a request to a lower-level driver, then the driver requires notification when the lower-level driver completes the request. To register for notification, the driver calls the IWDFIoRequest::SetCompletionCallback method to register the interface for the method that the framework calls when the lower-level driver completes the request. The driver implements the IRequestCallbackRequestCompletion::OnCompletion method to perform the operations required to complete the request.


Debugging UMDF Drivers

You can debug User-Mode Driver Framework (UMDF) drivers by using either a user-mode debugger or a kernel-mode debugger. However, user-mode debugging requires only a single computer, and kernel-mode debugging requires both a host computer and a target computer. Regardless, you can use the WinDbg debugger and UMDF debugger extensions to debug your UMDF driver.

The following topics describe how to enable user-mode debugging and how to use UMDF debugger extensions:

Enabling a Debugger

Attaching a User-Mode Debugger

Using UMDF Debugger Extensions


Enabling a Debugger

If a debugger is enabled, the computer can detect the debugger after the driver manager starts the driver host process for the device and the request to attach the debugger is made. To enable the debugger, you should set the HostProcessDbgBreakOnStart entry, which is located under the following key in the registry, to a nonzero value.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}

Note The computer is preconfigured with HostProcessDbgBreakOnStart set to 0. That is, the computer is preconfigured so that it will not detect any debugger.

Setting HostProcessDbgBreakOnStart configures an initial breakpoint (IB) time-out, in seconds. By default, the IB time-out is configured to detect the user-mode debugger. However, the computer can detect both user-mode and kernel-mode debuggers by setting the high bit (0x8000000) in the HostProcessDbgBreakOnStart value.

The UMDF searches for the user-mode debugger once a second until the IB time-out elapses. If a user-mode debugger is not detected and attached within the IB time-out value and the high bit in HostProcessDbgBreakOnStart is set, the UMDF attempts to break into the kernel-mode debugger.

Enabling the IB time-out disables other UMDF time-outs (for example, Plug and Play [PnP]operations). For more information about UMDF time-outs, see Enforcing Time-Outs.

The following examples describe scenarios of enabling a debugger:

  • HostProcessDbgBreakOnStart set to 0x0000004

    The UMDF attempts to connect to the user-mode debugger once a second for 4 seconds. The UMDF never tries to connect to the kernel-mode debugger.

  • HostProcessDbgBreakOnStart set to 0x8000000

    The UMDF waits 0 seconds and then attempts to connect to the user-mode debugger. If the user-mode debugger is not attached within 0 seconds (that is, the UMDF makes only one attachment attempt), the UMDF tries to connect to the kernel-mode debugger.

  • HostProcessDbgBreakOnStart set to 0x8000004

    The UMDF attempts to connect to the user-mode debugger once a second for 4 seconds. If the user-mode debugger is not attached within 4 seconds, the UMDF tries to connect to the kernel-mode debugger.


Attaching a User-Mode Debugger

After the driver manager starts the driver host process for the device, you can attach a user-mode debugger. How you attach the debugger depends on how many devices are attached to the computer:

  • If a single device is attached, run the following command:

    windbg –pn WUDFHost.exe

    Run this command repeatedly until a host process to debug is discovered.

  • If multiple devices are attached, determine the process identifier (PID) of a particular host and run the following command:

    windbg –p PID

    You can use the operating system–supplied Tasklist.exe to determine the PID of a host process. (Tasklist.exe is a command-line application that provides a user with a list of processes that are running on the operating system.)


Using UMDF Debugger Extensions

Before you can use UMDF debugger extensions, the debugger you use must load the UMDF debugger dynamic link library (DLL). In the WDK, the UMDF debugger DLL (WudfExt.dll) is located in the %DDKROOT%\bin directory. To load the UMDF debugger DLL at the debugger's command prompt, enter the following command:

!load WudfExt.dll

After you load the UMDF debugger DLL, you can use the following UMDF debugger extensions.

Extension | Description
!help | Shows all debugger extensions that WudfExt.dll supports
!devstack | Shows device stacks in the host process
!dumpirps | Shows the list of pending messages in the host process
!umirp | Shows information about a user-mode I/O request packet (IRP)
!wdfdriverinfo | Shows information about a UMDF driver
!wdfdevicequeue | Shows the I/O queues for a device
!wdfqueue | Shows information about an I/O queue
!wdfrequest | Shows information about an I/O request


User-Mode Driver Framework Reference

The following sections document the Component Object Model (COM) interfaces that are implemented by user-mode drivers that are built on the Windows Driver Foundation (WDF) - User-Mode Driver Framework (UMDF) platform and the COM interfaces that are used by those user-mode drivers. Prototypes for the COM interfaces are in Wudfddi.h.

User-Mode Driver Framework Interfaces Implemented by Drivers

User-Mode Driver Framework Interfaces Used by Drivers

User-Mode Driver Framework Structures and Enumeration Types


User-Mode Driver Framework Interfaces Implemented by Drivers

The following sections document the interfaces that are implemented by user-mode drivers for the User-Mode Driver Framework (UMDF) platform:

IDriverEntry

IFileCallbackCleanup

IFileCallbackClose

IImpersonateCallback

IObjectCleanup

IPnpCallback

IPnpCallbackHardware

IPnpCallbackSelfManagedIo

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackIoResume

IQueueCallbackIoStop

IQueueCallbackRead

IQueueCallbackStateChange

IQueueCallbackWrite

IRequestCallbackCancel

IRequestCallbackRequestCompletion


IDriverEntry

The IDriverEntry interface exposes the user-mode driver's main entry and exit points. In addition to the methods that IDriverEntry inherits from the IUnknown interface, IDriverEntry supports the following methods:

IDriverEntry::OnDeinitialize

IDriverEntry::OnDeviceAdd

IDriverEntry::OnInitialize


IDriverEntry::OnDeinitialize

The OnDeinitialize method performs any operations that are necessary before a system unloads a driver.

void
  OnDeinitialize(
    IN IWDFDriver*  pWdfDriver
    );

Parameters

pWdfDriver
A pointer to the IWDFDriver interface for the driver object that represents the driver that the system unloads.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The framework creates a new driver object for each driver that is loaded in the driver host process. When a driver is about to be unloaded from the host process, the framework calls OnDeinitialize to notify the driver of the departure and passes the IWDFDriver interface in the call. The system unloads the driver after OnDeinitialize returns.

See Also

IWDFDriver


IDriverEntry::OnDeviceAdd

The OnDeviceAdd method adds a new device to a system.

HRESULT
  OnDeviceAdd(
    IN IWDFDriver*  pWdfDriver,
    IN IWDFDeviceInitialize*  pWdfDeviceInit
    );

Parameters

pWdfDriver
A pointer to the IWDFDriver interface for the parent driver object that the new device belongs to.
pWdfDeviceInit
A pointer to the IWDFDeviceInitialize interface that the driver uses to initialize the newly created device.

Return Value

OnDeviceAdd returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A new device object is created for each device that is loaded in the driver host process. When a new device arrives in the system, the framework calls OnDeviceAdd to notify the driver of the arrival and passes the IWDFDriver and IWDFDeviceInitialize interfaces in the call. The driver can call the IWDFDeviceInitialize::RetrieveDevicePropertyStore method to query for the device information that is provided as part of device installation. The driver can call the IWDFDriver::CreateDevice method to configure and create the device.

The IWDFDeviceInitialize interface that the pWdfDeviceInit parameter points to is valid only in the context of the OnDeviceAdd method.

See Also

IWDFDeviceInitialize, IWDFDeviceInitialize::RetrieveDevicePropertyStore, IWDFDriver, IWDFDriver::CreateDevice


IDriverEntry::OnInitialize

The OnInitialize method performs any operations that are necessary to initialize a driver.

HRESULT
  OnInitialize(
    IN IWDFDriver*  pWdfDriver
    );

Parameters

pWdfDriver
A pointer to the IWDFDriver interface for the framework driver object that represents the driver that is loaded in the host process.

Return Value

OnInitialize returns S_OK if the driver completed its global initialization. Otherwise, this method returns one of the error codes that are defined in Winerror.h. If the driver returns an error code, the framework will not load the driver.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The framework creates a new driver object for each driver that is loaded in the driver host process. When a driver enters the system, the framework calls OnInitialize to notify the driver and passes the IWDFDriver interface in the call.

See Also

IWDFDriver


IFileCallbackCleanup

A file object notifies a driver when a cleanup request is available for the driver. The file object notifies the driver in response to an application calling the CloseHandle Microsoft Win32 function. The driver can handle the notification by registering the IFileCallbackCleanup interface.

A driver registers the IFileCallbackCleanup interface when it calls the IWDFDriver::CreateDevice method to create a device object.

In addition to the methods that IFileCallbackCleanup inherits from the IUnknown interface, IFileCallbackCleanup supports the following method:

IFileCallbackCleanup::OnCleanupFile


IFileCallbackCleanup::OnCleanupFile

The OnCleanupFile method cancels all I/O requests that a driver has pending in the framework queue.

void
  OnCleanupFile(
    IN IWDFFile*  pWdfFileObject
    );

Parameters

pWdfFileObject
A pointer to the IWDFFile interface for the file object that is associated with the device.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The framework calls the OnCleanupFile method to notify the driver to cancel all I/O requests that it has pending. The framework notifies the driver in response to an application calling the Microsoft Win32 CloseHandle function.

See Also

IWDFFile


IFileCallbackClose

A file object notifies a driver when a close request is available for the driver. The driver can handle the notification by registering the IFileCallbackClose interface.

A driver registers the IFileCallbackClose interface when it calls the IWDFDriver::CreateDevice method to create a device object.

In addition to the methods that IFileCallbackClose inherits from the IUnknown interface, IFileCallbackClose supports the following method:

IFileCallbackClose::OnCloseFile


IFileCallbackClose::OnCloseFile

The OnCloseFile method is called when the last reference count on a file object goes down to zero and before the file object is released.

void
  OnCloseFile(
    IN IWDFFile*  pWdfFileObject
    );

Parameters

pWdfFileObject
A pointer to the IWDFFile interface for the file object that is associated with the device.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFFile


IImpersonateCallback

The IImpersonateCallback interface contains a method that handles impersonation.

In addition to the methods that IImpersonateCallback inherits from the IUnknown interface, IImpersonateCallback supports the following method:

IImpersonateCallback::OnImpersonate


IImpersonateCallback::OnImpersonate

The OnImpersonate method handles impersonation.

void
  OnImpersonate(
    IN void*  Context
    );

Parameters

Context
A pointer to a context that was previously supplied in the IWDFIoRequest::Impersonate method.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

Typically, a driver handles impersonation only when it escapes to a Win32 operation. For example, if the driver must open a data file on behalf of an application that sent an I/O operation, the driver can escape to open a data file.

To ensure that impersonation does not leak across driver callback functions or between device drivers, OnImpersonate should not call any framework methods.

See Also

IWDFIoRequest::Impersonate


IObjectCleanup

Any driver that stores a reference-counted COM interface to WDF object must support the IObjectCleanup interface to prevent interface leakage. Note that drivers, in general, are not required to hold references to WDF objects.

The framework calls the method of the IObjectCleanup interface when the associated framework object is about to be released.

In addition to the methods that IObjectCleanup inherits from the IUnknown interface, IObjectCleanup supports the following method:

IObjectCleanup::OnCleanup


IObjectCleanup::OnCleanup

The OnCleanup method releases any references to a WDF object to prevent interface leakage.

void
  OnCleanup(
    IN IWDFObject*  pWdfObject
    );

Parameters

pWdfObject
A pointer to the IWDFObject interface of a object that is about to be released.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The framework calls OnCleanup as part of a WDF object destruction sequence. The framework calls OnCleanup before the WDF object is destroyed.

See Also

IWDFObject


IPnpCallback

The IPnpCallback interface is a Plug and Play (PnP) and power management (PM) interface.

In addition to the methods that IPnpCallback inherits from the IUnknown interface, IPnpCallback supports the following methods:

IPnpCallback::OnD0Entry

IPnpCallback::OnD0Exit

IPnpCallback::OnQueryRemove

IPnpCallback::OnQueryStop

IPnpCallback::OnSurpriseRemoval


IPnpCallback::OnD0Entry

The OnD0Entry method notifies a driver when a device enters the D0 power state so that the driver can perform necessary operations (for example, the driver might have to enable the device when the device enters its working (D0) state).

HRESULT
  OnD0Entry(
    IN IWDFDevice*  pWdfDevice,
    IN WDF_POWER_DEVICE_STATE  previousState
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device that enters the D0 power state.
previousState
A WDF_POWER_DEVICE_STATE-typed value that identifies the power state of the device before the device entered the D0 power state.

Return Value

OnD0Entry returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice, WDF_POWER_DEVICE_STATE


IPnpCallback::OnD0Exit

The OnD0Exit method notifies a driver when a device exits the D0 power state so the driver can perform necessary operations (for example, the driver might have to disable the device when the device exits its working (D0) state).

HRESULT
  OnD0Exit(
    IN IWDFDevice*  pWdfDevice,
    IN WDF_POWER_DEVICE_STATE  newState
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device that exits the D0 power state.
newState
A WDF_POWER_DEVICE_STATE-typed value that identifies the new power state that the device is set to after the device exits the D0 power state.

Return Value

OnD0Exit returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice, WDF_POWER_DEVICE_STATE


IPnpCallback::OnQueryRemove

The OnQueryRemove method notifies a driver before a device is removed from a computer so that the driver can perform necessary operations.

HRESULT
  OnQueryRemove(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device that will be removed.

Return Value

OnQueryRemove returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice


IPnpCallback::OnQueryStop

The OnQueryStop method notifies a driver before a device is stopped so that the driver can perform necessary operations.

HRESULT
  OnQueryStop(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device that will be stopped.

Return Value

OnQueryStop returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice


IPnpCallback::OnSurpriseRemoval

The OnSurpriseRemoval method notifies a driver after a device is removed from a computer unexpectedly so that the driver can perform necessary operations.

void
  OnSurpriseRemoval(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device that is removed unexpectedly.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice


IPnpCallbackHardware

The IPnpCallbackHardware interface is a Plug and Play (PnP) and power management (PM) interface.

In addition to the methods that IPnpCallbackHardware inherits from the IUnknown interface, IPnpCallbackHardware supports the following methods:

IPnpCallbackHardware::OnPrepareHardware

IPnpCallbackHardware::OnReleaseHardware


IPnpCallbackHardware::OnPrepareHardware

The OnPrepareHardware method notifies a driver to perform operations that are necessary to make the specified hardware accessible.

HRESULT
  OnPrepareHardware(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device to make accessible.

Return Value

OnPrepareHardware returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

Receiving a call to the OnPrepareHardware method is equivalent to a Microsoft Windows Driver Model (WDM) driver receiving an IRP_MN_START_DEVICE IRP.

See Also

IRP_MN_START_DEVICE, IWDFDevice


IPnpCallbackHardware::OnReleaseHardware

The OnReleaseHardware method notifies a driver to perform operations that are necessary when the specified hardware is no longer accessible.

HRESULT
  OnReleaseHardware(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device that is no longer accessible.

Return Value

OnReleaseHardware returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice


IPnpCallbackSelfManagedIo

The IPnpCallbackSelfManagedIo interface is a Plug and Play (PnP) and power management (PM) interface.

In addition to the methods that IPnpCallbackSelfManagedIo inherits from the IUnknown interface, IPnpCallbackSelfManagedIo supports the following methods:

IPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup

IPnpCallbackSelfManagedIo::OnSelfManagedIoFlush

IPnpCallbackSelfManagedIo::OnSelfManagedIoInit

IPnpCallbackSelfManagedIo::OnSelfManagedIoRestart

IPnpCallbackSelfManagedIo::OnSelfManagedIoStop

IPnpCallbackSelfManagedIo::OnSelfManagedIoSuspend


IPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup

The OnSelfManagedIoCleanup method releases memory for a device's self-managed I/O operations, after the device is removed.

void
  OnSelfManagedIoCleanup(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device that the driver performs cleanup for.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice


IPnpCallbackSelfManagedIo::OnSelfManagedIoFlush

The OnSelfManagedIoFlush method flushes the device for a device's self-managed I/O operations.

void
  OnSelfManagedIoFlush(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device that is flushed.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice


IPnpCallbackSelfManagedIo::OnSelfManagedIoInit

The OnSelfManagedIoInit method initializes a device's self-managed I/O operations.

HRESULT
  OnSelfManagedIoInit(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device whose self-managed I/O operations are initialized.

Return Value

OnSelfManagedIoInit returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice


IPnpCallbackSelfManagedIo::OnSelfManagedIoRestart

The OnSelfManagedIoRestart method restarts a device's self-managed I/O operations.

HRESULT
  OnSelfManagedIoRestart(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device whose self-managed I/O operations are restarted.

Return Value

OnSelfManagedIoRestart returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice


IPnpCallbackSelfManagedIo::OnSelfManagedIoStop

The OnSelfManagedIoStop method is not used in the current version of the UMDF.


IPnpCallbackSelfManagedIo::OnSelfManagedIoSuspend

The OnSelfManagedIoSuspend method suspends a device's self-managed I/O operations.

HRESULT
  OnSelfManagedIoStop(
    IN IWDFDevice*  pWdfDevice
    );

Parameters

pWdfDevice
A pointer to the IWDFDevice interface for the device object of the device whose self-managed I/O operations are suspended.

Return Value

OnSelfManagedIoSuspend returns S_OK if the operation succeeds Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice


IQueueCallbackCreate

An I/O queue notifies a driver when an open file request is available for the driver. The I/O queue notifies the driver in response to an application calling the Microsoft Win32 CreateFile function. The driver can handle the notification by registering the IQueueCallbackCreate interface.

A driver registers the IQueueCallbackCreate interface when it calls the IWDFDevice::CreateIoQueue method to create an I/O queue or to configure the default I/O queue. For more information about creating or configuring an I/O queue, see Configuring Dispatch Mode for an I/O Queue.

In addition to the methods that IQueueCallbackCreate inherits from the IUnknown interface, IQueueCallbackCreate supports the following method:

IQueueCallbackCreate::OnCreateFile


IQueueCallbackCreate::OnCreateFile

The OnCreateFile method is called to handle an open file request when an application opens a device through the Microsoft Win32 CreateFile function.

void
  OnCreateFile(
    IN IWDFIoQueue*  pWdfQueue,
    IN IWDFIoRequest*  pWdfRequest,
    IN IWDFFile*  pWdfFileObject
    );

Parameters

pWdfQueue
A pointer to the IWDFIoQueue interface for the I/O queue object that the request arrives from.
pWdfRequest
A pointer to the IWDFIoRequest interface that represents the framework request object.
pWdfFileObject
A pointer to the IWDFFile interface for the file object that is associated with the device. This information is provided for convenience because the driver can call the IWDFIoRequest::GetCreateParameters method to obtain the file object.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The framework calls the OnCreateFile method when an application opens a device through the Win32 CreateFile function to perform an I/O operation, such as reading from or writing to a file.

See Also

IWDFFile, IWDFIoQueue, IWDFIoRequest, IWDFIoRequest::GetCreateParameters


IQueueCallbackDefaultIoHandler

The IQueueCallbackDefaultIoHandler interface contains a method that handles I/O requests that no other method is registered to handle.

In addition to the methods that IQueueCallbackDefaultIoHandler inherits from the IUnknown interface, IQueueCallbackDefaultIoHandler supports the following method:

IQueueCallbackDefaultIoHandler::OnDefaultIoHandler


IQueueCallbackDefaultIoHandler::OnDefaultIoHandler

The OnDefaultIoHandler method handles I/O requests that no other method is registered to handle.

void
  OnDefaultIoHandler(
    IN IWDFIoQueue*  pWdfQueue,
    IN IWDFIoRequest*  pWdfRequest
    );

Parameters

pWdfQueue
A pointer to the IWDFIoQueue interface for the I/O queue object that the default I/O request arrives from.
pWdfRequest
A pointer to the IWDFIoRequest interface that represents the framework request object.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFIoQueue, IWDFIoRequest


IQueueCallbackDeviceIoControl

An I/O queue object notifies a driver when a device I/O control request is available for the driver. The I/O queue object notifies the driver in response to an application calling the Microsoft Win32 DeviceIoControl function. The driver can handle the notification by registering the IQueueCallbackDeviceIoControl interface.

A driver registers the IQueueCallbackDeviceIoControl interface when it calls the IWDFDevice::CreateIoQueue method to create an I/O queue or to configure the default I/O queue. For more information about creating or configuring an I/O queue, see Configuring Dispatch Mode for an I/O Queue.

In addition to the methods that IQueueCallbackDeviceIoControl inherits from the IUnknown interface, IQueueCallbackDeviceIoControl supports the following method:

IQueueCallbackDeviceIoControl::OnDeviceIoControl


IQueueCallbackDeviceIoControl::OnDeviceIoControl

The OnDeviceIoControl method is called to handle a device I/O control request when an application performs a specific operation on a device through the Microsoft Win32 DeviceIoControl function.

void
  OnDeviceIoControl(
    IN IWDFIoQueue*  pWdfQueue,
    IN IWDFIoRequest*  pWdfRequest,
    IN ULONG  ControlCode,
    IN SIZE_T  InBufferSize,
    IN SIZE_T  OutBufferSize
    );

Parameters

pWdfQueue
A pointer to the IWDFIoQueue interface for the I/O queue object that the request arrives from.
pWdfRequest
A pointer to the IWDFIoRequest interface that represents the framework request object.
ControlCode
The driver-defined or system-defined I/O control code (IOCTL) that identifies the specific operation to be performed and that is associated with the request.
InBufferSize
The size, in bytes, of the input buffer for the request.
OutBufferSize
The size, in bytes, of the output buffer for the request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A driver can implement a single OnDeviceIoControl method for all I/O queues or separate OnDeviceIoControl methods for each I/O queue.

The OnDeviceIoControl method receives every device I/O control request type from a queue. (The request type is identified by the WdfRequestDeviceIoControl value of the WDF_REQUEST_TYPE enumeration type for the request.)

For more information about the driver's methods that are associated with queues and that the framework calls, see I/O Queue Event Callback Functions. The OnDeviceIoControl method must process each received device I/O control request. For more information about how UMDF drivers process I/O requests, see Processing I/O Requests.

The driver can call the IWDFIoRequest::GetDeviceIoControlParameters, IWDFIoRequest::GetInputMemory, and IWDFIoRequest::GetOutputMemory methods to retrieve information about the request and the input and output buffers.

See Also

IWDFIoQueue, IWDFIoRequest, WDF_REQUEST_TYPE


IQueueCallbackIoResume

The IQueueCallbackIoResume interface contains a method that resumes the processing of an I/O request from a queue.

In addition to the methods that IQueueCallbackIoResume inherits from the IUnknown interface, IQueueCallbackIoResume supports the following method:

IQueueCallbackIoResume::OnIoResume


IQueueCallbackIoResume::OnIoResume

The OnIoResume method resumes the processing of the specified I/O request from the specified queue.

void
  OnIoResume(
    IN IWDFIoQueue*  pWdfQueue,
    IN IWDFIoRequest*  pWdfRequest
    );

Parameters

pWdfQueue
A pointer to the IWDFIoQueue interface for the I/O queue object that processing of the I/O request is resumed from.
pWdfRequest
A pointer to the IWDFIoRequest interface that represents the framework request object that is resumed.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFIoQueue, IWDFIoRequest


IQueueCallbackIoStop

The IQueueCallbackIoStop interface contains a method that stops the processing of an I/O request from a queue.

In addition to the methods that IQueueCallbackIoStop inherits from the IUnknown interface, IQueueCallbackIoStop supports the following method:

IQueueCallbackIoStop::OnIoStop


IQueueCallbackIoStop::OnIoStop

The OnIoStop method stops the processing of the specified I/O request from the specified queue.

void
  OnIoStop(
    IN IWDFIoQueue*  pWdfQueue,
    IN IWDFIoRequest*  pWdfRequest,
    IN ULONG  ActionFlags
    );

Parameters

pWdfQueue
A pointer to the IWDFIoQueue interface for the I/O queue object that processing of the I/O request is stopped from.
pWdfRequest
A pointer to the IWDFIoRequest interface that represents the framework request object whose processing is stopped.
ActionFlags
A valid bitwise OR of WDF_REQUEST_STOP_ACTION_FLAGS-typed values that identifies the state of a stop action request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFIoQueue, IWDFIoRequest, WDF_REQUEST_STOP_ACTION_FLAGS


IQueueCallbackRead

An I/O queue notifies a driver when a read request is available for the driver. The I/O queue notifies the driver when an application calls the Microsoft Win32 ReadFile or ReadFileEx function. The driver can handle the notification by registering the IQueueCallbackRead interface.

A driver registers the IQueueCallbackRead interface when it calls the IWDFDevice::CreateIoQueue method to create an I/O queue or to configure the default I/O queue. For more information about creating or configuring an I/O queue, see Configuring Dispatch Mode for an I/O Queue.

In addition to the methods that IQueueCallbackRead inherits from the IUnknown interface, IQueueCallbackRead supports the following method:

IQueueCallbackRead::OnRead


IQueueCallbackRead::OnRead

The OnRead method is called to handle a read request when an application reads information from a device through the Microsoft Win32 ReadFile or ReadFileEx function.

void
  OnRead(
    IN IWDFIoQueue*  pWdfQueue,
    IN IWDFIoRequest*  pWdfRequest,
    IN SIZE_T  NumOfBytesToRead
    );

Parameters

pWdfQueue
A pointer to the IWDFIoQueue interface for the I/O queue object that the request arrives from.
pWdfRequest
A pointer to the IWDFIoRequest interface that represents the framework request object.
NumOfBytesToRead
The size, in bytes, of the read buffer for the request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A driver can implement a single OnRead method for all I/O queues or separate OnRead methods for each I/O queue.

The OnRead method receives every read request type from the queue. (The read request type is identified by the WdfRequestRead value of the WDF_REQUEST_TYPE enumeration type for the request.) The OnRead method must process each received read request. For more information about how UMDF drivers process I/O requests, see Processing I/O Requests.

The driver can call the IWDFIoRequest::GetReadParameters and IWDFIoRequest::GetOutputMemory methods to retrieve information about the request and the read buffer.

See Also

IWDFIoQueue, IWDFIoRequest, WDF_REQUEST_TYPE


IQueueCallbackStateChange

An I/O queue object raises an event when it changes state. A driver can consume the event by registering the IQueueCallbackStateChange interface.

In addition to the methods that IQueueCallbackStateChange inherits from the IUnknown interface, IQueueCallbackStateChange supports the following method:

IQueueCallbackStateChange::OnStateChange


IQueueCallbackStateChange::OnStateChange

The OnStateChange method is called when the state of the I/O queue object changes.

void
  OnStateChange(
    IN IWDFIoQueue*  pWdfQueue,
    IN WDF_IO_QUEUE_STATE  QueueState
    );

Parameters

pWdfQueue
A pointer to the IWDFIoQueue interface for the I/O queue object whose state changes.
QueueState
A valid bitwise OR of WDF_IO_QUEUE_STATE-typed values that indicates status for the queue.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFIoQueue, WDF_IO_QUEUE_STATE


IQueueCallbackWrite

An I/O queue object notifies a driver when a write request is available for the driver. The I/O queue object notifies the driver when an application calls the Microsoft Win32 WriteFile or WriteFileEx function. The driver can handle the notification by registering the IQueueCallbackWrite interface.

A driver registers the IQueueCallbackWrite interface when it calls the IWDFDevice::CreateIoQueue method to create an I/O queue or to configure the default I/O queue. For more information about creating or configuring I/O queues, see Configuring Dispatch Mode for an I/O Queue.

In addition to the methods that IQueueCallbackWrite inherits from the IUnknown interface, IQueueCallbackWrite supports the following method:

IQueueCallbackWrite::OnWrite


IQueueCallbackWrite::OnWrite

The OnWrite method is called to handle a write request when an application writes information to a device through the Microsoft Win32 WriteFile or WriteFileEx function.

void
  OnWrite(
    IN IWDFIoQueue*  pWdfQueue,
    IN IWDFIoRequest*  pWdfRequest,
    IN SIZE_T  NumOfBytesToWrite
    );

Parameters

pWdfQueue
A pointer to the IWDFIoQueue interface for the I/O queue object that the request arrives from.
pWdfRequest
A pointer to the IWDFIoRequest interface that represents the framework request object.
NumOfBytesToWrite
The size, in bytes, of the write buffer for the request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A driver can implement a single OnWrite method for all I/O queues or separate OnWrite methods for each I/O queue.

The OnWrite method receives every write request type from the queue. (The write request type is identified by the WdfRequestWrite value of the WDF_REQUEST_TYPE enumeration type for the request.) The OnWrite method must process each received write request. For more information about how UMDF drivers process I/O requests, see Processing I/O Requests.

The driver can call the IWDFIoRequest::GetWriteParameters and IWDFIoRequest::GetInputMemory methods to retrieve information about the request and the write buffer.

See Also

IWDFIoQueue, IWDFIoRequest, WDF_REQUEST_TYPE


IRequestCallbackCancel

A driver is notified when an I/O request that the driver is currently processing is to be canceled. The driver is notified when an application calls the Microsoft Win32 CancelIo, CancelIoEx, or CancelSynchronousIo function. The driver can handle the notification by registering the IRequestCallbackCancel interface.

A driver registers the IRequestCallbackCancel interface when it calls the IWDFIoRequest::MarkCancelable method to enable the canceling of an I/O request. For more information about how to cancel I/O requests, see Canceling I/O Requests.

In addition to the methods that IRequestCallbackCancel inherits from the IUnknown interface, IRequestCallbackCancel supports the following method:

IRequestCallbackCancel::OnCancel


IRequestCallbackCancel::OnCancel

The OnCancel method is called when an application cancels an I/O operation through the Microsoft Win32 CancelIo, CancelIoEx, or CancelSynchronousIo function.

void
  OnCancel(
    IN IWDFIoRequest*  pWdfRequest
    );

Parameters

pWdfRequest
A pointer to the IWDFIoRequest interface that represents the framework request object to cancel.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The framework calls the OnCancel method to cancel the I/O request that the pWdfRequest parameter identifies. The driver should first determine whether it can cancel the I/O request. If the request can be canceled, the driver should cancel it. For more information about canceling a request, see Canceling I/O Requests.

If the driver cancels the request, the driver must also complete the request by calling the IWDFIoRequest::Complete method with the CompletionStatus parameter set to HRESULT_FROM_WIN32(ERROR_CANCELLED).

The framework does not call OnCancel to cancel a request unless the driver previously called the IWDFIoRequest::MarkCancelable method to enable cancellation of the request and to register the IRequestCallbackCancel interface.

See Also

IWDFIoRequest, IWDFIoRequest::Complete, IWDFIoRequest::MarkCancelable


IRequestCallbackRequestCompletion

A driver implements the IRequestCallbackRequestCompletion interface to complete a request object.

A driver registers the IRequestCallbackRequestCompletion interface when it calls the IWDFIoRequest::SetCompletionCallback method. For more information about how a driver completes an I/O request, see Completing I/O Requests.

In addition to the methods that IRequestCallbackRequestCompletion inherits from the IUnknown interface, IRequestCallbackRequestCompletion supports the following method:

IRequestCallbackRequestCompletion::OnCompletion


IRequestCallbackRequestCompletion::OnCompletion

The OnCompletion method completes the specified request.

void
  OnCompletion(
    IN IWDFIoRequest*  pWdfRequest,
    IN IWDFIoTarget*  pIoTarget,
    IN IWDFRequestCompletionParams*  pParams,
    IN void*  pContext
    );

Parameters

pWdfRequest
A pointer to the IWDFIoRequest interface that represents the framework request object.
pIoTarget
A pointer to the IWDFIoTarget interface for the I/O target object that represents the lower driver in the stack where the request was previously sent.
pParams
A pointer to the IWDFRequestCompletionParams interface for the parameters object for the completion request.
pContext
A pointer to a buffer that contains context information that is related to the completion request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFIoRequest, IWDFRequestCompletionParams, IWDFIoTarget


User-Mode Driver Framework Interfaces Used by Drivers

The User-Mode Driver Framework (UMDF) consists of a set of cooperating objects. The framework creates and manages a series of objects that are exposed to user-mode device drivers. Some of these objects are created by the framework in response to application-triggered actions, such as an I/O request, and other framework objects, such as I/O queues, are created by the driver by calling the appropriate framework interface. The following sections describe the interfaces that the framework objects expose:

IWDFDevice

IWDFDeviceInitialize

IWDFDriver

IWDFDriverCreatedFile

IWDFFile

IWDFFileHandleTargetFactory

IWDFIoQueue

IWDFIoRequest

IWDFIoTarget

IWDFIoTargetStateManagement

IWDFMemory

IWDFNamedPropertyStore

IWDFObject

IWDFRequestCompletionParams

IWDFUsbInterface

IWDFUsbTargetDevice

IWDFUsbTargetFactory

IWDFUsbTargetPipe


IWDFDevice

The IWDFDevice interface exposes a device object, which is a representation of a device on the system. Each device object has a parent driver object. When a new device arrives in the system, the framework calls the parent driver's IDriverEntry::OnDeviceAdd callback function to notify the driver about the arrival. The driver can then call the IWDFDriver::CreateDevice method to receive a pointer to the IWDFDevice interface for the new device object.

In addition to the methods that IWDFDevice inherits from the IWDFObject interface, IWDFDevice supports the following methods:

IWDFDevice::AssignDeviceInterfaceState

IWDFDevice::CommitPnpState

IWDFDevice::ConfigureRequestDispatching

IWDFDevice::CreateDeviceInterface

IWDFDevice::CreateIoQueue

IWDFDevice::CreateRequest

IWDFDevice::CreateSymbolicLink

IWDFDevice::CreateWdfFile

IWDFDevice::GetDefaultIoQueue

IWDFDevice::GetDefaultIoTarget

IWDFDevice::GetDriver

IWDFDevice::GetPnpState

IWDFDevice::PostEvent

IWDFDevice::RetrieveDeviceInstanceId

IWDFDevice::RetrieveDeviceName

IWDFDevice::RetrieveDevicePropertyStore

IWDFDevice::SetPnpState


IWDFDevice::AssignDeviceInterfaceState

The AssignDeviceInterfaceState method enables or disables the specified device interface instance for a device.

HRESULT
  AssignDeviceInterfaceState(
    IN LPCGUID  pDeviceInterfaceGuid,
    IN PCWSTR  pReferenceString,
    IN BOOL  Enable
    );

Parameters

pDeviceInterfaceGuid
A pointer to the GUID for a device interface class.
pReferenceString
A pointer to a NULL-terminated string that contains the name of the instance of the device interface.
Enable
A BOOL value that specifies whether the device interface instance should be enabled or disabled. TRUE indicates to enable; FALSE indicates to disable.

Return Value

AssignDeviceInterfaceState returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

For a code example of how to use the AssignDeviceInterfaceState method, see IWDFDevice::CreateDeviceInterface.

See Also

IWDFDevice::CreateDeviceInterface


IWDFDevice::CommitPnpState

The CommitPnpState method commits the state of the Plug and Play (PnP) property (that is, turns on, turns off, or sets to the default state) that the IWDFDevice::SetPnpState method set.

void
  CommitPnpState(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The values of the WDF_PNP_STATE enumeration identify the state of PnP for the device.

Example

For a code example of how to use the CommitPnpState method, see IWDFDevice::SetPnpState.

See Also

IWDFDevice::SetPnpState, WDF_PNP_STATE


IWDFDevice::ConfigureRequestDispatching

The ConfigureRequestDispatching method configures the queuing of I/O requests of the specified type to the specified I/O queue.

HRESULT
  ConfigureRequestDispatching(
    IN IWDFIoQueue*  pQueue,
    IN WDF_REQUEST_TYPE  RequestType,
    IN BOOL  Forward
    );

Parameters

pQueue
A pointer to the IWDFIoQueue interface for the I/O queue to configure.
RequestType
A WDF_REQUEST_TYPE-typed value that identifies the request type to be queued. The only valid WDF_REQUEST_TYPE values are WdfRequestCreate, WdfRequestRead, WdfRequestWrite, and WdfRequestDeviceIoControl.
Forward
A BOOL value that specifies whether requests of the specified type are queued. TRUE indicates to enable queuing requests; FALSE indicates to disable queuing requests.

Return Value

ConfigureRequestDispatching returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example shows how to configure a queue.

    //
    // Create the control queue and configure forwarding for I/O control code (IOCTL) requests
    //
    if (S_OK == hr) {
        PCMyControlQueue controlQueue;
        hr = CMyControlQueue::CreateInstance(this, &controlQueue);
        if (S_OK == hr) {
            hr = controlQueue->Configure();
            if (S_OK == hr) {
                hr = m_FxDevice->ConfigureRequestDispatching(
                           controlQueue->GetFxQueue(),
                           WdfRequestDeviceIoControl,
                           true
                           );
            }
            controlQueue->Release();
        }
    }

See Also

IWDFIoQueue, WDF_REQUEST_TYPE


IWDFDevice::CreateDeviceInterface

The CreateDeviceInterface method creates the specified device interface instance for a device.

HRESULT
  CreateDeviceInterface(
    IN LPCGUID  pDeviceInterfaceGuid,
    IN PCWSTR  pReferenceString
    );

Parameters

pDeviceInterfaceGuid
A pointer to the GUID for a device interface class.
pReferenceString
A pointer to a NULL-terminated string that contains the name of the instance of the device interface.

Return Value

CreateDeviceInterface returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

Drivers can use the pReferenceString parameter to differentiate different instances of a single interface. In other words, if a driver calls CreateDeviceInterface twice for the same device interface class, the driver can specify a different string for pReferenceString each time. When an instance of an interface is opened, the framework passes the instance's reference string to the driver. The reference string is appended to the path component of the interface instance's name. The driver can then use the reference string to determine which instance of the device interface class is being opened.

Example

The following code example shows how to create a device interface instance.

    //
    // Create the device interface.
    //
    HRESULT hr;
    if (S_OK == hr) {
        hr = m_FxDevice->CreateDeviceInterface(
                         &GUID_DEVINTERFACE_OSRUSBFX2,
                         NULL);
    }
    if (S_OK == hr) {
        hr = m_FxDevice->AssignDeviceInterfaceState(
                        &GUID_DEVINTERFACE_OSRUSBFX2,
                        NULL,
                        TRUE);
    }

See Also

IWDFDevice::AssignDeviceInterfaceState


IWDFDevice::CreateIoQueue

The CreateIoQueue method configures the default I/O queue that is associated with a device or creates a secondary I/O queue for the device.

HRESULT
  CreateIoQueue(
    IN IUnknown*  pCallbackInterface,
    IN BOOL  bDefaultQueue,
    IN WDF_IO_QUEUE_DISPATCH_TYPE  DispatchType,
    IN BOOL  bPowerManaged,
    IN BOOL  bAllowZeroLengthRequests,
    OUT IWDFIoQueue**  ppIoQueue
    );

Parameters

pCallbackInterface
A pointer to the IUnknown interface that the framework uses to determine the event callback functions that the driver subscribes to on the queue. These are the functions that the framework calls when the relevant events occur.
bDefaultQueue
A BOOL value that specifies whether to configure the default I/O queue or create a secondary I/O queue for the device. TRUE indicates to configure the default I/O queue; FALSE indicates to create a secondary I/O queue.
DispatchType
A WDF_IO_QUEUE_DISPATCH_TYPE-typed value that identifies how the driver must receive requests from the I/O queue.
bPowerManaged
A BOOL value that specifies whether the I/O queue is power managed. TRUE indicates the framework automatically coordinates dispatching for the I/O queue with Plug and Play (PnP) and the power state of the device; FALSE indicates no automatically coordinated dispatching.
bAllowZeroLengthRequests
A BOOL value that specifies whether the I/O queue permits the presentation of zero-length I/O requests to the driver. TRUE indicates the driver should never receive read and write requests that have zero-length buffers—that is, the framework automatically completes these request types for the driver. FALSE indicates the driver receives these request types.
ppIoQueue
A pointer to a variable that receives a pointer to the IWDFIoQueue interface for the newly created I/O queue object or the default I/O queue object.

Return Value

CreateIoQueue returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The IUnknown interface that the driver supplies for the pCallbackInterface parameter can support several queue callback functions. The framework calls the QueryInterface method on the supplied IUnknown interface multiple times to retrieve the interface methods that the driver supports. When applications perform actions that are related to the methods of the supported interfaces (such as, an I/O read request), the framework calls the methods (such as, the IQueueCallbackRead::OnRead method) to notify the driver. The framework calls QueryInterface for the following interfaces:

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackRead

IQueueCallbackWrite

When the driver passes either WdfIoQueueDispatchSequential or WdfIoQueueDispatchParallel for the DispatchType parameter of CreateIoQueue to create a nonmanual queue, CreateIoQueue can return success if the driver's queue callback object implements at least one of the preceding interfaces and indicates support of such interfaces through the IUnknown interface that pCallbackInterface points to.

When the driver passes WdfIoQueueDispatchManual for DispatchType to create a manual queue, CreateIoQueue can return success even if the driver's queue callback object does not implement any callback interfaces. For more information about the driver's callback objects, see Creating Callback Objects.

Example

For a code example of how to use the CreateIoQueue method, see IWDFDriver::CreateDevice.

See Also

IQueueCallbackCreate, IQueueCallbackDefaultIoHandler, IQueueCallbackDeviceIoControl, IQueueCallbackRead, IQueueCallbackWrite, IWDFIoQueue, WDF_IO_QUEUE_DISPATCH_TYPE


IWDFDevice::CreateRequest

The CreateRequest method creates an unformatted request object.

HRESULT
  CreateRequest(
    IN IUnknown*  pCallbackInterface,
    IN IWDFObject*  pParentObject,
    OUT IWDFIoRequest**  ppRequest
    );

Parameters

pCallbackInterface
A pointer to the IUnknown interface that the framework uses to determine the event callback functions that the driver subscribes to on the newly created request object. These are the functions that the framework calls when the relevant events occur.
pParentObject
A pointer to the IWDFObject interface for the parent object of the created I/O request object. If NULL, the device object becomes the default parent.
ppRequest
A pointer to a variable that receives a pointer to the IWDFIoRequest interface for the new request object.

Return Value

CreateRequest returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

Before a UMDF driver uses the request object that CreateRequest creates, the driver must format the request object. To format an I/O request object, the driver calls one of the following methods:

  • IWDFIoTarget::FormatRequestForIoctl
  • IWDFIoTarget::FormatRequestForRead
  • IWDFIoTarget::FormatRequestForWrite

If NULL is specified in the pParentObject parameter, the device object becomes the default parent object for the newly created I/O request object. If a UMDF driver creates an I/O request object that the driver uses with a specific I/O queue object or another I/O request object, the driver should set that queue or request object as the created request object's parent object. When the parent object is deleted, the created request object is deleted.

Example

The following code example shows how to create a request, format the request for reading, and send the request on.

HRESULT
CUmdfHidDevice::SendInterruptPipeRead(
    VOID
    )
{
    CComPtr<IWDFDevice> wdfDevice;

    HRESULT hr;

    // Allocate a new WDF request to send on the interrupt pipe.
    GetWdfDevice(&wdfDevice);
    hr = wdfDevice->CreateRequest(
                        static_cast<IRequestCallbackRequestCompletion*>(this),
                        wdfDevice,
                        &m_InterruptReadRequest
                        );

    if (SUCCEEDED(hr))
    {
        hr = m_InterruptPipe->FormatRequestForRead(m_InterruptReadRequest, NULL, m_ReadMemory, NULL, NULL);
    }

    // Issue the read to the pipe.
    if (SUCCEEDED(hr))
    {
        hr = m_InterruptReadRequest->Send(m_InterruptPipe, 0, 0);
    }

    return hr;
}

See Also

IWDFIoRequest, IWDFIoTarget::FormatRequestForIoctl, IWDFIoTarget::FormatRequestForRead, IWDFIoTarget::FormatRequestForWrite, IWDFObject


IWDFDevice::CreateSymbolicLink

The CreateSymbolicLink method creates a symbolic link for the device.

HRESULT
  CreateSymbolicLink(
    IN PCWSTR  pSymbolicLink
    );

Parameters

pSymbolicLink
A pointer to a NULL-terminated string that contains the name of the symbolic link for the device.

Return Value

CreateSymbolicLink returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A symbolic link is a file-system object that points to another file-system object. The object being pointed to is called the target.


IWDFDevice::CreateWdfFile

The CreateWdfFile method creates a file object for a driver to use.

HRESULT
  CreateWdfFile(
    IN LPCWSTR  pcwszFileName,
    OUT IWDFDriverCreatedFile**  ppFile
    );

Parameters

pcwszFileName
A pointer to a NULL-terminated string that contains the name of the file to create a file object from.
ppFile
A pointer to a buffer that receives a pointer to the IWDFDriverCreatedFile interface for the driver-created file object.

Return Value

CreateWdfFile returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFDriverCreatedFile


IWDFDevice::GetDefaultIoQueue

The GetDefaultIoQueue method retrieves the interface of the default I/O queue for a device.

void
  GetDefaultIoQueue(
    OUT IWDFIoQueue**  ppWdfIoQueue
    );

Parameters

ppWdfIoQueue
A pointer to a variable that receives a pointer to the IWDFIoQueue interface for the default I/O queue object.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFIoQueue


IWDFDevice::GetDefaultIoTarget

The GetDefaultIoTarget method retrieves the interface of the default I/O target for a device instance.

void
  GetDefaultIoTarget(
    OUT IWDFIoTarget**  ppWdfIoTarget
    );

Parameters

ppWdfIoTarget
A pointer to a variable that receives a pointer to the IWDFIoTarget interface for the default I/O target object.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFIoTarget


IWDFDevice::GetDriver

The GetDriver method retrieves the interface to the parent driver object of a device instance.

void
  GetDriver(
    OUT IWDFDriver**  ppWdfDriver
    );

Parameters

ppWdfDriver
A pointer to a variable that receives a pointer to the IWDFDriver interface for the parent driver object.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

For a code example of how to use the GetDriver method, see IWDFDriver::CreateWdfMemory.

See Also

IWDFDriver


IWDFDevice::GetPnpState

The GetPnpState method determines whether the given Plug and Play (PnP) property of a device is on or off (or set to the default state).

WDF_TRI_STATE
  GetPnpState(
    IN WDF_PNP_STATE  State
    );

Parameters

State
A WDF_PNP_STATE-typed value that identifies the PnP property to retrieve status about.

Return Value

GetPnpState returns one of the following WDF_TRI_STATE-typed values that identifies the state of the PnP property that is specified in the State parameter.

Value | Meaning
WdfUseDefault (0) | The PnP property is set to the default state.
WdfFalse (1) | The PnP property is turned off.
WdfTrue (2) | The PnP property is turned on.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFDevice::SetPnpState, WDF_PNP_STATE


IWDFDevice::PostEvent

The PostEvent method asynchronously notifies applications that are waiting for the specified event from a driver.

HRESULT
  PostEvent(
    IN REFGUID  EventGuid,
    IN WDF_EVENT_TYPE  EventType,
    IN BYTE*  pbData,
    IN DWORD  cbDataSize
    );

Parameters

EventGuid
The GUID for the event. The GUID is determined by the application and the driver and is opaque to the framework.
EventType
A WDF_EVENT_TYPE-typed value that identifies the type of event. The following table shows the possible values.
Value | Meaning
WdfEventReserved (0) | Reserved.
WdfEventBroadcast (1) The event is broadcast.

Applications can subscribe to WdfEventBroadcast-type events. To receive broadcast events, the application must register for notification through the Microsoft Win32 RegisterDeviceNotification function. WdfEventBroadcast-type events are exposed as DBT_CUSTOMEVENT-type events to applications.

pbData
A pointer to a buffer that contains data that is associated with the event.
cbDataSize
The size, in bytes, of data that pbData points to.

Return Value

PostEvent returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFDevice::RetrieveDeviceInstanceId

The RetrieveDeviceInstanceId method retrieves the identifier of an instance of a device.

HRESULT
  RetrieveDeviceInstanceId(
    OUT PWSTR  Buffer,
    IN/OUT DWORD*  pdwSizeInChars
    );

Parameters

Buffer
A pointer to a buffer that receives a NULL-terminated string that represents the identifier of an instance of the device, if the supplied buffer is non-NULL and RetrieveDeviceInstanceId is successful.
pdwSizeInChars
A pointer to a variable that receives the number of characters, including the NULL character, in the string that Buffer points to.

If Buffer is NULL, the value that the driver supplied is zero. The framework then returns the size, in characters, that are required for the identifier string.

If Buffer is non-NULL, the framework returns the size, in characters, of the identifier string.

Return Value

RetrieveDeviceInstanceId returns S_OK for the following scenarios:

  • The buffer that the Buffer parameter pointed to was non-NULL and large enough to hold the identifier string, including the NULL character, and the framework successfully copied the string into the supplied buffer and set the variable that is pointed to by the pdwSizeInChars parameter to the number of characters in the string.
  • The buffer at Buffer was NULL, the driver preset the variable at pdwSizeInChars to 0, and the framework set the variable at pdwSizeInChars to the number of characters that are required for the string.

RetrieveDeviceInstanceId returns HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) to indicate that the supplied buffer was non-NULL and did not contain enough space to hold the identifier string. The framework sets the variable at pdwSizeInChars to the number of characters that are required for the string.

RetrieveDeviceInstanceId might also return other HRESULT values.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFDevice::RetrieveDeviceName

The RetrieveDeviceName method retrieves the name of an underlying kernel-mode device.

HRESULT
  RetrieveDeviceName(
    OUT PWSTR  pDeviceName,
    IN/OUT DWORD*  pdwDeviceNameLength
    );

Parameters

pDeviceName
A pointer to a buffer that receives a NULL-terminated string that represents the name of the underlying kernel-mode device, if the buffer is non-NULL and RetrieveDeviceName is successful.
pdwDeviceNameLength
A pointer to a variable that receives the number of characters, including the NULL character, in the device name.

If the buffer at pDeviceName is NULL, the value that the driver supplies is zero. The framework then returns the size, in characters, that is required for the device name string.

If the buffer at pDeviceName is non-NULL, the framework returns the size, in characters, of the device name string.

Return Value

RetrieveDeviceName returns S_OK for the following scenarios:

  • The buffer that the pDeviceName parameter pointed to was non-NULL and large enough to hold the name string, including the NULL character, and the framework successfully copied the string into the supplied buffer and set the variable that is pointed to by pdwDeviceNameLength to the number of characters in the string.
  • The buffer at pDeviceName was NULL, the driver preset the variable at pdwDeviceNameLength to 0, and the framework set the variable at pdwDeviceNameLength to the number of characters that were required for the string.

RetrieveDeviceName returns HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) to indicate that the supplied buffer was non-NULL and did not contain enough space to hold the device name. The framework sets the variable at pdwDeviceNameLength to the number of characters that are required for the string.

RetrieveDeviceName might also return other HRESULT values.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The device name is not the physical device object (PDO) name. Instead, the device name is the name of the reflector. The driver must target all I/O to this device object.

Example

The following code example shows how to retrieve the name of an underlying kernel-mode device.

    PWSTR deviceName = NULL;
    DWORD deviceNameCch = 0;
    HRESULT hr;
    //
    // Get the length of the device name to allocate a buffer
    //
    hr = m_FxDevice->RetrieveDeviceName(NULL, &deviceNameCch);
    //
    // Allocate the buffer
    //
    deviceName = new WCHAR[deviceNameCch];

    if (deviceName == NULL) {
        hr = E_OUTOFMEMORY;
        goto Exit1;
    }
    //
    // Get the device name
    //
    hr = m_FxDevice->RetrieveDeviceName(deviceName, &deviceNameCch);

    // Open the device and get the handle

    m_Handle = CreateFile(deviceName,
                         (GENERIC_READ | GENERIC_WRITE),
                         0,
                         NULL,
                         OPEN_EXISTING,
                         FILE_FLAG_OVERLAPPED,
                         NULL);


IWDFDevice::RetrieveDevicePropertyStore

The RetrieveDevicePropertyStore method retrieves a device property store that clients can read and write device properties through.

HRESULT
  RetrieveDevicePropertyStore(
    IN PCWSTR  pcwszServiceName,
    IN WDF_PROPERTY_STORE_RETRIEVE_FLAGS  Flags,
    OUT IWDFNamedPropertyStore**  ppPropStore,
    OUT WDF_PROPERTY_STORE_DISPOSITION*  pDisposition
    );

Parameters

pcwszServiceName
A pointer to a NULL-terminated string that represents the name of the device property store.
Flags
A WDF_PROPERTY_STORE_RETRIEVE_FLAGS-typed value that identifies how to retrieve the device property store.
ppPropStore
A pointer to a buffer that receives a pointer to the IWDFNamedPropertyStore interface that is used to retrieve device properties.
pDisposition
A pointer to a variable that receives a WDF_PROPERTY_STORE_DISPOSITION-typed value that identifies whether the framework created the device property store or the device property store already existed.

Return Value

RetrieveDevicePropertyStore returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The caller should call the Release method of the IWDFNamedPropertyStore interface after finishing with the property store.

Example

To be supplied.

See Also

IWDFNamedPropertyStore, WDF_PROPERTY_STORE_DISPOSITION, WDF_PROPERTY_STORE_RETRIEVE_FLAGS


IWDFDevice::SetPnpState

The SetPnpState method turns on or off (or sets to the default state) the specified Plug and Play (PnP) property of a device.

void
  SetPnpState(
    IN WDF_PNP_STATE  State,
    IN WDF_TRI_STATE  Value
    );

Parameters

State
A WDF_PNP_STATE-typed value that identifies the PnP property to set.
Value
A WDF_TRI_STATE-typed value that identifies how to set the PnP property that State specifies. The following table shows the possible values for Value.
Value | Meaning
WdfUseDefault (0) | Set the PnP property to the default state.
WdfFalse (1) | Turn off the PnP property.
WdfTrue (2) | Turn on the PnP property.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example shows how to indicate that a device failed as the result of a request.

VOID
CUmdfHidDevice::OnCompletion(
    __in IWDFIoRequest* WdfRequest,
    __in IWDFIoTarget* /* WdfTarget */,
    __in IWDFRequestCompletionParams* WdfCompletionParams,
    __in PVOID /* Context */
    )
{
    ULONG_PTR bytesRead;

    if (!SUCCEEDED(WdfCompletionParams->GetCompletionStatus()))
    {
        m_WdfDevice->SetPnpState(WdfPnpStateFailed, WdfTrue);
        m_WdfDevice->CommitPnpState();
        return;
    }

    // Lock the device to prevent files from closing.
    m_WdfDevice->AcquireLock();

    // Retrieve the number of bytes that were read.
    bytesRead = WdfCompletionParams->GetInformation();

    // Process the reports.
    ProcessInputReports((PBYTE) m_ReadMemory->GetDataBuffer(NULL), bytesRead);

    m_WdfDevice->ReleaseLock();

    // Release the request.
    m_InterruptReadRequest = NULL;
    WdfRequest->DeleteWdfObject();

    // Send a new request.
    SendInterruptPipeRead();
}

See Also

IWDFDevice::GetPnpState, WDF_PNP_STATE


IWDFDeviceInitialize

The IWDFDeviceInitialize interface is a helper interface that the framework supplies as an input parameter to the driver's IDriverEntry::OnDeviceAdd method. The driver calls the methods of this interface to set the properties for a new device object and passes this interface as an input to the IWDFDriver::CreateDevice method to create the new device object.

In addition to the methods that IWDFDeviceInitialize inherits from the IUnknown interface, IWDFDeviceInitialize supports the following methods:

IWDFDeviceInitialize::AutoForwardCreateCleanupClose

IWDFDeviceInitialize::GetPnpCapability

IWDFDeviceInitialize::RetrieveDeviceInstanceId

IWDFDeviceInitialize::RetrieveDevicePropertyStore

IWDFDeviceInitialize::SetFilter

IWDFDeviceInitialize::SetLockingConstraint

IWDFDeviceInitialize::SetPnpCapability

IWDFDeviceInitialize::SetPowerPolicyOwnership


IWDFDeviceInitialize::AutoForwardCreateCleanupClose

The AutoForwardCreateCleanupClose method controls when create, cleanup, and close requests are forwarded to the next lower driver in the device stack.

void
  AutoForwardCreateCleanupClose(
    IN WDF_TRI_STATE  State
    );

Parameters

State
A WDF_TRI_STATE-typed value that identifies the state of automatic forwarding. The following table shows the possible values.
Value | Meaning
WdfUseDefault (0) | The framework uses the default forwarding scheme. For more information, see the following Comments section.
WdfFalse (1) | The framework does not forward create, cleanup, and close requests to the next lower driver.
WdfTrue (2) | The framework synchronously forwards create, cleanup, and close requests to the next lower driver.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

If the UMDF driver passes WdfUseDefault for the State parameter in a call to AutoForwardCreateCleanupClose, the framework uses a default forwarding scheme for create, cleanup, and close requests that depends on whether the driver is a filter or function driver:

  • If the driver is a filter driver, the default forwarding scheme is to synchronously forward requests to the next lower driver.
  • If the driver is a function driver, the default forwarding scheme is not to forward requests to the next lower driver.

If the framework is set up for forwarding, it forwards cleanup and close notifications regardless of whether the driver supports the IFileCallbackCleanup::OnCleanupFile and IFileCallbackClose::OnCloseFile interface methods. However, the framework automatically forwards create requests only if the driver does not support the IQueueCallbackCreate::OnCreateFile method. If the driver supports IQueueCallbackCreate::OnCreateFile, the framework forwards create requests only if the driver explicitly set up forwarding (WdfTrue) to the next lower driver.

Example

To be supplied.

See Also

IFileCallbackCleanup::OnCleanupFile, IFileCallbackClose::OnCloseFile, IQueueCallbackCreate::OnCreateFile


IWDFDeviceInitialize::GetPnpCapability

The GetPnpCapability method determines the state of the specified Plug and Play (PnP) capability.

WDF_TRI_STATE
  GetPnpCapability(
    IN WDF_PNP_CAPABILITY  Capability
    );

Parameters

Capability
A WDF_PNP_CAPABILITY-typed value that identifies the PnP capability to retrieve status about.

Return Value

GetPnpCapability returns one of the following WDF_TRI_STATE-typed values that identifies the state of the PnP capability that is specified in the Capability parameter:

Value | Meaning
WdfUseDefault (0) | The capability is set to the default state.
WdfFalse (1) | The capability is not set.
WdfTrue (2) | The capability is set.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDeviceInitialize::SetPnpCapability, WDF_PNP_CAPABILITY


IWDFDeviceInitialize::RetrieveDeviceInstanceId

The RetrieveDeviceInstanceId method retrieves the identifier of an instance of a device.

HRESULT
  RetrieveDeviceInstanceId(
    OUT PWSTR  Buffer,
    IN/OUT DWORD*  pdwSizeInChars
    );

Parameters

Buffer
A pointer to a buffer that receives a NULL-terminated string that represents the identifier of an instance of a device if the supplied buffer is non-NULL and RetrieveDeviceInstanceId is successful.
pdwSizeInChars
A pointer to a variable that receives the number of characters, including the NULL character, in the string that Buffer points to.

If Buffer is NULL, the value that the driver supplies is zero. The framework then returns the size, in characters, that is required for the identifier string.

If Buffer is non-NULL, the framework returns the size, in characters, of the identifier string.

Return Value

RetrieveDeviceInstanceId returns S_OK for the following scenarios:

  • The buffer that the Buffer parameter pointed to was non-NULL and large enough to hold the identifier string, including the NULL character, and the framework successfully copied the string into the supplied buffer and set the variable that was pointed to by the pdwSizeInChars parameter to the number of characters in the string.
  • The buffer at Buffer was NULL, the driver preset the variable at pdwSizeInChars to 0, and the framework set the variable at pdwSizeInChars to the number of characters that are required for the string.

RetrieveDeviceInstanceId returns HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) to indicate that the supplied buffer is non-NULL and does not contain enough space to hold the identifier string. The framework sets the variable at pdwSizeInChars to the number of characters that are required for the string.

RetrieveDeviceInstanceId might also return other HRESULT values.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFDeviceInitialize::RetrieveDevicePropertyStore

The RetrieveDevicePropertyStore method retrieves a device property store that clients can read and write device properties through.

HRESULT
  RetrieveDevicePropertyStore(
    IN PCWSTR  pcwszServiceName,
    IN WDF_PROPERTY_STORE_RETRIEVE_FLAGS  Flags,
    OUT IWDFNamedPropertyStore**  ppPropStore,
    OUT WDF_PROPERTY_STORE_DISPOSITION*  pDisposition
    );

Parameters

pcwszServiceName
A pointer to a NULL-terminated string that represents the name of the device property store.
Flags
A WDF_PROPERTY_STORE_RETRIEVE_FLAGS-typed value that identifies how to retrieve the device property store.
ppPropStore
A pointer to a buffer that receives a pointer to the IWDFNamedPropertyStore interface that is used to retrieve device properties.
pDisposition
A pointer to a variable that receives a WDF_PROPERTY_STORE_DISPOSITION-typed value that identifies whether the framework created the device property store or the device property store already existed.

Return Value

RetrieveDevicePropertyStore returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The caller should call the Release method of the IWDFNamedPropertyStore interface after finishing with the property store.

Example

To be supplied.

See Also

IWDFNamedPropertyStore, WDF_PROPERTY_STORE_DISPOSITION, WDF_PROPERTY_STORE_RETRIEVE_FLAGS


IWDFDeviceInitialize::SetFilter

The SetFilter method sets the property that enables a device as a filter device.

void
  SetFilter(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A filter driver calls SetFilter to mark itself as a filter.

Example

For a code example of how to use the SetFilter method, see IWDFDriver::CreateDevice.

See Also

IWDFDriver::CreateDevice


IWDFDeviceInitialize::SetLockingConstraint

The SetLockingConstraint method sets the synchronization (or locking) model for callback functions into the driver.

void
  SetLockingConstraint(
    IN WDF_CALLBACK_CONSTRAINT  LockType
    );

Parameters

LockType
One of the following WDF_CALLBACK_CONSTRAINT-typed values that identifies the locking model.
Value | Meaning
None (0) No callback functions into the driver are synchronized.

The driver must handle all synchronization.
WdfDeviceLevel (1) All callback functions into the driver that are associated with the device are synchronized, including all callback functions that are associated with I/O queues.

Only one event handler that is associated with the device can run at any given time.
WdfLevelReserved (2) | Reserved.

Note that the preceding locking models apply only for I/O (that is, open, read, write, and device I/O control) operations and not for Plug and Play (PnP) and power management notifications.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The default value of the LockType parameter is WdfDeviceLevel, which is currently the only supported value.

Example

For a code example of how to use the SetLockingConstraint method, see IWDFDriver::CreateDevice.

See Also

IWDFDriver::CreateDevice


IWDFDeviceInitialize::SetPnpCapability

The SetPnpCapability method sets the specified Plug and Play (PnP) capability of a device to the specified state.

void
  SetPnpCapability(
    IN WDF_PNP_CAPABILITY  Capability,
    IN WDF_TRI_STATE  Value
    );

Parameters

Capability
A WDF_PNP_CAPABILITY-typed value that identifies the PnP capability to set.
Value
A WDF_TRI_STATE-typed value that identifies how to set the PnP capability that is specified in Capability. The following table shows the possible values.
Value | Meaning
WdfUseDefault (0) | Set the capability to the default state.
WdfFalse (1) | Do not set the capability.
WdfTrue (2) | Set the capability.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDeviceInitialize::GetPnpCapability, WDF_PNP_CAPABILITY


IWDFDeviceInitialize::SetPowerPolicyOwnership

The SetPowerPolicyOwnership method sets the ownership of the power policy to a driver or removes ownership from the driver.

void
  SetPowerPolicyOwnership(
    IN BOOL  fTrue
    );

Parameters

fTrue
A BOOL value that specifies whether to set power-policy ownership to the driver or remove ownership from the driver. TRUE indicates to set power-policy ownership to the driver; FALSE indicates to remove ownership from the driver.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A filter driver passes FALSE to SetPowerPolicyOwnership so that it is not the power policy owner.

Example

For a code example of how to use the SetPowerPolicyOwnership method, see IWDFDriver::CreateDevice.

See Also

IWDFDriver::CreateDevice


IWDFDriver

The IWDFDriver interface exposes the framework driver object that represents the driver image that is loaded in the host process.

In addition to the methods that IWDFDriver inherits from the IWDFObject interface, IWDFDriver supports the following methods:

IWDFDriver::CreateDevice

IWDFDriver::CreatePreallocatedWdfMemoryObject

IWDFDriver::CreateWdfMemory

IWDFDriver::CreateWdfObject

IWDFDriver::IsVersionAvailable

IWDFDriver::RetrieveVersionString


IWDFDriver::CreateDevice

The CreateDevice method configures and creates a new framework device object.

HRESULT
  CreateDevice(
    IN IWDFDeviceInitialize*  pDeviceInit,
    IN IUnknown*  pCallbackInterface,
    OUT IWDFDevice**  ppDevice
    );

Parameters

pDeviceInit
A pointer to the IWDFDeviceInitialize interface that represents the configuration properties for the new device to create.
pCallbackInterface
A pointer to the IUnknown interface that the framework uses to determine the event callback functions that the driver subscribes to on the newly created device object. These are the functions that the framework calls when the relevant events occur.
ppDevice
A pointer to a buffer that receives a pointer to the IWDFDevice interface for the new device object.

Return Value

CreateDevice returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The IUnknown interface that the driver supplies for the pCallbackInterface parameter can support several callback functions. The framework calls the QueryInterface method on the supplied IUnknown multiple times to retrieve the interface methods that the driver supports. When the device changes state, the framework calls the method that is related to the change (such as the IPnpCallback::OnD0Entry method) to notify the driver.

If the call to CreateDevice is successful, the driver must eventually call the IWDFDevice::Release method. Note that the framework has its own reference count on the object.

Example

The following code example shows an implementation of the OnDeviceAdd method of the IDriverEntry interface. The framework calls OnDeviceAdd when a device is added to a computer.

HRESULT
CDriver::OnDeviceAdd(
    IWDFDriver* pDriver,
    IWDFDeviceInitialize* pDeviceInit
    )
{
    IUnknown   *pDeviceCallback = NULL;
    IWDFDevice *pIWDFDevice     = NULL;
    IUnknown   *pIUnkQueue      = NULL;

    //
    // Create the device callback object.
    //
    HRESULT hr = CDevice::CreateInstance(&pDeviceCallback);

    //
    // Set device properties
    //
    if (S_OK == hr) {
        pDeviceInit->SetLockingConstraint(WdfDeviceLevel);
        // For a filter driver, call the following:
        // pDeviceInit->SetFilter();
        // pDeviceInit->SetPowerPolicyOwnership(FALSE);
    }

    //
    // Request that the framework create a device object.
    // The device callback object is passed to inform the
    // framework about the PnP callback functions the driver supports.
    //
    if (S_OK == hr) {
        hr = pDriver->CreateDevice(pDeviceInit,
                                   pDeviceCallback,
                                   &pIWDFDevice);
    }

    //
    // Create the queue callback object.
    //

    if (S_OK == hr) {
        hr = CQueue::CreateInstance(&pIUnkQueue);
    }

    //
    // Configure the default queue.
    // The queue callback object is passed to inform the
    // framework about the queue callback functions the driver supports.
    //
    if (S_OK == hr) {
        IWDFIoQueue * pDefaultQueue = NULL;
        hr = pIWDFDevice->CreateIoQueue(
                       pIUnkQueue,
                       TRUE,                  // bDefaultQueue
                       WdfIoQueueDispatchParallel,
                       TRUE,                  // bPowerManaged
                       FALSE, //bAllowZeroLengthRequests
                          &pDefaultQueue);
        SAFE_RELEASE(pDefaultQueue);
    }

    SAFE_RELEASE(pDeviceCallback);
    SAFE_RELEASE(pIWDFDevice);
    SAFE_RELEASE(pIUnkQueue);

    return hr;
}

See Also

IDriverEntry::OnDeviceAdd, IPnpCallback::OnD0Entry, IWDFDevice, IWDFDeviceInitialize


IWDFDriver::CreatePreallocatedWdfMemory

The CreatePreallocatedWdfMemory method creates a framework memory object for the specified buffer.

HRESULT
  CreatePreallocatedWdfMemory(
    IN BYTE*  pBuff,
    IN SIZE_T  BufferSize,
    IN IUnknown*  pCallbackInterface,
    IN IWDFObject*  pParentObject,
    OUT IWDFMemory**  ppWdfMemory
    );

Parameters

pBuff
A pointer to a driver-supplied data buffer for the memory object.
BufferSize
The size, in bytes, of data that pBuff points to.
pCallbackInterface
A pointer to the IUnknown interface that the framework uses to determine the event callback functions that the driver subscribes to on the newly created memory object. These are the functions that the framework calls when the relevant events occur. This interface is typically used for object cleanup and disposal.
pParentObject
A pointer to the IWDFObject interface for the parent object of the created memory object. If NULL, the driver object becomes the default parent.
ppWdfMemory
A pointer to a buffer that receives a pointer to the IWDFMemory interface for the newly created WDF memory object.

Return Value

CreatePreallocatedWdfMemory returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The CreatePreallocatedWdfMemory method creates a framework memory object for a buffer that the driver previously allocated or obtained.

A UMDF driver can call CreatePreallocatedWdfMemory if it must create a memory object that represents a pre-existing memory buffer. For example, the driver might receive a driver-defined structure within a buffer for an I/O request that contains an internal I/O control code. The driver can call CreatePreallocatedWdfMemory to create a memory object so that the driver can pass the structure to an I/O target.

After a UMDF driver calls CreatePreallocatedWdfMemory, the driver can call IWDFMemory::SetBuffer to assign a different buffer to the memory object that CreatePreallocatedWdfMemory created.

When the framework memory object that CreatePreallocatedWdfMemory created is deleted, the framework does not deallocate the pre-existing buffer. Likewise, a call to IWDFMemory::SetBuffer does not deallocate the previously assigned buffer.

Example

The following code example shows how to create a memory object for a buffer.

    //
    // Allocate a request.
    hr = wdfDevice->CreateRequest(NULL, NULL, &request);

    // Allocate a buffer and wrap it in a memory object.
    // Make the memory object a child of the request.
    // When the request object is deleted, the memory object
    // is also deleted.

    if (SUCCEEDED(hr))
    {
        buffer = new BYTE[m_HidDescriptor->wReportLength];

        if (buffer == NULL)
        {
            hr = E_OUTOFMEMORY;
        }
    }

    if (SUCCEEDED(hr))
    {
        CComPtr<IWDFDriver> driver;
        wdfDevice->GetDriver(&driver);

        hr = driver->CreatePreallocatedWdfMemory(
                        buffer,
                        m_HidDescriptor->wReportLength,
                        NULL,
                        request,
                        &memory
                        );
    }

See Also

IWDFMemory, IWDFMemory::SetBuffer, IWDFObject


IWDFDriver::CreateWdfMemory

The CreateWdfMemory method creates a framework memory object and allocates, for the memory object, a data buffer of the specified size.

HRESULT
  CreateWdfMemory(
    IN SIZE_T  BufferSize,
    IN IUnknown*  pCallbackInterface,
    IN IWDFObject*  pParentObject,
    OUT IWDFMemory**  ppWdfMemory
    );

Parameters

BufferSize
The size, in bytes, of data for the newly created WDF memory object's data buffer.
pCallbackInterface
A pointer to the IUnknown interface that the framework uses to determine the event callback functions that the driver subscribes to on the newly created memory object. These are the functions that the framework calls when the relevant events occur. This interface is typically used for object cleanup and disposal.
pParentObject
A pointer to the IWDFObject interface for the parent object of the created memory object. If NULL, the driver object becomes the default parent.
ppWdfMemory
A pointer to a buffer that receives a pointer to the IWDFMemory interface for the newly created WDF memory object.

Return Value

CreateWdfMemory returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The CreateWdfMemory method allocates a buffer of the size that the BufferSize parameter specifies, and creates a framework memory object that represents the buffer.

If NULL is specified in the pParentObject parameter, the driver object becomes the default parent object for the newly created memory object. If a UMDF driver creates a memory object that the driver uses with a specific device object, request object, or other framework object, the driver should set the memory object's parent object appropriately. When the parent object is deleted, the memory object and its buffer are deleted.

A UMDF driver can also delete a memory object and its buffer by calling IWDFObject::DeleteWdfObject.

Example

The following code example shows how to create a memory object that can hold information that is read from a USB endpoint.

HRESULT
CUmdfHidDevice::PrepareReader(
    VOID
    )
{
    CComPtr<IWDFDevice> wdfDevice;
    CComPtr<IWDFDriver> wdfDriver;
    CComPtr<IWDFIoRequest> wdfRequest;

    HRESULT hr;

    GetWdfDevice(&wdfDevice);
    wdfDevice->GetDriver(&wdfDriver);

    // Open the interrupt pipe.
    hr = m_HidInterface->RetrieveUsbPipeObject(
                         USB_HID_INTERRUPT_PIPE_INDEX,
                         &m_InterruptPipe
                         );

    // Allocate a memory object to hold information that
    // is read from the interrupt pipe.
    // This memory object will be reused.
    if (SUCCEEDED(hr))
    {
        hr = wdfDriver->CreateWdfMemory(m_ReadBufferSize,
                           NULL,
                           wdfDevice,
                           &m_ReadMemory);
    }

    return hr;
}

See Also

IWDFMemory, IWDFObject, IWDFObject::DeleteWdfObject


IWDFDriver::CreateWdfObject

The CreateWdfObject method creates a custom (or user) WDF object from a parent WDF object.

HRESULT
  CreateWdfObject(
    IN IUnknown*  pCallbackInterface,
    IN IWDFObject*  pParentObject,
    OUT IWDFObject**  ppWdfObject
    );

Parameters

pCallbackInterface
A pointer to the IUnknown interface that the framework uses to determine the event callback functions that the driver subscribes to on the newly created custom object. These are the functions that the framework calls when the relevant events occur.
pParentObject
A pointer to the IWDFObject interface for the parent WDF object. If NULL, the driver object becomes the default parent.
ppWdfObject
A pointer to a buffer that receives a pointer to the IWDFObject interface for the newly created WDF object.

Return Value

CreateWdfObject returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A driver can associate a number of its interfaces with the IUnknown interface that it supplies. The framework calls the QueryInterface method on the supplied IUnknown multiple times to retrieve the interfaces that the driver supports. For example, the framework can call the QueryInterface method on the supplied IUnknown to retrieve the IObjectCleanup interface. When events that are related to the methods of the supported interfaces occur, the framework calls the methods to notify the driver about the events.

The driver can call CreateWdfObject to create a general framework base object for its own use. The driver can associate context memory, assign a parent object, and register an IObjectCleanup interface. The framework subsequently calls the IObjectCleanup::OnCleanup method to clean up the child object.

If no parent object is specified at the pParentObject parameter, the driver becomes the default parent. Therefore, when the driver object is deleted, the framework cleans up the child object.

If a parent object is assigned, the child object is deleted when the parent object is deleted. In other words, the lifetime of a child object is scoped within that of the parent.

If the driver must clean up the child object before the parent object is deleted, the driver can call the IWDFObject::DeleteWdfObject method.

Example

To be supplied.

See Also

IObjectCleanup, IObjectCleanup::OnCleanup, IWDFObject, IWDFObject::DeleteWdfObject


IWDFDriver::IsVersionAvailable

The IsVersionAvailable method determines whether the specified version of the framework is available.

BOOL
  IsVersionAvailable(
    IN UMDF_VERSION_DATA*  pMinimumVersion
    );

Parameters

pMinimumVersion
A pointer to a UMDF_VERSION_DATA structure that describes the minimum version of the framework that the driver supports.

Return Value

IsVersionAvailable returns a BOOL value that indicates whether the given version of the framework is available. TRUE indicates the version of the framework is available. FALSE indicates the version of the framework is not available.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

UMDF_VERSION_DATA


IWDFDriver::RetrieveVersionString

The RetrieveVersionString method retrieves the version of the framework.

HRESULT
  RetrieveVersionString(
    OUT PWSTR  pVersion,
    IN/OUT DWORD*  pdwVersionLength
    );

Parameters

pVersion
A pointer to a buffer that receives a NULL-terminated string that represents the version of the framework if the supplied buffer is non-NULL and RetrieveVersionString is successful.
pdwVersionLength
A pointer to a variable that receives the size, in characters, of the version string that pVersion points to. On input, this variable contains the size, in bytes, of the buffer at pVersion.

If the buffer at pVersion is NULL, the value that the driver supplies is zero. The framework then returns the size, in characters, that is required for the version string.

If the buffer at pVersion is non-NULL, the framework returns the size, in characters, of the version string.

Return Value

RetrieveVersionString returns S_OK for the following scenarios:

  • The buffer that the pVersion parameter points to was non-NULL and large enough to hold the version string, including the NULL character. In addition, the framework successfully copied the string into the supplied buffer and set the variable that is pointed to by the pdwVersionLength parameter to the number of characters in the string.
  • The buffer at pVersion was NULL, the driver preset the variable at pdwVersionLength to 0, and the framework set the variable at pdwVersionLength to the number of characters that are required for the string.

RetrieveVersionString returns HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) to indicate that the supplied buffer is non-NULL and did not contain enough space to hold the version. The framework sets the variable at pdwVersionLength to the number of characters that are required for the string.

RetrieveVersionString might also return other HRESULT values.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFDriverCreatedFile

The IWDFDriverCreatedFile interface exposes a framework file object for the driver to use.

In addition to the methods that IWDFDriverCreatedFile inherits from the IWDFFile interface, IWDFDriverCreatedFile supports the following method:

IWDFDriverCreatedFile::Close


IWDFDriverCreatedFile::Close

The Close method closes an instance of a file object that was created by calling the IWDFDevice::CreateWdfFile method.

void
  Close(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFDevice::CreateWdfFile


IWDFFile

The IWDFFile interface exposes the file object that represents the HANDLE that is returned by the Microsoft Win32 CreateFile function. All further operations on this handle, such as calls to the Win32 ReadFile function and the DeviceIoControl function, are sent to this file object.

In addition to the methods that IWDFFile inherits from the IWDFObject interface, IWDFFile supports the following methods:

IWDFFile::GetDevice

IWDFFile::RetrieveFileName


IWDFFile::GetDevice

The GetDevice method returns the interface to the device object that a file object is associated with.

void
  GetDevice(
    OUT IWDFDevice**  ppWdfDevice
    );

Parameters

ppWdfDevice
A pointer to a variable that receives a pointer to the IWDFDevice interface for the device object that is associated with the file object.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example shows how to get the device object that a file object is associated with.

    CComPtr<IWDFDevice> wdfDevice;

    WdfFile->GetDevice(&wdfDevice);

See Also

IWDFDevice


IWDFFile::RetrieveFileName

The RetrieveFileName method retrieves the full name of the file that is associated with the underlying kernel-mode device.

HRESULT
  RetrieveFileName(
    OUT PWSTR  pFileName,
    IN/OUT DWORD*  pdwFileNameLengthInChars
    );

Parameters

pFileName
A pointer to a buffer that receives a NULL-terminated string that represents the full name of the file that is associated with the underlying kernel-mode device if the supplied buffer is non-NULL and RetrieveFileName is successful.
pdwFileNameLengthInChars
A pointer to a variable that receives the size, in characters, of the full file name that pFileName points to. On input, this variable contains the size, in bytes, of the buffer at pFileName.

If the buffer at pFileName is NULL, the value that the driver supplies is zero. The framework then returns the size, in characters, that is required for the file name string.

If the buffer at pFileName is non-NULL, the framework returns the size, in characters, of the file name string.

Return Value

RetrieveFileName returns S_OK for the following scenarios:

  • The buffer that the pFileName parameter points to was non-NULL and large enough to hold the name string, including the NULL character, and the framework successfully copied the string into the supplied buffer and set the variable that is pointed to by the pdwFileNameLengthInChars parameter to the number of characters in the string.
  • The buffer at pFileName was NULL, the driver preset the variable at pdwFileNameLengthInChars to 0, and the framework set the variable at pdwFileNameLengthInChars to the number of characters that are required for the string.

RetrieveFileName returns HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) to indicate that the supplied buffer is non-NULL and did not contain enough space to hold the file name. The framework sets the variable at pdwFileNameLengthInChars to the number of characters that are required for the string.

RetrieveFileName might also return other HRESULT values.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example shows how to retrieve the name of a file.

    ULONG fileNameCch = 0;
    PWSTR fileName = NULL;
    ULONG index;

    CComObject<CUmdfHidFile> *file = NULL;

    HRESULT hr;

    // Get the length of the file name to allocate a buffer.
    hr = WdfFile->RetrieveFileName(NULL, &fileNameCch);
    //
    // Allocate the buffer.
    //
    if (SUCCEEDED(hr))
    {
        fileName = new WCHAR[fileNameCch];

        if (fileName != NULL)
        {
            hr = E_OUTOFMEMORY;
        }
    }
    //
    // Get the file name.
    //
    if (SUCCEEDED(hr))
    {
        hr = WdfFile->RetrieveFileName(fileName, &fileNameCch);
    }


IWDFFileHandleTargetFactory

The IWDFFileHandleTargetFactory interface is a factory interface that is used to create a file-handle-based target device object.

In addition to the methods that IWDFFileHandleTargetFactory inherits from the IUnknown interface, IWDFFileHandleTargetFactory supports the following method:

IWDFFileHandleTargetFactory::CreateFileHandleTarget


IWDFFileHandleTargetFactory::CreateFileHandleTarget

The CreateFileHandleTarget method creates a file-handle-based device object that is also an I/O target.

HRESULT
  CreateFileHandleTarget(
    IN HANDLE  hTarget,
    OUT IWDFIoTarget**  ppTarget
    );

Parameters

hTarget
A handle to the target device.
ppTarget
A pointer to a buffer that receives a pointer to the IWDFIoTarget interface for the target device object.

Return Value

CreateFileHandleTarget returns one of the following values:

S_OK
CreateFileHandleTarget successfully created a file-handle-based device object that is also an I/O target.
E_OUTOFMEMORY
CreateFileHandleTarget encountered an allocation failure.

CreateFileHandleTarget might also return other HRESULT values that are defined in Winerror.h.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

A UMDF driver should release the IWDFIoTarget interface pointer that the CreateFileHandleTarget method returns in the ppTarget parameter when the driver is done with the interface.

To use the newly created file-handle-based I/O target object in a device stack, the INF file that installs the UMDF driver must contain the UmdfDispatcher directive and set UmdfDispatcher to FileHandle (UmdfDispatcher=FileHandle) in the DDInstall.WDF section. UmdfDispatcher is required to inform the UMDF platform that it can allow access to the file-handle-based I/O target. For more information about UmdfDispatcher, see Specifying WDF Directives.

Example

The following code example shows how to create a device object that is based on a file handle.

    HRESULT hr = S_OK;
    IWDFFileHandleTargetFactory * pFileHandleTargetFactory = NULL;

    // Open the device and get the handle.

    m_WriteHandle = CreateNamedPipe(NP_NAME,
              PIPE_ACCESS_DUPLEX|FILE_FLAG_OVERLAPPED,
     PIPE_TYPE_MESSAGE|PIPE_READMODE_MESSAGE|PIPE_WAIT,
                                    2,
                                    MAX_TRANSFER_SIZE,
                                    MAX_TRANSFER_SIZE,
                                    1000,
                                    NULL);

    if (m_WriteHandle == INVALID_HANDLE_VALUE) {
        DWORD err = GetLastError();

        TraceEvents(TRACE_LEVEL_ERROR,
                    TEST_TRACE_DEVICE,
                    "%!FUNC! Cannot open write side of named pipe %!winerr!",
                    err
                    );

        hr = HRESULT_FROM_WIN32(err);
    }

    if (SUCCEEDED(hr)) {
        hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&pFileHandleTargetFactory));

        if (FAILED(hr)){
            TraceEvents(TRACE_LEVEL_ERROR,
                        TEST_TRACE_DEVICE,
                        L"ERROR: Unable to obtain target factory for creating FileHandle based I/O target %!hresult!",
                        hr
                        );
        }
    }

    if (SUCCEEDED(hr)) {
        hr = pFileHandleTargetFactory->CreateFileHandleTarget(m_WriteHandle, &m_WriteTarget);
    }

See Also

IWDFIoTarget


IWDFIoQueue

The IWDFIoQueue interface exposes an I/O queue object.

In addition to the methods that IWDFIoQueue inherits from the IWDFObject interface, IWDFIoQueue supports the following methods:

IWDFIoQueue::ConfigureRequestDispatching

IWDFIoQueue::Drain

IWDFIoQueue::DrainSynchronously

IWDFIoQueue::GetDevice

IWDFIoQueue::GetState

IWDFIoQueue::Purge

IWDFIoQueue::PurgeSynchronously

IWDFIoQueue::RetrieveNextRequest

IWDFIoQueue::RetrieveNextRequestByFileObject

IWDFIoQueue::Start

IWDFIoQueue::Stop

IWDFIoQueue::StopSynchronously


IWDFIoQueue::ConfigureRequestDispatching

The ConfigureRequestDispatching method configures the queuing of I/O requests of the given type.

HRESULT
  ConfigureRequestDispatching(
    IN WDF_REQUEST_TYPE  RequestType,
    IN BOOL  Forward
    );

Parameters

RequestType
A WDF_REQUEST_TYPE-typed value that identifies the request type to be queued. The only valid values are WdfRequestCreate, WdfRequestRead, WdfRequestWrite, and WdfRequestDeviceIoControl.
Forward
A BOOL value that specifies whether requests of the specified type are queued. TRUE indicates to enable queuing requests; FALSE indicates to disable queuing requests.

Return Value

ConfigureRequestDispatching returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The driver can call the ConfigureRequestDispatching method multiple times to configure how each request type is dispatched to the I/O queue.

Example

The following code example shows how to configure forwarding for IOCTL requests.

    //
    // Configure forwarding for IOCTL requests
    //
    HRESULT hr = m_FxQueue->ConfigureRequestDispatching(
                           WdfRequestDeviceIoControl,
                           true
                           );

See Also

WDF_REQUEST_TYPE


IWDFIoQueue::Drain

The Drain method directs the queue to reject new incoming I/O requests and allow already-queued requests to be delivered to the driver for processing.

void
  Drain(
    IN IQueueCallbackStateChange*  pDrainComplete
    );

Parameters

pDrainComplete
A pointer to the IQueueCallbackStateChange interface whose method the framework calls to deliver queue state to the driver. The framework calls the method after all requests are completed or canceled and the queue is empty.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A driver should ensure that only one of the following methods is in progress at any given time:

  • IWDFIoQueue::Stop
  • IWDFIoQueue::Drain
  • IWDFIoQueue::Purge

For example, if the driver previously called Drain, it should wait for notification from the method of the interface that the pDrainComplete parameter points to before the driver calls either Stop or Purge. Violating this rule results in termination of the host process.

Example

To be supplied.

See Also

IQueueCallbackStateChange, IWDFIoQueue::Purge, IWDFIoQueue::Stop


IWDFIoQueue::DrainSynchronously

The DrainSynchronously method directs the queue to reject new incoming I/O requests and allows already-queued requests to be delivered to the driver for processing. This method returns after all requests are completed or canceled.

void
  DrainSynchronously(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The DrainSynchronously method is a synchronous version of the IWDFIoQueue::Drain method. That is, DrainSynchronously does not return to the driver until the queue is drained.

Example

To be supplied.

See Also

IWDFIoQueue::Drain


IWDFIoQueue::GetDevice

The GetDevice method retrieves the interface to the device that owns the I/O queue.

void
  GetDevice(
    OUT IWDFDevice**  ppWdfDevice
    );

Parameters

ppWdfDevice
A pointer to a variable that receives a pointer to the IWDFDevice interface for the device object, if the call succeeds; otherwise, this parameter is NULL.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example shows how to retrieve the device interface that owns an I/O queue.

    CDevice                 *pMyDevice;
    IWDFDevice              *pDevice;
    HANDLE                  writeHandle;

    //
    // Retrieve the queue's parent device object
    //
    pWdfQueue->GetDevice(&pDevice);
    //
    // Use the device object to retrieve assigned context.
    // In this case, context is the device callback object.
    //
    pDevice->RetrieveContext((VOID **)&pMyDevice);
    pDevice->Release();
    //
    // Retrieve the device callback object's write handle.
    //
    writeHandle = pMyDevice->GetWriteHandle();

See Also

IWDFDevice


IWDFIoQueue::GetState

The GetState method retrieves the state of an I/O queue.

WDF_IO_QUEUE_STATE
  GetState(
    OUT ULONG*  pulNumOfRequestsInQueue,
    OUT ULONG*  pulNumOfRequestsInDriver
    );

Parameters

pulNumOfRequestsInQueue
A pointer to a variable that receives the number of I/O requests that are currently in the I/O queue (that is, that have not been delivered to the driver).
pulNumOfRequestsInDriver
A pointer to a variable that receives the number of I/O requests that the driver accepted from the I/O queue but that the driver has not completed, canceled, or forwarded to another I/O queue.

Return Value

GetState returns a bitwise OR of WDF_IO_QUEUE_STATE-typed values that provides the state of the queue.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The total number of requests that are associated with the I/O queue is the sum of the values that the pulNumOfRequestsInQueue and pulNumOfRequestsInDriver parameters point to.

Example

To be supplied.

See Also

WDF_IO_QUEUE_STATE


IWDFIoQueue::Purge

The Purge method directs the framework to reject new incoming I/O requests and to cancel all outstanding requests.

void
  Purge(
    IN IQueueCallbackStateChange*  pPurgeComplete
    );

Parameters

pPurgeComplete
A pointer to the IQueueCallbackStateChange interface whose method the framework calls to deliver queue state to the driver. The framework calls the method after all requests are canceled.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The framework cancels unprocessed requests in the queue. For requests that are delivered to the driver and marked cancelable, the framework calls IRequestCallbackCancel::OnCancel.

The driver should ensure that only one of the following methods is in progress at any given time:

  • IWDFIoQueue::Stop
  • IWDFIoQueue::Drain
  • IWDFIoQueue::Purge

For example, if the driver previously called Purge, it should wait for notification from the method of the interface that the pPurgeComplete parameter points to before it calls either Stop or Drain. Violating this rule results in termination of the host process.

Example

The following code example shows how to stop requests to a queue.

VOID
CUmdfHidFile::OnCleanupFile(
    __in IWDFFile* /* WdfFile */
    )
/*++
    This method handles the cleanup operation for the file object.
Because the file is disabled, no new reports should be added to the ring buffer.
--*/
{
    this->Disable();

    //
    // Stop all current requests to read reports.
    //

    m_GetReportQueue->Purge(NULL);
}

See Also

IQueueCallbackStateChange, IRequestCallbackCancel::OnCancel, IWDFIoQueue::Drain, IWDFIoQueue::Stop


IWDFIoQueue::PurgeSynchronously

The PurgeSynchronously method directs the framework to reject new incoming I/O requests and to cancel all outstanding requests. The method returns after all outstanding requests are canceled.

void
  PurgeSynchronously(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The framework cancels unprocessed requests in the queue. For requests that are delivered to the driver and marked cancelable, the framework calls IRequestCallbackCancel::OnCancel.

The PurgeSynchronously method is a synchronous version of the IWDFIoQueue::Purge method. That is, PurgeSynchronously does not return to the driver until all outstanding requests are canceled.

Example

To be supplied.

See Also

IRequestCallbackCancel::OnCancel, IWDFIoQueue::Purge


IWDFIoQueue::RetrieveNextRequest

The RetrieveNextRequest method retrieves the next I/O request from an I/O queue.

HRESULT
  RetrieveNextRequest(
    OUT IWDFIoRequest**  ppRequest
    );

Parameters

ppRequest
A pointer to a buffer that receives a pointer to the IWDFIoRequest interface for the next request object, or receives NULL if the queue is empty or if the next request is not found.

Return Value

RetrieveNextRequest returns one of the following values:

S_OK
The next I/O request was successfully retrieved from the I/O queue.
STATUS_WDF_PAUSED
The queue is not dispatching requests. This situation occurs if the device undergoes a power state transition and all of the queues are stopped from dispatching requests or if the driver explicitly called IWDFIoQueue::Stop to stop dispatching requests.
HRESULT_FROM_NT(STATUS_NO_MORE_ENTRIES)
No requests were in the queue.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_STATE)
The call was made to retrieve the request from a parallel queue.

RetrieveNextRequest might also return other HRESULT values.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

If a driver configures an I/O queue for manual dispatching of I/O requests, the driver can call the RetrieveNextRequest method to obtain the next request from the queue. For more information about manually dispatching I/O requests, see Configuring Dispatch Mode for an I/O Queue.

Example

The following code example polls the queue for requests for as long as requests can be retrieved. The code first verifies if requests are associated with a specific file object.

VOID
CMyDevice::ServiceSwitchChangeQueue(
    __in SWITCH_STATE NewState,
    __in HRESULT CompletionStatus,
    __in_opt IWDFFile *SpecificFile
    )
{
    IWDFIoRequest *fxRequest;
    HRESULT enumHr = S_OK;
    do {
        HRESULT hr;
        //
        // Get the next request.
        //
        if (NULL != SpecificFile) {
            enumHr = m_SwitchChangeQueue->RetrieveNextRequestByFileObject(
                                        SpecificFile,
                                        &fxRequest
                                        );
        }
        else {
            enumHr = m_SwitchChangeQueue->RetrieveNextRequest(&fxRequest);
        }
        //
        // If a request was retrieved, complete it.
        //
        if (S_OK == enumHr) {
            if (S_OK == CompletionStatus) {
                IWDFMemory *fxMemory;
                //
                // Copy the result to the request buffer.
                //
                fxRequest->GetOutputMemory(&fxMemory);
                hr = fxMemory->CopyFromBuffer(0,
                                 &NewState,
                                 sizeof(SWITCH_STATE));
                fxMemory->Release();
            }
            else {
                hr = CompletionStatus;
            }
            //
            // Complete the request with the copy or
            // completion status.
            //
            if (S_OK == hr) {
                fxRequest->CompleteWithInformation(hr,
                                 sizeof(SWITCH_STATE));
            }
            else {
                fxRequest->Complete(hr);
            }
        }
    }
    while (S_OK == enumHr);
}

See Also

IWDFIoQueue::Stop, IWDFIoRequest


IWDFIoQueue::RetrieveNextRequestByFileObject

The RetrieveNextRequestByFileObject method retrieves from an I/O queue the next I/O request whose file object matches the specified file object.

HRESULT
  RetrieveNextRequestByFileObject(
    IN IWDFFile*  pFileObject,
    OUT IWDFIoRequest**  ppRequest
    );

Parameters

pFileObject
A pointer to the IWDFFile interface for the file object that is used to retrieve the next I/O request whose file object matches this supplied file object.
ppRequest
A pointer to a buffer that receives a pointer to the IWDFIoRequest interface for the next request object whose file object matches the supplied file object, or receives NULL if the queue is empty or if the next request is not found.

Return Value

RetrieveNextRequestByFileObject returns one of the following values:

S_OK
The next I/O request was successfully retrieved from the I/O queue.
STATUS_WDF_PAUSED
The queue is not dispatching requests. This situation occurs if the device undergoes a power state transition and all of the queues are stopped from dispatching requests or if the driver explicitly called IWDFIoQueue::Stop to stop dispatching requests.
HRESULT_FROM_NT(STATUS_NO_MORE_ENTRIES)
No requests were in the queue.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_STATE)
The call was made to retrieve the request from a parallel queue.

RetrieveNextRequestByFileObject might also return other HRESULT values.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

If a driver configures an I/O queue for manual dispatching of I/O requests, the driver can call the RetrieveNextRequestByFileObject method to obtain the next request whose file object matches the supplied file object from the queue. For more information about manually dispatching I/O requests, see Configuring Dispatch Mode for an I/O Queue.

If multiple I/O requests whose file objects match the file object that the pFileObject parameter points to exist in the I/O queue, the first I/O request is returned.

Example

For a code example of how to use the GetNextRequestByFileObject method, see IWDFIoQueue::RetrieveNextRequest.

See Also

IWDFFile, IWDFIoQueue::RetrieveNextRequest, IWDFIoQueue::Stop, IWDFIoRequest


IWDFIoQueue::Start

The Start method enables an I/O queue to start receiving new I/O requests and delivering them to a driver.

void
  Start(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFIoQueue::Stop

The Stop method prevents an I/O queue from delivering new I/O requests to a driver but still allows the I/O queue to accept requests from applications.

void
  Stop(
    IN IQueueCallbackStateChange*  pStopComplete
    );

Parameters

pStopComplete
A pointer to the IQueueCallbackStateChange interface whose method the framework calls after all outstanding I/O requests, if any, in the driver are completed.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A call to Stop is asynchronous and immediately returns to the driver. The driver is notified through the method of the supplied IQueueCallbackStateChange interface after all outstanding requests in the driver complete.

The driver should ensure that only one of the following methods is in progress at any given time:

  • IWDFIoQueue::Stop
  • IWDFIoQueue::Drain
  • IWDFIoQueue::Purge

For example, if the driver previously called Stop, it should wait for notification from the method of the interface that the pStopComplete parameter points to before the driver calls either Drain or Purge. Violating this rule results in termination of the host process.

Example

To be supplied.

See Also

IQueueCallbackStateChange, IWDFIoQueue::Drain, IWDFIoQueue::Purge


IWDFIoQueue::StopSynchronously

The StopSynchronously method prevents an I/O queue from delivering new I/O requests to a driver but still allows the I/O queue to accept requests from applications.

void
  StopSynchronously(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The StopSynchronously method is the synchronous version of the IWDFIoQueue::Stop method. That is, StopSynchronously does not return to the driver until the queue stops.

Example

To be supplied.

See Also

IWDFIoQueue::Stop


IWDFIoRequest

The IWDFIoRequest interface exposes an I/O request object.

In addition to the methods that IWDFIoRequest inherits from the IWDFObject interface, IWDFIoRequest supports the following methods:

IWDFIoRequest::CancelSentRequest

IWDFIoRequest::Complete

IWDFIoRequest::CompleteWithInformation

IWDFIoRequest::FormatUsingCurrentType

IWDFIoRequest::ForwardToIoQueue

IWDFIoRequest::GetCompletionParams

IWDFIoRequest::GetCreateParameters

IWDFIoRequest::GetDeviceIoControlParameters

IWDFIoRequest::GetFileObject

IWDFIoRequest::GetInputMemory

IWDFIoRequest::GetIoQueue

IWDFIoRequest::GetOutputMemory

IWDFIoRequest::GetReadParameters

IWDFIoRequest::GetRequestorProcessId

IWDFIoRequest::GetType

IWDFIoRequest::GetWriteParameters

IWDFIoRequest::Impersonate

IWDFIoRequest::IsFrom32BitProcess

IWDFIoRequest::MarkCancelable

IWDFIoRequest::Send

IWDFIoRequest::SetCompletionCallback

IWDFIoRequest::SetInformation

IWDFIoRequest::UnmarkCancelable


IWDFIoRequest::CancelSentRequest

The CancelSentRequest method attempts to cancel the I/O request that the driver previously submitted to an I/O target.

BOOL
  CancelSentRequest(
    void
    );

Parameters

None

Return Value

CancelSentRequest returns a BOOL value that indicates whether the cancel request was successfully delivered to the request's owner. TRUE indicates the request was successfully delivered. FALSE indicates the request was not successfully delivered.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A driver can call CancelSentRequest to attempt to cancel the I/O request that it previously sent to an I/O target by calling the IWDFIoRequest::Send method.

If the request is in the I/O target's queue, the framework cancels the request. If the framework already delivered the request to the I/O target's driver, and if that driver previously called IWDFIoRequest::MarkCancelable to enabling canceling, the framework calls that driver's IRequestCallbackCancel::OnCancel method. If the target's driver did not call IWDFIoRequest::MarkCancelable, the request is not canceled unless the request subsequently becomes cancelable.

If the driver previously registered the IRequestCallbackRequestCompletion interface for the request's completion routine, the framework calls the completion routine after the request is canceled.

Example

To be supplied.

See Also

IRequestCallbackCancel::OnCancel, IRequestCallbackRequestCompletion, IWDFIoRequest::MarkCancelable, IWDFIoRequest::Send


IWDFIoRequest::Complete

The Complete method completes an I/O request.

void
  Complete(
    IN HRESULT  CompletionStatus
    );

Parameters

CompletionStatus
A status value to complete the request with.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

Instead of calling Complete, the driver can call the IWDFIoRequest::CompleteWithInformation method.

Example

The following code example completes a request with the failure that occurred when a memory object could not be retrieved.

    IWDFIoRequest* FxRequest;
    HRESULT hr = S_OK;
    IWDFMemory* FxInputMemory = NULL;

    FxRequest->GetInputMemory(&FxInputMemory);
    if (S_OK != hr) {
    FxRequest->Complete(hr);
    }

See Also

IWDFIoRequest::CompleteWithInformation


IWDFIoRequest::CompleteWithInformation

The CompleteWithInformation method completes a request with the supplied information.

void
  CompleteWithInformation(
    IN HRESULT  CompletionStatus,
    IN SIZE_T  Information
    );

Parameters

CompletionStatus
A status value to complete the request with.

Information
Additional driver-supplied information that is related to the I/O operation.

For read, write, and device I/O control operations, the driver should supply the number of bytes that are transferred.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

For a code example of how to use the CompleteWithInformation method, see IWDFIoRequest::Send.

See Also

IWDFIoRequest::Complete, IWDFIoRequest::Send


IWDFIoRequest::FormatUsingCurrentType

The FormatUsingCurrentType method formats an I/O request so that the driver can forward it, unmodified, to the next-lower driver.

void
  FormatUsingCurrentType(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

When a driver receives an I/O request, the driver might forward the request to the local I/O target, unmodified. To forward the unmodified request, the driver must:

  • Call FormatUsingCurrentType to format the request so that the framework can pass the request to the driver's local I/O target.
  • Call the IWDFIoRequest::Send method to send the request to the I/O target.

Example

For a code example of how to use the FormatUsingCurrentType method, see IWDFIoRequest::Send.

See Also

IWDFIoRequest::Send


IWDFIoRequest::ForwardToIoQueue

The ForwardToIoQueue method forwards (that is, requeues) an I/O request to one of the calling driver's I/O queues.

HRESULT
  ForwardToIoQueue(
    IN IWDFIoQueue*  pDestination
    );

Parameters

pDestination
A pointer to the IWDFIoQueue interface for the destination queue object.

Return Value

ForwardToIoQueue returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A driver cannot requeue a request to the same queue that the request came from. Also, the ForwardToIoQueue method cannot requeue a request that the driver obtained by calling the IWDFIoQueue::RetrieveNextRequest method.

The request cannot be cancelable. If the driver previously called the IWDFIoRequest::MarkCancelable method to make the request cancelable, the driver must call the IWDFIoRequest::UnmarkCancelable method before calling ForwardToIoQueue.

Example

The following code example shows how to forward a request to another queue if the request's buffer is insufficient to hold the required information.

HRESULT hr;
  if (OutputBufferSizeInBytes < sizeof(SWITCH_STATE)) {
      hr = HRESULT_FROM_NT(ERROR_INSUFFICIENT_BUFFER);
  }
  else {
      hr = FxRequest->ForwardToIoQueue(
                      m_Device->GetSwitchChangeQueue()
                      );
      if (SUCCEEDED(hr)) {
          completeRequest = false;
      }
  }

See Also

IWDFIoQueue, IWDFIoQueue::RetrieveNextRequest, IWDFIoRequest::MarkCancelable, IWDFIoRequest::UnmarkCancelable


IWDFIoRequest::GetCompletionParams

The GetCompletionParams method retrieves the parameters object for the completion of an I/O request object.

void
  GetCompletionParams(
    OUT IWDFRequestCompletionParams**  ppCompletionParams
    );

Parameters

ppCompletionParams
A pointer to a variable that receives a pointer to the IWDFRequestCompletionParams interface.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example shows how to retrieve and use the parameters object for the completion of an I/O request object.

    CComPtr<IWDFDevice> wdfDevice;
    CComPtr<IWDFIoRequest> request = NULL;

    PBYTE buffer;

    CComPtr<IWDFMemory> memory;

    CComPtr<IWDFRequestCompletionParams> completionParams;

    ULONG bytesReturned;

    HRESULT hr;

    //
    // Allocate a request.
    //

    hr = wdfDevice->CreateRequest(NULL, NULL, &request);

    //
    // Format a request and send it to a target.
    // If the send succeeded, retrieve the status and the
    // number of bytes transferred.
    //

     request->GetCompletionParams(&completionParams);
     hr = completionParams->GetCompletionStatus();
     bytesReturned = completionParams->GetInformation();

See Also

IWDFRequestCompletionParams


IWDFIoRequest::GetCreateParameters

The GetCreateParameters method retrieves the request parameters for a create-type request.

void
  GetCreateParameters(
    OUT ULONG*  pOptions,
    OUT USHORT*  pFileAttributes,
    OUT USHORT*  pShareAccess
    );

Parameters

pOptions
A pointer to a variable that receives a bitmask of flags that specify the options that are applied when creating or opening the file that is associated with the request and the action to be taken if the file already exists.

The high 8 bits of this parameter correspond to the Disposition parameter of the kernel-mode IoCreateFileSpecifyDeviceObjectHint function. These 8 bits specify the action to be taken, depending on whether the file already exists.

The low 24 bits of this member correspond to the CreateOptions parameter of IoCreateFileSpecifyDeviceObjectHint.

pFileAttributes
A pointer to a variable that receives a bitmask of attribute flags that is applied when creating or opening the file that is associated with the request. Explicitly specified attributes are applied only when the file is created, superseded, or, in some situations, overwritten. By default, the single FILE_ATTRIBUTE_NORMAL flag is specified. However, this flag can be overridden by any other flag or by a bitwise OR combination of compatible flags. The bitmask of attribute flags corresponds to the FileAttributes parameter of IoCreateFileSpecifyDeviceObjectHint.
pShareAccess
A pointer to a variable that receives a bitmask of flags that specify the share access rights that are requested for the file that is associated with the request. If the received bitmask is zero, exclusive access is being requested. For more information about share access, see the description of the ShareAccess parameter of IoCreateFileSpecifyDeviceObjectHint.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IoCreateFileSpecifyDeviceObjectHint


IWDFIoRequest::GetDeviceIoControlParameters

The GetDeviceIoControlParameters method retrieves the request parameters for a device I/O control-type request.

void
  GetDeviceIoControlParameters(
    OUT ULONG*  pControlCode,
    OUT SIZE_T*  pInBufferSize,
    OUT SIZE_T*  pOutBufferSize
    );

Parameters

pControlCode
A pointer to a variable that receives the control code that identifies the specific operation to be performed.
pInBufferSize
A pointer to a variable that receives the size, in bytes, of the input data buffer for the request. To retrieve the input data buffer, the driver calls the IWDFIoRequest::GetInputMemory method.
pOutBufferSize
A pointer to a variable that receives the size, in bytes, of the output data buffer for the request. To retrieve the output data buffer, the driver calls the IWDFIoRequest::GetOutputMemory method.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The call to GetDeviceIoControlParameters fails if the request type is not a device I/O control type.

Example

To be supplied.

See Also

IWDFIoRequest::GetInputMemory, IWDFIoRequest::GetOutputMemory


IWDFIoRequest::GetFileObject

The GetFileObject method retrieves the file object that is associated with an I/O request.

void
  GetFileObject(
    OUT IWDFFile**  ppFileObject
    );

Parameters

ppFileObject
A pointer to a buffer that receives a pointer to the IWDFFile interface for the file object. Note that returning NULL is valid.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example verifies if a request's file object matches the file object that the caller provides and, if so, performs cleanup processing for the request:

  IWDFIoRequest request;
  IWDFFile *MatchFile;

  IWDFFile *fxFile;

  request->GetFileObject(&fxFile);

  if (MatchFile == fxFile) {
      Device->CancelRequest(request, TRUE);
  }

See Also

IWDFFile


IWDFIoRequest::GetInputMemory

The GetInputMemory method retrieves the memory object that represents the input buffer in an I/O request.

void
  GetInputMemory(
    OUT IWDFMemory**  ppWdfMemory
    );

Parameters

ppWdfMemory
A pointer to a variable that receives a pointer to the reference-counted IWDFMemory interface for the memory object. Note that returning NULL is valid; in this situation, no input memory is associated with the I/O request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

Before a driver completes an I/O request, the driver must call the IWDFMemory::Release method for the memory object. The underlying memory object is freed when the request is completed.

The input buffer that is associated with the I/O request contains information (for example, data to be written to a disk) that the originator of the request supplied. The driver can call GetInputMemory to obtain the input buffer for a write request or a device I/O control request, but not for a read request (because read requests do not provide input data). To access the input buffer, the driver must call the IWDFMemory::GetDataBuffer method.

Example

For a code example of how to use the GetInputMemory method, see IWDFIoRequest::Complete.

See Also

IWDFIoRequest::Complete, IWDFMemory, IWDFMemory::GetDataBuffer


IWDFIoRequest::GetIoQueue

The GetIoQueue method retrieves the I/O queue object that is associated with an I/O request.

void
  GetIoQueue(
    OUT IWDFIoQueue**  ppWdfIoQueue
    );

Parameters

ppWdfIoQueue
A pointer to a variable that receives a pointer to the IWDFIoQueue interface for the I/O queue object that the I/O request is associated with.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFIoQueue


IWDFIoRequest::GetOutputMemory

The GetOutputMemory method retrieves the memory object that represents the output buffer for an I/O request.

void
  GetOutputMemory(
    OUT IWDFMemory**  ppWdfMemory
    );

Parameters

ppWdfMemory
A pointer to a variable that receives a pointer to the reference-counted IWDFMemory interface for the memory object. Note that returning NULL is valid; in this situation, no output memory is associated with the I/O request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

Before a driver completes an I/O request, the driver must call the IWDFMemory::Release method for the memory object. The underlying memory object is freed when the request is completed.

The output buffer that is associated with the I/O request contains information (for example, data from a disk) that the driver provides to the originator of the request. The driver can call GetOutputMemory to obtain the output buffer for a read request or a device I/O control request, but not for a write request (because write requests do not provide output data). To access the output buffer, the driver must call the IWDFMemory::GetDataBuffer method.

Example

For a code example of how to use the GetOutputMemory method, see IWDFIoQueue::RetrieveNextRequest.

See Also

IWDFIoQueue::RetrieveNextRequest, IWDFMemory, IWDFMemory::GetDataBuffer


IWDFIoRequest::GetReadParameters

The GetReadParameters method retrieves the request parameters for a read-type request.

void
  GetReadParameters(
    OUT SIZE_T*  pSizeInBytes,
    OUT LONGLONG*  pllOffset,
    OUT ULONG*  pulKey
    );

Parameters

pSizeInBytes
A pointer to a variable that receives the size, in bytes, to read. To retrieve the data for reading, the driver calls the IWDFIoRequest::GetOutputMemory method.
pllOffset
A pointer to a variable that receives the offset, in bytes, to begin reading from the device or the file on the device. If the device does not support absolute read addresses, pllOffset can be ignored. For more information, see the following Comments section.

Client applications specify this value in the Offset and OffsetHigh members of the OVERLAPPED structure. A pointer to OVERLAPPED is passed in the Microsoft Win32 ReadFile or ReadFileEx function.

pulKey
A pointer to a variable that receives a key that the driver can use to sort the I/O request in a way that the driver determines.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A call to GetReadParameters fails if the request type is not a read type.

For devices that support addressing (for example, a disk device), the value that the pllOffset parameter points to is typically the byte offset into the device. For devices that do not support addressing (for example, a serial port), the driver can ignore the value at pllOffset.

Example

To be supplied.

See Also

IWDFIoRequest::GetOutputMemory


IWDFIoRequest::GetRequestorProcessId

The GetRequestorProcessId method retrieves the identifier of the process that sent an I/O request.

ULONG
  GetRequestorProcessId(
    void
    );

Parameters

None

Return Value

GetRequestorProcessId returns the identifier of the process that sent the I/O request.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFIoRequest::GetType

The GetType method retrieves the type of operation that a request contains.

WDF_REQUEST_TYPE
  GetType(
    void
    );

Parameters

None

Return Value

GetType returns a WDF_REQUEST_TYPE-typed value that identifies the request type and why the request is sent to the driver.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example processes a request according to its operation type by first comparing the request object's type with a known type.

void
CMyQueue::OnCompletion(
    IWDFIoRequest*                 FxRequest,
    IWDFIoTarget*                  FxIoTarget,
    IWDFRequestCompletionParams*   CompletionParams,
    PVOID                          Context
    )
{
    UNREFERENCED_PARAMETER(FxIoTarget);
    UNREFERENCED_PARAMETER(Context);

    //
    // If this request is a read request, invert the bits read
    // because they were inverted during write so that the
    // application would read the identical data that it wrote.
    //

    if (WdfRequestRead == FxRequest->GetType()) {
        HandleReadRequestCompletion(
            FxRequest,
            CompletionParams
            );
    }
    else {
        //
        // Otherwise, complete the request object with the
        // identical parameters that the lower request was
        // completed with.
        //

        FxRequest->CompleteWithInformation(
            CompletionParams->GetCompletionStatus(),
            CompletionParams->GetInformation()
            );
    }
}

See Also

WDF_REQUEST_TYPE


IWDFIoRequest::GetWriteParameters

The GetWriteParameters method retrieves the request parameters for a write-type request.

void
  GetWriteParameters(
    OUT SIZE_T*  pSizeInBytes,
    OUT LONGLONG*  pllOffset,
    OUT ULONG*  pulKey
    );

Parameters

pSizeInBytes
A pointer to a variable that receives the size, in bytes, to write. To retrieve the data for writing, the driver calls the IWDFIoRequest::GetOutputMemory method.
pllOffset
A pointer to a variable that receives the offset, in bytes, to begin writing to the device or the file on the device. If the device does not support absolute write addresses, pllOffset can be ignored. For more information, see the following Comments section.

Client applications specify this value in the Offset and OffsetHigh members of the OVERLAPPED structure. A pointer to OVERLAPPED is passed in the Microsoft Win32 WriteFile or WriteFileEx function.

pulKey
A pointer to a variable that receives a key that the driver can use to sort the I/O request in a way that the driver determines.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A call to GetWriteParameters fails if the request type is not a write type.

For devices that support addressing (for example, a disk device), the value that the pllOffset parameter points to is typically the byte offset into the device. For devices that do not support addressing (for example, a serial port), the driver can ignore the value at pllOffset.

Example

To be supplied.

See Also

IWDFIoRequest::GetOutputMemory


IWDFIoRequest::Impersonate

The Impersonate method registers the interface for the method that the framework should call for impersonation.

HRESULT
  Impersonate(
    IN SECURITY_IMPERSONATION_LEVEL  ImpersonationLevel,
    IN IImpersonateCallback*  pCallback,
    IN void*  pvCallbackContext
    );

Parameters

ImpersonationLevel
A SECURITY_IMPERSONATION_LEVEL-typed value that identifies the level of impersonation.
pCallback
A pointer to the IImpersonateCallback interface whose method the framework calls for impersonation.

pvCallbackContext
A pointer to a buffer that contains context information that is related to the impersonation call. The framework passes this context information in a call to the IImpersonateCallback::OnImpersonate method.

Return Value

Impersonate returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IImpersonateCallback, IImpersonateCallback::OnImpersonate, SECURITY_IMPERSONATION_LEVEL


IWDFIoRequest::IsFrom32BitProcess

The IsFrom32BitProcess method determines whether a request originated from a 32-bit process.

BOOL
  IsFrom32BitProcess(
    void
    );

Parameters

None

Return Value

IsFrom32BitProcess returns a BOOL value that indicates whether the request originated from a 32-bit process. TRUE indicates the request originated from a 32-bit process. FALSE indicates the request did not originate from a 32-bit process.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFIoRequest::MarkCancelable

The MarkCancelable method enables the canceling of the I/O request.

void
  MarkCancelable(
    IN IRequestCallbackCancel*  pCancelCallback
    );

Parameters

pCancelCallback
A pointer to the IRequestCallbackCancel interface whose method the framework calls after the I/O request is canceled.

Return Value

MarkCancelable returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

After a driver receives an I/O request as input to an IQueueCallbackRead::OnRead, IQueueCallbackWrite::OnWrite, or IQueueCallbackDeviceIoControl::OnDeviceIoControl event callback function, the driver can call the MarkCancelable method to enable canceling of the request. Later, the driver can call the IWDFIoRequest::UnmarkCancelable method to disable canceling of the request.

Before a driver calls MarkCancelable, the driver must implement the IRequestCallbackCancel::OnCancel method. Otherwise, the call to MarkCancelable returns ERROR_INVALID_PARAMETER.

The driver must call IWDFIoRequest::Complete, either from the IRequestCallbackCancel::OnCancel method or from its regular I/O completion path.

After a driver calls MarkCancelable to enable canceling, the request remains cancelable while the driver has possession of the request object, unless the driver calls UnmarkCancelable to disable canceling.

If the driver calls the IWDFIoRequest::ForwardToIoQueue method to forward the request to a different queue, the following rules apply:

  • Canceling of I/O requests cannot be enabled when the driver forwards the requests to a different queue.

    Typically, the driver should not call MarkCancelable to enable canceling a request before calling IWDFIoRequest::ForwardToIoQueue. Alternatively, the driver can make the request cancelable. However, the driver must then call UnmarkCancelable to disable canceling the request before calling IWDFIoRequest::ForwardToIoQueue.

  • While the request is in a second queue, the framework owns it and can cancel it without notifying the driver.
  • After the framework dequeues the request from the second queue and delivers the request to the driver, the driver can call MarkCancelable to enable canceling.

Example

The following code example sets up a request so that the framework can cancel it.

    //
    // The QueryInteraface should not fail.
    //
    (VOID)this->QueryInterface(_uuidof(IRequestCallbackCancel), (PVOID *)&cancelCallback);

    pWdfRequest->MarkCancelable(cancelCallback);

See Also

IQueueCallbackDeviceIoControl::OnDeviceIoControl, IQueueCallbackRead::OnRead, IQueueCallbackWrite::OnWrite, IRequestCallbackCancel, IRequestCallbackCancel::OnCancel, IWDFIoRequest::Complete, IWDFIoRequest::ForwardToIoQueue, IWDFIoRequest::UnmarkCancelable


IWDFIoRequest::Send

The Send method sends a request to the specified I/O target.

HRESULT
  Send(
    IN IWDFIoTarget*  pIoTarget,
    IN ULONG  Flags,
    IN LONGLONG  Timeout
    );

Parameters

pIoTarget
A pointer to the IWDFIoTarget interface for the I/O target object, which typically represents a lower driver in the stack.
Flags
A valid bitwise OR of the following WDF_REQUEST_SEND_OPTIONS_FLAGS-typed values that indicates how the driver sends the request.
Value | Meaning
WDF_REQUEST_SEND_OPTION_TIMEOUT (0x01) | Time out the request in the amount of time that the Timeout parameter specifies.
WDF_REQUEST_SEND_OPTION_SYNCHRONOUS (0x02) | Send the request synchronously.
WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE (0x04) | Ignore the state of the I/O target when the driver sends the request.
WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET (0x08) | Send the request and take no further action.

Timeout
The amount of time, in system time units (100-nanosecond intervals), that can elapse before the framework automatically cancels the I/O request.
  • If the value is negative, the expiration time is relative to the current system time.
  • If the value is positive, the expiration time is specified as an absolute time (which is relative to January 1, 1601).
  • If the value is zero, the framework does not time out the request.

Relative expiration times are not affected by any changes to the system time that might occur within the specified time-out period. Absolute expiration times reflect system time changes.

Return Value

Send returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Note that returning S_OK indicates only that the request was sent to the target and not that the request was completed.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A call to the Send method is an asynchronous operation (that is, it returns immediately) unless the WDF_REQUEST_SEND_OPTION_SYNCHRONOUS flag is passed for the Flags parameter.

Example

The following code example forwards a request to the next device in the device stack, which can be the next device in user mode or the top device in kernel mode (that is, the reflector's down device).

    IWDFIoRequest* FxRequest;

    //
    // Set the completion callback.
    // When the lower request is completed, the driver is
    // notified through the completion callback.
    //

    IRequestCallbackRequestCompletion *completionCallback =
        QueryIRequestCallbackRequestCompletion();

    FxRequest->SetCompletionCallback(
        completionCallback,
        NULL                    //pContext
        );

    completionCallback->Release();

    //
    // Copy the current I/O stack location's parameters to
    // the next stack location.

    FxRequest->FormatUsingCurrentType( );

    //
    // Send down the request.
    //
    HRESULT hrSend = S_OK;

    hrSend = FxRequest->Send(
                m_FxIoTarget,
                0,              // Asynchronous
                0               //No time-out
                );

    if (S_OK != hrSend) {
        //
        // If the send failed, the driver must complete the
        // request with the failure.
        FxRequest->CompleteWithInformation(hrSend, 0);
    }

See Also

IWDFIoTarget


IWDFIoRequest::SetCompletionCallback

The SetCompletionCallback method registers the interface for the method that the framework should call when an I/O request completes.

void
  SetCompletionCallback(
    IN IRequestCallbackRequestCompletion*  pCompletionCallback,
    IN void*  pContext
    );

Parameters

pCompletionCallback
A pointer to the IRequestCallbackRequestCompletion interface whose method the framework calls after the I/O request completes, or NULL if the driver deregisters a previously registered completion routine.

pContext
A pointer to a buffer that contains context information that is related to the request completion. The framework passes this context information in a call to the IRequestCallbackRequestCompletion::OnCompletion method.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

If a driver that forwards an I/O request requires notification when the lower-level driver completes the request, the driver can provide a completion routine and call SetCompletionCallback to register the IRequestCallbackRequestCompletion interface for the completion routine. The framework calls the completion routine after the lower-level driver completes the I/O request.

Example

For a code example of how to use the SetCompletionCallback method, see IWDFIoRequest::Send.

See Also

IRequestCallbackRequestCompletion, IRequestCallbackRequestCompletion::OnCompletion, IWDFIoRequest::Send


IWDFIoRequest::SetInformation

The SetInformation method sets the size of information for a request.

void
  SetInformation(
    IN ULONG_PTR  Information
    );

Parameters

Information
A ULONG_PTR value that specifies the size of information to set for the request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example sets the size of a request's information.

HRESULT
CUmdfHidFile::HandleGetCollectionInformation(
    __in IWDFIoRequest* WdfRequest
    )
{
    PHIDP_COLLECTION_DESC collectionDesc = m_Collection->GetCollectionDesc();
    HID_COLLECTION_INFORMATION collectionInfo;

    CComPtr<IWDFMemory> wdfMemory;

    HRESULT hr = HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER);

    collectionInfo.DescriptorSize = collectionDesc->PreparsedDataLength;
    collectionInfo.Polled = false;
    collectionInfo.Reserved1[0] = 0;
    collectionInfo.VendorID = 0;
    collectionInfo.ProductID = 0;
    collectionInfo.VersionNumber = 0;

    WdfRequest->GetOutputMemory(&wdfMemory);

    if (wdfMemory != NULL)
    {
        hr = wdfMemory->CopyFromBuffer(0,
                              &collectionInfo,
                              sizeof(collectionInfo));
    }

    if (SUCCEEDED(hr))
    {
        WdfRequest->SetInformation(sizeof(collectionInfo));
    }

    return hr;
}


IWDFIoRequest::UnmarkCancelable

The UnmarkCancelable method disables the canceling of an I/O request.

HRESULT
  UnmarkCancelable(
    void
    );

Parameters

None

Return Value

UnmarkCancelable returns one of the following values:

S_OK
UnmarkCancelable disabled use of the IRequestCallbackCancel::OnCancel method that was previously registered through a call to the IWDFIoRequest::MarkCancelable method.
HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED)
The request is currently being canceled.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

If the driver previously called the IWDFIoRequest::MarkCancelable method to enable canceling of the request, it can call the UnmarkCancelable method to disable canceling of the request.

If the driver previously called IWDFIoRequest::MarkCancelable but the IWDFIoRequest::Complete method has not yet been called from within a call to the driver's IRequestCallbackCancel::OnCancel callback method, the driver must call UnmarkCancelable before it calls IWDFIoRequest::Complete outside of a call to its IRequestCallbackCancel::OnCancel method.

If UnmarkCancelable returns HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED), the driver's IRequestCallbackCancel::OnCancel method either was called or is about to be called. The driver should not attempt to use the request object after UnmarkCancelable returns HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED) if the driver's IRequestCallbackCancel::OnCancel has already called IWDFIoRequest::Complete to complete the request.

Example

The following code example sets the request as not cancelable.

    hr = request->UnmarkCancelable();

See Also

IRequestCallbackCancel::OnCancel, IWDFIoRequest::Complete, IWDFIoRequest::MarkCancelable


IWDFIoRequestCompletionParams

The IWDFIoRequestCompletionParams interface exposes the parameters object for the completion of an I/O request object. The parameters object is primarily required for asynchronous I/O and layered drivers.

In addition to the methods that IWDFIoRequestCompletionParams inherits from the IWDFRequestCompletionParams interface, IWDFIoRequestCompletionParams supports the following methods:

IWDFIoRequestCompletionParams::GetIoctlParameters

IWDFIoRequestCompletionParams::GetReadParameters

IWDFIoRequestCompletionParams::GetWriteParameters


IWDFIoRequestCompletionParams::GetIoctlParameters

The GetIoctlParameters method retrieves parameters that are associated with the completion of a device I/O control request.

void
  GetIoctlParameters(
    OUT ULONG*  pIoControlCode,
    OUT IWDFMemory**  ppInputMemory,
    OUT SIZE_T*  pInputMemoryOffset,
    OUT IWDFMemory**  ppOutputMemory,
    OUT SIZE_T*  pOutputMemoryOffset,
    OUT SIZE_T*  pOutBytes
        );

Parameters

pIoControlCode
A pointer to a variable that receives the control code that identifies the specific operation to be performed
ppInputMemory
A pointer to a variable that receives a pointer to the IWDFMemory interface for access to the input buffer for the completion of the device I/O control request.
pInputMemoryOffset
A pointer to a variable that receives the offset, in bytes, into the input buffer for the completion of the I/O control request.
ppOutputMemory
A pointer to a variable that receives a pointer to the IWDFMemory interface for access to the output buffer for the completion of the device I/O control request.
pOutputMemoryOffset
A pointer to a variable that receives the offset, in bytes, into the output buffer for the completion of the I/O control request.
pOutBytes
A pointer to a variable that receives the number of bytes that are output for the completion of the device I/O control request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFMemory


IWDFIoRequestCompletionParams::GetReadParameters

The GetReadParameters method retrieves parameters that are associated with the completion of a read request.

void
  GetReadParameters(
    OUT IWDFMemory**  ppReadMemory,
    OUT SIZE_T*  pBytesRead,
    OUT SIZE_T*  pReadMemoryOffset
    );

Parameters

ppReadMemory
A pointer to a variable that receives a pointer to the IWDFMemory interface for access to the read buffer for the completion of the read request.
pBytesRead
A pointer to a variable that receives the size, in bytes, of the read buffer for the completion of the read request.
pReadMemoryOffset
A pointer to a variable that receives the offset, in bytes, into the read buffer for the completion of the read request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFMemory


IWDFIoRequestCompletionParams::GetWriteParameters

The GetWriteParameters method retrieves parameters that are associated with the completion of a write request.

void
  GetWriteParameters(
    OUT IWDFMemory**  ppWriteMemory,
    OUT SIZE_T*  pBytesWritten,
    OUT SIZE_T*  pWriteMemoryOffset
    );

Parameters

ppWriteMemory
A pointer to a variable that receives a pointer to the IWDFMemory interface for access to the write buffer for the completion of the write request.
pBytesWritten
A pointer to a variable that receives the size, in bytes, of the write buffer for the completion of the write request.
pWriteMemoryOffset
A pointer to a variable that receives the offset, in bytes, into the write buffer for the completion of the write request.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFMemory


IWDFIoTarget

The IWDFIoTarget interface exposes the I/O target object that typically represents a lower driver in the stack.

In addition to the methods that IWDFIoTarget inherits from the IWDFObject interface, IWDFIoTarget supports the following method:

IWDFIoTarget::CancelSentRequestsForFile

IWDFIoTarget::FormatRequestForIoctl

IWDFIoTarget::FormatRequestForRead

IWDFIoTarget::FormatRequestForWrite

IWDFIoTarget::GetTargetFile


IWDFIoTarget::CancelSentRequestsForFile

The CancelSentRequestsForFile method cancels all I/O requests that have been sent on behalf of the specified file object.

void
  CancelSentRequestsForFile(
    IN IWDFFile*  pFile
    );

Parameters

pFile
A pointer to the IWDFFile interface for the file object to cancel all I/O requests for.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example shows a UMDF driver implementation of the IFileCallbackCleanup::OnCleanupFile method that cancels all previously sent I/O requests.

void
CQueue::OnCleanupFile(
        /*[in]*/ IWDFFile*          pFileObject
        )
{
    m_Parent->GetWriteTarget()->CancelSentRequestsForFile(pFileObject);
    m_Parent->GetReadTarget()->CancelSentRequestsForFile(pFileObject);

    return;
}

See Also

IWDFFile


IWDFIoTarget::FormatRequestForIoctl

The FormatRequestForIoctl method formats an I/O request object for an I/O control operation.

HRESULT
  FormatRequestForIoctl(
    IN IWDFIoRequest*  pRequest,
    IN ULONG  IoctlCode,
    IN IWDFFile*  pFile,
    IN IWDFMemory*  pInputMemory,
    IN PWDFMEMORY_OFFSET  pInputMemoryOffset,
    IN IWDFMemory*  pOutputMemory,
    IN PWDFMEMORY_OFFSET  pOutputMemoryOffset
    );

Parameters

pRequest
A pointer to the IWDFIoRequest interface for the request object to format.
IoctlCode
A control code that identifies a specific operation to perform.
pFile
A pointer to the IWDFFile interface for the file object that is associated with the I/O control request.
pInputMemory
A pointer to the IWDFMemory interface that is used to access the input buffer for the request. This parameter is optional.
pInputMemoryOffset
A pointer to a WDFMEMORY_OFFSET structure that describes the input memory offset for the request. This parameter is optional.
pOutputMemory
A pointer to the IWDFMemory interface that is used to access the output buffer for the request. This parameter is optional.
pOutputMemoryOffset
A pointer to a WDFMEMORY_OFFSET structure that describes the output memory offset for the request. This parameter is optional.

Return Value

FormatRequestForIoctl returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFFile, IWDFIoRequest, IWDFMemory, WDFMEMORY_OFFSET


IWDFIoTarget::FormatRequestForRead

The FormatRequestForRead method formats an I/O request object for a read operation.

HRESULT
  FormatRequestForRead(
    IN IWDFIoRequest*  pRequest,
    IN IWDFFile*  pFile,
    IN IWDFMemory*  pOutputMemory,
    IN PWDFMEMORY_OFFSET  pOutputMemoryOffset,
    IN PLONGLONG  DeviceOffset
    );

Parameters

pRequest
A pointer to the IWDFIoRequest interface for the request object to format.
pFile
A pointer to the IWDFFile interface for the file object that is associated with the read request.
pOutputMemory
A pointer to the IWDFMemory interface that is used to access the buffer that is used for the read request. This parameter is optional.
pOutputMemoryOffset
A pointer to a WDFMEMORY_OFFSET structure that describes the output memory offset that is used for the read. This parameter is optional.
DeviceOffset
A pointer to the device offset that is used for the read. This parameter is optional.

Return Value

FormatRequestForRead returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

For a code example of how to use the FormatRequestForRead method, see IWDFDevice::CreateRequest.

See Also

IWDFFile, IWDFIoRequest, IWDFMemory, WDFMEMORY_OFFSET


IWDFIoTarget::FormatRequestForWrite

The FormatRequestForWrite method formats an I/O request object for a write operation.

HRESULT
  FormatRequestForWrite(
    IN IWDFIoRequest*  pRequest,
    IN IWDFFile*  pFile,
    IN IWDFMemory*  pInputMemory,
    IN PWDFMEMORY_OFFSET  pInputMemoryOffset,
    IN PLONGLONG  DeviceOffset
    );

Parameters

pRequest
A pointer to the IWDFIoRequest interface for the request object to format.
pFile
A pointer to the IWDFFile interface for the file object that is associated with the write request.
pInputMemory
A pointer to the IWDFMemory interface that is used to access the buffer that is used for the write request. This parameter is optional.
pInputMemoryOffset
A pointer to a WDFMEMORY_OFFSET structure that describes the input memory offset that is used for the write request. This parameter is optional.
DeviceOffset
A pointer to the device offset that is used for the write request. This parameter is optional.

Return Value

FormatRequestForWrite returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example formats a request for writing before forwarding the request.

    IWDFIoRequest * pNewRequest = NULL;
     IWDFMemory *pInputMemory = NULL;
     IWDFIoTarget *pWriteTarget = m_Parent->GetWriteTarget();
      IWDFFile *pTargetFile = NULL;

     pWdfRequest->GetInputMemory(&pInputMemory);

     hr = m_Parent->GetFxDevice()->CreateRequest(NULL, NULL, &pNewRequest);

     if (SUCCEEDED(hr))
     {
         pWriteTarget->GetTargetFile(&pTargetFile);

         hr = pWriteTarget->FormatRequestForWrite(
                    pNewRequest,
                    pTargetFile,
                    pInputMemory,
                    NULL,
                    NULL
                    );
            }

     if (SUCCEEDED(hr))
     {
         pNewRequest->AssignContext(NULL, (PVOID)pWdfRequest);
     }

     if (SUCCEEDED(hr))
     {
         ForwardRequest(pNewRequest, pWriteTarget, TRUE);
     }
     else
     {
         pWdfRequest->Complete(hr);
     }

See Also

IWDFFile, IWDFIoRequest, IWDFMemory, WDFMEMORY_OFFSET


IWDFIoTarget::GetTargetFile

The GetTargetFile method retrieves the file object that is associated with the I/O target object.

void
  GetTargetFile(
    OUT IWDFFile**  ppFileObject
    );

Parameters

ppFileObject
Pointer to a buffer that receives a pointer to the IWDFFile interface for the I/O target's file object.

Return Value

None

Headers

Declared in wudfddi.h. Include wudfddi.h.

Comments

An I/O target object that is bound to a WDF file object automatically applies the file that is associated with that file object to requests that are formatted through that I/O target object.

When formatting a request, an I/O target object (for example, the default I/O target) enables a user to use the same file that the request started with or a new file.

Example

For a code example of how to use the GetTargetFile method, see IWDFIoTarget::FormatRequestForWrite.

See Also

IWDFFile


IWDFIoTargetStateManagement

The IWDFIoTargetStateManagement interface exposes methods that manage and monitor the state of an I/O target object.

In addition to the methods that IWDFIoTargetStateManagement inherits from the IUnknown interface, IWDFIoTargetStateManagement supports the following methods:

IWDFIoTargetStateManagement::GetState

IWDFIoTargetStateManagement::Remove

IWDFIoTargetStateManagement::Start

IWDFIoTargetStateManagement::Stop


IWDFIoTargetStateManagement::GetState

The GetState method retrieves the current state of an I/O target object.

WDF_IO_TARGET_STATE
  GetState(
    void
    );

Parameters

None

Return Value

GetState returns one of the following WDF_IO_TARGET_STATE-typed values that identifies the current state of an I/O target object.

Value | Meaning
WdfIoTargetStateUndefined (0) | The I/O target state is undefined.
WdfIoTargetStarted (1) | The I/O target started.
WdfIoTargetStopped (2) | The I/O target stopped.
WdfIoTargetClosedForQueryRemove (3) | The I/O target is closed because it was sent a query for removal.
WdfIoTargetClosed (4) | The I/O target is closed.
WdfIoTargetDeleted (5) | The I/O target is deleted.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFIoTargetStateManagement::Remove

The Remove method removes an I/O target object.

HRESULT
  Remove(
    IN BOOL  bIsSurpriseRemove
    );

Parameters

bIsSurpriseRemove
A BOOL value that specifies whether the remove operation is a surprise. TRUE indicates a surprise remove operation; FALSE indicates that the operation is not a surprise.

Return Value

Remove returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFIoTargetStateManagement::Start

The Start method starts an I/O target object.

HRESULT
  Start(
    void
    );

Parameters

None

Return Value

Start returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFIoTargetStateManagement::Stop

The Stop method stops an I/O target object.

HRESULT
  Stop(
    IN WDF_IO_TARGET_SENT_IO_ACTION  Action
    );

Parameters

Action
A WDF_IO_TARGET_SENT_IO_ACTION-typed value that identifies how to handle sent I/O when the I/O target object is stopped.
Values | Meaning
WdfIoTargetSentIoUndefined (0) | How the sent I/O is handled is undefined.
WdfIoTargetCancelSentIo (1) | Cancel sent I/O.
WdfIoTargetWaitForSentIoToComplete (2) | Wait for sent I/O to complete before stopping the I/O target object.
WdfIoTargetLeaveSentIoPending (3) | Let sent I/O remain pending.

Return Value

Stop returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFMemory

The IWDFMemory interface exposes the framework memory object that provides access to a memory block.

In addition to the methods that IWDFMemory inherits from the IWDFObject interface, IWDFMemory supports the following methods:

IWDFMemory::CopyFromBuffer

IWDFMemory::CopyFromMemory

IWDFMemory::CopyToBuffer

IWDFMemory::GetDataBuffer

IWDFMemory::GetSize


IWDFMemory::CopyFromBuffer

The CopyFromBuffer method safely copies data from the specified source buffer to a memory object.

HRESULT
  CopyFromBuffer(
    IN ULONG_PTR  DestOffset,
    IN void*  pSourceBuffer,
    IN SIZE_T  NumOfBytesToCopyFrom
    );

Parameters

DestOffset
The offset, in bytes, into the memory object to start to copy data to.
pSourceBuffer
A pointer to the source buffer that data is copied from.

NumOfBytesToCopyFrom
The number of bytes to copy from the buffer that pSourceBuffer points to.

Return Value

CopyFromBuffer returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

For a code example of how to use the CopyFromBuffer method, see IWDFIoQueue::RetrieveNextRequest.

See Also

IWDFIoQueue::RetrieveNextRequest


IWDFMemory::CopyFromMemory

The CopyFromMemory method safely copies data from the specified source buffer and prevents overruns that the copy operation might otherwise cause.

HRESULT
  CopyFromMemory(
    IN IWDFMemory*  pSource,
    IN PWDFMEMORY_OFFSET  pSourceOffset
    );

Parameters

pSource
A pointer to the IWDFMemory interface for the memory object that is the source of the copy operation.

pSourceOffset
A pointer to a WDFMEMORY_OFFSET structure that describes the information that is copied from a memory block.

The BufferOffset member of the WDFMEMORY_OFFSET structure, if not NULL, indicates the offset into the source buffer to start the copy operation from.

The BufferLength member should be set to 0; the framework ignores this member because the amount of data that is copied depends on the length and offset combination of the current destination buffer.

Return Value

CopyFromMemory returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

IWDFMemory, WDFMEMORY_OFFSET


IWDFMemory::CopyToBuffer

The CopyToBuffer method safely copies data from a memory object to the specified target buffer.

HRESULT
  CopyToBuffer(
    IN ULONG_PTR  SourceOffset,
    IN void*  pTargetBuffer,
    IN SIZE_T  NumOfBytesToCopyTo
    );

Parameters

SourceOffset
The offset, in bytes, into the memory object to start to copy data from.
pTargetBuffer
A pointer to the target buffer that data is copied to.

NumOfBytesToCopyTo
The number of bytes to copy to the buffer that pTargetBuffer points to.

Return Value

CopyToBuffer returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

The following code example obtains a memory object from a request object and then copies a specific amount of data from the memory object to a buffer.

    // Get a memory object from a request object.
    pWdfRequest->GetInputMemory(&pRequestMemory);

    // Copy from the memory object to a buffer.

    hr = pRequestMemory->CopyToBuffer(0, m_Buffer, BytesToWrite);


IWDFMemory::GetDataBuffer

The GetDataBuffer method retrieves the data buffer that is associated with a memory object.

void*
  GetDataBuffer(
    OUT SIZE_T*  pBufferSize
    );

Parameters

pBufferSize
A pointer to a variable that receives information that describes the size of the data buffer.

Return Value

GetDataBuffer returns a pointer to the data buffer.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

For a code example of how to use the GetDataBuffer method, see IWDFDevice::SetPnpState.


IWDFMemory::GetSize

The GetSize method retrieves the size of the data buffer that is associated with a memory object.

SIZE_T
  GetSize(
    void
    );

Parameters

None

Return Value

GetSize returns the size, in bytes, of the data buffer for the memory object.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFMemory::SetBuffer

The SetBuffer method assigns a specified buffer to a memory object that a driver created by calling IWDFDriver::CreatePreallocatedWdfMemoryObject.

void
  SetBuffer(
    IN void*  Buffer,
    IN SIZE_T  BufferSize
    );

Parameters

Buffer
A pointer to a driver-supplied buffer.

BufferSize
The nonzero size, in bytes, of the buffer that Buffer points to.

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The SetBuffer method can assign a buffer to a memory object that IWDFDriver::CreatePreallocatedWdfMemoryObject created, but not to a memory object that IWDFDriver::CreateWdfMemory created.

Example

To be supplied.

See Also

IWDFIoQueue::RetrieveNextRequest


IWDFNamedPropertyStore

The IWDFNamedPropertyStore interface exposes a property-store object.

In addition to the methods that IWDFNamedPropertyStore inherits from the IUnknown interface, IWDFNamedPropertyStore supports the following methods:

IWDFNamedPropertyStore::GetNameAt

IWDFNamedPropertyStore::GetNameCount

IWDFNamedPropertyStore::GetNamedValue

IWDFNamedPropertyStore::SetNamedValue


IWDFNamedPropertyStore::GetNameAt

The GetNameAt method retrieves the name of a property.

HRESULT
  GetNameAt(
    IN DWORD  iProp,
    OUT PWSTR*  ppwszName
    );

Parameters

iProp
The zero-based index of the property that GetNameAt retrieves the name from.
ppwszName
A pointer to a variable that receives a pointer to a NULL-terminated string that contains the name of the property.

Return Value

GetNameAt returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFNamedPropertyStore::GetNameCount

The GetNameCount method retrieves the number of properties in a property store.

HRESULT
  GetNameCount(
    OUT DWORD*  pdwCount
    );

Parameters

pdwCount
A pointer to a variable that receives the number of properties in the property store.

Return Value

GetNameCount returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.


IWDFNamedPropertyStore::GetNamedValue

The GetNamedValue method retrieves the value of a property.

HRESULT
  GetNamedValue(
    IN LPCWSTR  pszName,
    OUT PROPVARIANT*  pv
    );

Parameters

pszName
A pointer to a null-terminated string that contains the name of the property.
pv
A pointer to a variable that receives the value for the property.

Return Value

GetNamedValue returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The following variant types are supported for property values. The following table shows the variant type that is returned regardless of the original variant type.

Variant type | Variant type retrieved
VT_BSTR | While clients read a string value, the value is returned as VT_LPWSTR regardless of the original variant type that was used to write the value.
VT_LPWSTR
VT_LPSTR
VT_I1 | While clients read an integer value, the value is returned as VT_UI4 regardless of the original variant type that was used to write the value.
VT_UI1
VT_I2
VT_UI2
VT_I4
VT_UI4
VT_UINT
VT_BLOB | The binary value is returned as VT_BLOB.
VT_VECTOR | VT_LPWSTR | The string array is returned as VT_VECTOR | VT_LPWSTR

A string that contains environment variables is expanded on read.

Example

To be supplied.


IWDFNamedPropertyStore::SetNamedValue

The SetNamedValue method sets the value of a property.

HRESULT
  SetNamedValue(
    IN LPCWSTR  pszName,
    IN const PROPVARIANT*  pv
    );

Parameters

pszName
A pointer to a null-terminated string that contains the name of the property.
pv
A pointer to the value that the property is set to.

Return Value

SetNamedValue returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The following variant types are supported for property values. The following table shows the types of values that the framework writes for particular variant types.

Variant type | Write
VT_BSTR | Writes a string value.
VT_LPWSTR
VT_LPSTR
VT_I1 | Writes an integer value.
VT_UI1
VT_I2
VT_UI2
VT_I4
VT_UI4
VT_UINT
VT_BLOB | Writes a binary value.
VT_VECTOR | VT_LPWSTR | Writes a string array.

Example

To be supplied.


IWDFObject

The IWDFObject interface exposes the framework base object that provides the basic functionality common across all framework object types. All framework objects are derived from this root object.

In addition to the methods that IWDFObject inherits from the IUnknown interface, IWDFObject supports the following methods:

IWDFObject::AcquireLock

IWDFObject::AssignContext

IWDFObject::DeleteWdfObject

IWDFObject::ReleaseLock

IWDFObject::RetrieveContext


IWDFObject::AcquireLock

The AcquireLock method prevents the framework from calling methods of interfaces that a driver registered.

void
  AcquireLock(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

If a driver configured itself to use the WdfDeviceLevel locking scheme, the framework automatically acquires the “presentation” lock before calling into the driver. (For more information about this locking scheme, see Specifying a Callback Synchronization Mode.) The AcquireLock and IWDFObject::ReleaseLock methods acquire and release the presentation lock, respectively. Framework device objects and framework I/O queue objects currently support the AcquireLock method.

The driver calls the AcquireLock method to manipulate its objects that were created from its callback interfaces outside the callback scope in a thread-safe manner. The AcquireLock method represents an advanced feature of the framework that most drivers will not use because improper usage can result in deadlocks.

Unsynchronized code can call AcquireLock. The driver should call on objects that match its synchronization scope.

Example

For a code example of how to use the AcquireLock method, see IWDFDevice::SetPnpState.

See Also

IWDFObject::ReleaseLock


IWDFObject::AssignContext

The AssignContext method registers a context and a driver-supplied cleanup callback function for the object.

HRESULT
  AssignContext(
    IN IObjectCleanup*  pCleanupCallback,
    IN void*  pContext
    );

Parameters

pCleanupCallback
A pointer to the IObjectCleanup interface that contains the cleanup callback function, which performs cleanup operations for the object if it becomes invalid.
pContext
A pointer to the context to register. NULL is a valid context.

Return Value

AssignContext returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A driver calls AssignContext to register a context and to request notification when the object becomes invalid. In a AssignContext call, the driver passes a pointer to the IObjectCleanup interface in the pCleanupCallback parameter to register IObjectCleanup. Note that the framework internally holds a reference to the supplied IObjectCleanup interface while the object is valid. When the object becomes invalid, the framework calls the IObjectCleanup::OnCleanup method to notify the driver. The framework automatically releases the reference to the supplied IObjectCleanup after calling IObjectCleanup::OnCleanup.

At any given time, only one context that is associated with each object instance can exist. Attempts to register additional contexts fail.

A context can be associated only with an object that is in a valid state. For example, an attempt to associate a context with an object that is in the process of deletion fails.

Because the context is not a Component Object Model (COM) interface, the driver must not treat the context as such. For example, the driver cannot call the AddRef method on the context.

The IWDFObject::RetrieveContext method can be used to retrieve the context that was previously registered through AssignContext.

Example

For a code example of how to use the AssignContext method, see IWDFIoTarget::FormatRequestForWrite.

See Also

IObjectCleanup, IObjectCleanup::OnCleanup, IWDFObject::RetrieveContext


IWDFObject::DeleteWdfObject

The DeleteWdfObject method deletes a previously created Microsoft Windows Driver Foundation (WDF) object.

HRESULT
  DeleteWdfObject(
    void
    );

Parameters

None

Return Value

DeleteWdfObject returns S_OK if the operation succeeds. Otherwise, this method returns HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) or one of the other error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A driver is unable to delete some WDF objects. For example, the driver cannot delete a framework device object because the framework owns and controls device objects. For more information about the hierarchy of WDF objects, see Framework Object Hierarchy.

The driver typically deletes only WDF objects that it creates and owns. For more information about deleting framework objects, see Managing the Lifetime of Objects.

However, when a parent object is deleted, all child objects are automatically deleted. For example, if the driver called IWDFDevice::CreateIoQueue to create an I/O queue object, the newly created I/O queue becomes a child of the device object. The I/O queue object is then automatically deleted when the device object is deleted without the driver explicitly calling DeleteWdfObject.

Example

For a code example of how to use the DeleteWdfObject method, see IWDFDevice::SetPnpState.

See Also

IWDFDevice::CreateIoQueue


IWDFObject::ReleaseLock

The ReleaseLock method allows the framework to call methods of interfaces that are registered by the driver that the framework previously prevented from calling because the driver called the IWDFObject::AcquireLock method.

void
  ReleaseLock(
    void
    );

Parameters

None

Return Value

None

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

For a code example of how to use the ReleaseLock method, see IWDFDevice::SetPnpState.

See Also

IWDFObject::AcquireLock


IWDFObject::RetrieveContext

The RetrieveContext method retrieves a context that was previously registered through the IWDFObject::AssignContext method.

HRESULT
  RetrieveContext(
    OUT void**  ppvContext
    );

Parameters

ppvContext
A pointer to a buffer that receives a pointer to the previously registered context.

Return Value

RetrieveContext returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

Because the context is not a Component Object Model (COM) interface, the driver must not treat the context as such. For example, the driver cannot call the AddRef method on the context.

Example

For a code example of how to use the RetrieveContext method, see IWDFIoQueue::GetDevice.

See Also

IWDFIoQueue::GetDevice, IWDFObject::AssignContext


IWDFRequestCompletionParams

The IWDFRequestCompletionParams interface exposes the parameters object for the completion of an I/O request object. The parameters object is primarily required for asynchronous I/O and layered drivers.

In addition to the methods that IWDFRequestCompletionParams inherits from the IUnknown interface, IWDFRequestCompletionParams supports the following methods:

IWDFRequestCompletionParams::GetCompletedRequestType

IWDFRequestCompletionParams::GetCompletionStatus

IWDFRequestCompletionParams::GetInformation


IWDFRequestCompletionParams::GetCompletedRequestType

The GetCompletedRequestType method retrieves the type of operation that the request to be completed contains.

WDF_REQUEST_TYPE
  GetCompletedRequestType(
    void
    );

Parameters

None

Return Value

GetCompletedRequestType returns a WDF_REQUEST_TYPE-typed value that identifies the request type and why the request was sent to the driver.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

To be supplied.

See Also

WDF_REQUEST_TYPE


IWDFRequestCompletionParams::GetCompletionStatus

The GetCompletionStatus method retrieves the completion status of an I/O request.

HRESULT
  GetCompletionStatus(
    void
    );

Parameters

None

Return Value

GetCompletionStatus returns S_OK for a successful completion status. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

For a code example of how to use the GetCompletionStatus method, see IWDFIoRequest::GetCompletionParams.


IWDFRequestCompletionParams::GetInformation

The GetInformation method retrieves information that is associated with the completion of an I/O request.

ULONG_PTR
  GetInformation(
    void
    );

Parameters

None

Return Value

GetInformation returns information (for example, the number of bytes transferred) that is associated with the completion of the I/O request.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Example

For a code example of how to use the GetInformation method, see IWDFDevice::SetPnpState.


IWDFUsbInterface

The IWDFUsbInterface interface exposes a USB interface that a USB device exposes.

In addition to the methods that IWDFUsbInterface inherits from the IWDFObject interface, IWDFUsbInterface supports the following methods:

IWDFUsbInterface::GetConfiguredSettingIndex

IWDFUsbInterface::GetInterfaceDescriptor

IWDFUsbInterface::GetInterfaceNumber

IWDFUsbInterface::GetNumEndPoints

IWDFUsbInterface::GetWinUsbHandle

IWDFUsbInterface::RetrieveUsbPipeObject

IWDFUsbInterface::SelectSetting


IWDFUsbInterface::GetConfiguredSettingIndex

The GetConfiguredSettingIndex method retrieves the current setting index for a USB interface.

UCHAR
  GetConfiguredSettingIndex(
    void
    );

Parameters

None

Return Value

GetConfiguredSettingIndex returns the current setting index for the USB interface.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The GetConfiguredSettingIndex method is provided for convenience because a UMDF driver can obtain the current setting index from the bAlternateSetting member of the USB_INTERFACE_DESCRIPTOR structure that the driver retrieves when it calls the IWDFUsbInterface::GetInterfaceDescriptor method.

Example

To be supplied.

See Also

IWDFUsbInterface::GetInterfaceDescriptor, USB_INTERFACE_DESCRIPTOR


IWDFUsbInterface::GetInterfaceDescriptor

The GetInterfaceDescriptor method retrieves a descriptor for a USB interface.

void
  GetInterfaceDescriptor(
    OUT PUSB_INTERFACE_DESCRIPTOR  UsbAltInterfaceDescriptor
    );

Parameters

UsbAltInterfaceDescriptor
A pointer to a variable that receives the USB interface descriptor.

Return Value

None

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

After a UMDF driver calls the IWDFUsbTargetDevice::RetrieveUsbInterface method to retrieve the first USB interface for the USB device, a UMDF driver should retrieve the descriptor for the USB interface. Therefore, the GetInterfaceDescriptor method does not fail.

Example

For a code example of how to use the GetInterfaceDescriptor method, see IWDFUsbTargetFactory::CreateUsbTargetDevice.

See Also

IWDFUsbTargetDevice::RetrieveUsbInterface


IWDFUsbInterface::GetInterfaceNumber

The GetInterfaceNumber method retrieves the index of a USB interface.

UCHAR
  GetInterfaceNumber(
    void
    );

Parameters

None

Return Value

GetInterfaceNumber returns the index of the USB interface.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Example

To be supplied.


IWDFUsbInterface::GetNumEndPoints

The GetNumEndPoints method retrieves the number of endpoints (pipes) on a USB interface.

UCHAR
  GetNumEndPoints(
    void
    );

Parameters

None

Return Value

GetNumEndPoints returns the number of endpoints on the USB interface.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The GetNumEndPoints method is provided for convenience because a UMDF driver can obtain the number of endpoints from the bNumEndpoints member of the USB_INTERFACE_DESCRIPTOR structure that the driver retrieves when it calls the IWDFUsbInterface::GetInterfaceDescriptor method.

Example

The following code example retrieves the number of pipes on a USB interface and then retrieves particular types of pipes.

    HRESULT  hr;
    UCHAR  NumEndPoints;
    NumEndPoints = pIUsbInterface->GetNumEndPoints();

    if (NumEndPoints != NUM_OSRUSB_ENDPOINTS) {
            hr = E_UNEXPECTED;
    }
    if (SUCCEEDED(hr))  {
        for (UCHAR PipeIndex = 0; PipeIndex < NumEndPoints; PipeIndex++) {
            hr = pIUsbInterface->RetrieveUsbPipeObject(PipeIndex,
                                                  &pIUsbPipe);
            if (FAILED(hr)) {
                // Output an error.
            }
            else {
                if ( pIUsbPipe->IsInEndPoint() && (UsbdPipeTypeBulk == pIUsbPipe->GetType()) ) {
                    pIUsbInputPipe = pIUsbPipe;
                }
                else if ( pIUsbPipe->IsOutEndPoint() && (UsbdPipeTypeBulk == pIUsbPipe->GetType()) )
                {
                    pIUsbOutputPipe = pIUsbPipe;
                }
                else
                {
                    SAFE_RELEASE(pIUsbPipe);
                }
            }

See Also

IWDFUsbInterface::GetInterfaceDescriptor, USB_INTERFACE_DESCRIPTOR


IWDFUsbInterface::GetWinUsbHandle

The GetWinUsbHandle method retrieves the WinUsb interface handle that is associated with a USB interface.

WINUSB_INTERFACE_HANDLE
  GetWinUsbHandle(
    void
    );

Parameters

None

Return Value

GetWinUsbHandle returns the WinUsb interface handle that is associated with the USB interface.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The GetWinUsbHandle method returns the WinUsb interface handle that the framework obtained internally by using the WinUsb_Initialize function. A UMDF driver can use the WinUsb interface handle to escape to the WinUSB User-Mode Client Interface, if required.

The UMDF driver should not call the WinUsb_Free function to free the WinUsb interface handle because the USB interface object owns the handle.

Example

To be supplied.

See Also

WinUsb_Free, WinUsb_Initialize


IWDFUsbInterface::RetrieveUsbPipeObject

The RetrieveUsbPipeObject method retrieves a USB pipe object for the specified pipe index.

HRESULT
  RetrieveUsbPipeObject(
    IN UCHAR  PipeIndex,
    OUT IWDFUsbTargetPipe**  ppPipe
    );

Parameters

PipeIndex
The index of the USB pipe object to retrieve.
ppPipe
A pointer to a variable that receives a pointer to the IWDFUsbTargetPipe interface for the USB pipe object whose index is specified by PipeIndex.

Return Value

RetrieveUsbPipeObject returns one of the following values:

S_OK
RetrieveUsbPipeObject successfully retrieved the USB pipe object.
E_OUTOFMEMORY
RetrieveUsbPipeObject encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

A UMDF driver can call the methods of the IWDFUsbTargetPipe interface that the RetrieveUsbPipeObject method retrieves to obtain the type of pipe and other information.

Example

For a code example of how to use the RetrieveUsbPipeObject method, see IWDFUsbInterface::GetNumEndPoints.

See Also

IWDFUsbTargetPipe


IWDFUsbInterface::SelectSetting

The SelectSetting method selects the specified setting on a USB interface.

HRESULT
  SelectSetting(
    IN UCHAR  SettingNumber
    );

Parameters

SettingNumber
The setting to select on the USB interface.

Return Value

SelectSetting returns one of the following values:

S_OK
SelectSetting successfully selected the setting that the SettingNumber parameter specified.
E_OUTOFMEMORY
SelectSetting encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The SelectSetting method generates a UMDF request and synchronously sends the request to the I/O target.

Example

To be supplied.


IWDFUsbRequestCompletionParams

The IWDFUsbRequestCompletionParams interface exposes the parameters object for the completion of a USB request object. The parameters object is primarily required for asynchronous I/O and layered drivers.

In addition to the methods that IWDFUsbRequestCompletionParams inherits from the IWDFRequestCompletionParams interface, IWDFUsbRequestCompletionParams supports the following methods:

IWDFUsbRequestCompletionParams::GetCompletedUsbRequestType

IWDFUsbRequestCompletionParams::GetDeviceControlTransferParameters

IWDFUsbRequestCompletionParams::GetPipeReadParameters

IWDFUsbRequestCompletionParams::GetPipeWriteParameters


IWDFUsbRequestCompletionParams::GetCompletedUsbRequestType

The GetCompletedUsbRequestType method retrieves the type of operation that the request to be completed contains.

WDF_USB_REQUEST_TYPE
  GetCompletedUsbRequestType(
    void
    );

Parameters

None

Return Value

GetCompletedUsbRequestType returns a value of type WDF_USB_REQUEST_TYPE that identifies the USB request type.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Example

To be supplied.

See Also

WDF_USB_REQUEST_TYPE


IWDFUsbRequestCompletionParams::GetDeviceControlTransferParameters

The GetDeviceControlTransferParameters method retrieves parameters that are associated with the completion of a device I/O control request.

void
  GetDeviceControlTransferParameters(
    OUT IWDFMemory**  ppMemory,
    OUT ULONG*  pLengthTransferred,
    OUT SIZE_T*  pOffset,
    OUT PWINUSB_SETUP_PACKET  pSetupPacket
        );

Parameters

ppMemory
A pointer to a variable that receives a pointer to the IWDFMemory interface for access to the buffer for the completion of the device I/O control request.
pLengthTransferred
A pointer to a variable that receives the size, in bytes, of transferred data.
pOffset
A pointer to a variable that receives the offset, in bytes, into the buffer for the completion of the I/O control request.
pSetupPacket
A pointer that receives the WinUsb setup packet for the control transfer. This pointer is a PWINUSB_SETUP_PACKET data type that is defined as PVOID.

Return Value

None

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Example

To be supplied.

See Also

IWDFMemory


IWDFUsbRequestCompletionParams::GetPipeReadParameters

The GetPipeReadParameters method retrieves parameters that are associated with the completion of a read request.

void
  GetPipeReadParameters(
    OUT IWDFMemory**  ppReadMemory,
    OUT SIZE_T*  pBytesRead,
    OUT SIZE_T*  pReadMemoryOffset
    );

Parameters

ppReadMemory
A pointer to a variable that receives a pointer to the IWDFMemory interface for access to the read buffer for the completion of the read request.
pBytesRead
A pointer to a variable that receives the size, in bytes, of the read buffer for the completion of the read request.
pReadMemoryOffset
A pointer to a variable that receives the offset, in bytes, into the read buffer for the completion of the read request.

Return Value

None

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Example

To be supplied.

See Also

IWDFMemory


IWDFUsbRequestCompletionParams::GetPipeWriteParameters

The GetPipeWriteParameters method retrieves parameters that are associated with the completion of a write request.

void
  GetPipeWriteParameters(
    OUT IWDFMemory**  ppWriteMemory,
    OUT SIZE_T*  pBytesWritten,
    OUT SIZE_T*  pWriteMemoryOffset
    );

Parameters

ppWriteMemory
A pointer to a variable that receives a pointer to the IWDFMemory interface for access to the write buffer for the completion of the write request.
pBytesWritten
A pointer to a variable that receives the size, in bytes, of the write buffer for the completion of the write request.
pWriteMemoryOffset
A pointer to a variable that receives the offset, in bytes, into the write buffer for the completion of the write request.

Return Value

None

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Example

To be supplied.

See Also

IWDFMemory


IWDFUsbTargetDevice

The IWDFUsbTargetDevice interface exposes a USB device I/O target object.

In addition to the methods that IWDFUsbTargetDevice inherits from the IWDFIoTarget interface, IWDFUsbTargetDevice supports the following methods:

IWDFUsbTargetDevice::FormatRequestForControlTransfer

IWDFUsbTargetDevice::GetNumInterfaces

IWDFUsbTargetDevice::GetWinUsbHandle

IWDFUsbTargetDevice::RetrieveDescriptor

IWDFUsbTargetDevice::RetrieveDeviceInformation

IWDFUsbTargetDevice::RetrievePowerPolicy

IWDFUsbTargetDevice::RetrieveUsbInterface

IWDFUsbTargetDevice::SetPowerPolicy


IWDFUsbTargetDevice::FormatRequestForControlTransfer

The FormatRequestForControlTransfer method formats an I/O request object for a USB control transfer.

HRESULT
  FormatRequestForControlTransfer(
    IN IWDFIoRequest*  pRequest,
    IN PWINUSB_SETUP_PACKET  SetupPacket,
    IN IWDFMemory*  pMemory,
    IN PWDFMEMORY_OFFSET  TransferOffset
    );

Parameters

pRequest
A pointer to the IWDFIoRequest interface for the request object to format.
SetupPacket
A pointer to a WinUsb setup packet (which is a PWINUSB_SETUP_PACKET data type that is defined as PVOID) for the control transfer.
pMemory
A pointer to the IWDFMemory interface that is used to access the buffer that is used for the control transfer. This parameter is optional.
TransferOffset
A pointer to a WDFMEMORY_OFFSET structure that describes the memory offset that is used for the control transfer. This parameter is optional.

Return Value

FormatRequestForControlTransfer returns one of the following values:

S_OK
FormatRequestForControlTransfer successfully formatted an I/O request object.
E_OUTOFMEMORY
FormatRequestForControlTransfer encountered an allocation failure.
E_INVALIDARG
The memory offset that the TransferOffset parameter specified was invalid.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

After a UMDF driver calls FormatRequestForControlTransfer to format an I/O request for a control transfer operation, the framework can subsequently send the request to the I/O target.

Example

The following code example formats an I/O request object for a USB control transfer.

    //
    // Format the request as a control pipe transfer to get
    // a report descriptor.
    //

    WDF_USB_CONTROL_SETUP_PACKET requestParameters;

    WDF_USB_CONTROL_SETUP_PACKET_INIT(
        &requestParameters,
        BmRequestDeviceToHost,
        BmRequestToInterface,
        USB_REQUEST_GET_DESCRIPTOR,
        (m_HidDescriptor->bReportType << 8),
        m_InterfaceNumber
        );

    if (SUCCEEDED(hr))
    {
        hr = m_UsbTargetDevice->FormatRequestForControlTransfer(
                                    request,
                                    (PWINUSB_SETUP_PACKET) &requestParameters,
                                    memory,
                                    NULL
                                    );
    }

See Also

IWDFIoRequest, IWDFMemory, WDFMEMORY_OFFSET


IWDFUsbTargetDevice::GetNumInterfaces

The GetNumInterfaces method retrieves the number of USB interfaces for the USB device.

UCHAR
  GetNumInterfaces(
    void
    );

Parameters

None

Return Value

GetNumInterfaces returns the number of IWDFUsbInterface interfaces for the USB device in the default (zero) configuration.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

UMDF USB I/O target devices do not support multiple configurations.

Example

The following code example retrieves the number of USB interfaces for the USB device.

    UCHAR NumInterfaces = pIUsbTargetDevice->GetNumInterfaces();

See Also

IWDFUsbInterface


IWDFUsbTargetDevice::GetWinUsbHandle

The GetWinUsbHandle method retrieves the WinUsb interface handle that is associated with a I/O target device object.

WINUSB_INTERFACE_HANDLE
  GetWinUsbHandle(
    void
    );

Parameters

None

Return Value

GetWinUsbHandle returns the WinUsb interface handle that is associated with the I/O target device object.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The GetWinUsbHandle method returns the WinUsb interface handle that the framework obtained internally by using the WinUsb_Initialize function. A UMDF driver can use the WinUsb interface handle to escape to the WinUSB User-Mode Client Interface, if required.

The UMDF driver should not call the WinUsb_Free function to free the WinUsb interface handle because the I/O target device object owns the handle.

Example

To be supplied.

See Also

WinUsb_Free, WinUsb_Initialize


IWDFUsbTargetDevice::RetrieveDescriptor

The RetrieveDescriptor method retrieves a USB descriptor, which can describe a device, configuration, or string.

HRESULT
  RetrieveDescriptor(
    IN UCHAR  DescriptorType,
    IN UCHAR  Index,
    IN USHORT  LanguageID,
    IN/OUT ULONG*  BufferLength,
    OUT PVOID  Buffer
    );

Parameters

DescriptorType
The type of USB descriptor that the UMDF driver requests.

Index
The index of the descriptor, according to the USB specification.
LanguageID
The identifier of the language, if the UMDF driver requests a string descriptor; otherwise, this parameter is zero.
BufferLength
A pointer to a variable that, on input, contains the size, in bytes, of the buffer that RetrieveDescriptor supplies in Buffer. On output, this parameter contains the size that RetrieveDescriptor requires for Buffer.
Buffer
A pointer that receives the buffer that contains the USB descriptor.

Return Value

RetrieveDescriptor returns one of the following values:

S_OK
RetrieveDescriptor successfully retrieved the USB descriptor.
E_OUTOFMEMORY
RetrieveDescriptor encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

For information about valid descriptor types that a UMDF driver can pass for the DescriptorType parameter, see the WinUsb_GetDescriptor function.

The RetrieveDescriptor method generates a UMDF request and synchronously sends the request to the I/O target.

Example

The following code example retrieves a USB configuration descriptor.

HRESULT
CUmdfHidDevice::RetrieveConfigDescriptor(
    __out_bcount(ConfigDescriptorCb) PUSB_CONFIGURATION_DESCRIPTOR *ConfigDescriptor,
    __out ULONG *ConfigDescriptorCb
    )
{
    ULONG descriptorCb = sizeof(USB_CONFIGURATION_DESCRIPTOR);
    USB_CONFIGURATION_DESCRIPTOR descriptorHeader;
    PBYTE descriptorBuffer;
    HRESULT hr;
    //
    // Get the configuration descriptor once to determine
    // the length of the entire config descriptor.
    //
    hr = m_UsbTargetDevice->RetrieveDescriptor(
                    USB_CONFIGURATION_DESCRIPTOR_TYPE,
                            0,
                            0,
                            &descriptorCb,
                            &descriptorHeader
                            );
    //
    // Allocate space to hold the entire set of descriptors.
    //
    if (SUCCEEDED(hr)) {
        descriptorCb = 4096;
        descriptorBuffer = new BYTE[descriptorCb];
        if (descriptorBuffer == NULL) {
            hr = E_OUTOFMEMORY;
        }
    }
    //
    // Retrieve the set of descriptors.
    //
    if (SUCCEEDED(hr)) {
        hr = m_UsbTargetDevice->RetrieveDescriptor(
                     USB_CONFIGURATION_DESCRIPTOR_TYPE,
                                    0,
                                    0,
                                    &descriptorCb,
                                    descriptorBuffer
                                    );
    }
    //
    // Store the buffer in the output parameter, or delete it.
    //
    if (SUCCEEDED(hr)) {
        *ConfigDescriptor = (PUSB_CONFIGURATION_DESCRIPTOR) (descriptorBuffer);
        *ConfigDescriptorCb = descriptorCb;
    }
    else {
        delete[] descriptorBuffer;
    }
    return hr;
}

See Also

WinUsb_GetDescriptor


IWDFUsbTargetDevice::RetrieveDeviceInformation

The RetrieveDeviceInformation method retrieves device information of the specified type.

HRESULT
  RetrieveDeviceInformation(
    IN ULONG  InformationType,
    IN/OUT ULONG*  BufferLength,
    OUT PVOID  Buffer
    );

Parameters

InformationType
The type of information that the UMDF driver requests about the device.
BufferLength
A pointer to a variable that, on input, contains the size, in bytes, of the buffer that RetrieveDeviceInformation supplies in Buffer. On output, this parameter contains the size that RetrieveDeviceInformation requires for Buffer.
Buffer
A pointer that receives the buffer that contains the device information.

Return Value

RetrieveDeviceInformation returns one of the following values:

S_OK
RetrieveDeviceInformation successfully retrieved the device information.
E_OUTOFMEMORY
RetrieveDeviceInformation encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

For information about valid information types that a UMDF driver can pass for the InformationType parameter, see the WinUsb_QueryDeviceInformation function.

The RetrieveDeviceInformation method generates a UMDF request and synchronously sends the request to the I/O target.

Example

For a code example of how to use the RetrieveDeviceInformation method, see IWDFUsbTargetPipe::SetPipePolicy.

See Also

WinUsb_QueryDeviceInformation


IWDFUsbTargetDevice::RetrievePowerPolicy

The RetrievePowerPolicy method retrieves a WinUsb power policy.

HRESULT
  RetrievePowerPolicy(
    IN ULONG  PolicyType,
    IN/OUT ULONG*  ValueLength,
    OUT PVOID  Value
    );

Parameters

PolicyType
The type of WinUsb power policy that the UMDF driver requests.
ValueLength
A pointer to a variable that, on input, contains the size, in bytes, of the buffer that RetrievePowerPolicy supplies in Value. On output, this parameter contains the size that RetrievePowerPolicy requires for Value.
Value
A pointer that receives the buffer that contains the WinUsb power policy.

Return Value

RetrievePowerPolicy returns one of the following values:

S_OK
RetrievePowerPolicy successfully retrieved the WinUsb power policy.
E_OUTOFMEMORY
RetrievePowerPolicy encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

Power policy controls the power management that WinUsb for the device performs.

For information about valid policy types that a UMDF driver can pass for the PolicyType parameter and values that the framework returns, see the WinUsb_GetInterfacePowerPolicy function.

The RetrievePowerPolicy method generates a UMDF request and synchronously sends the request to the I/O target.

Example

To be supplied.

See Also

WinUsb_GetInterfacePowerPolicy, IWDFUsbTargetDevice::SetPowerPolicy


IWDFUsbTargetDevice::RetrieveUsbInterface

The RetrieveUsbInterface method retrieves the specified USB interface for a USB device.

HRESULT
  RetrieveUsbInterface(
    IN UCHAR  InterfaceIndex,
    OUT IWDFUsbInterface**  ppUsbInterface
    );

Parameters

InterfaceIndex
The index of the interface to retrieve.
ppUsbInterface
A pointer to a variable that receives a pointer to the specified IWDFUsbInterface interface for the USB device.

Return Value

RetrieveUsbInterface returns one of the following values:

S_OK
RetrieveUsbInterface successfully retrieved the specified USB interface for the USB device.
E_OUTOFMEMORY
RetrieveUsbInterface encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The driver can call the IWDFUsbTargetDevice::GetNumInterfaces method to retrieve the total number of USB interfaces that are available.

Example

For a code example of how to use the RetrieveUsbInterface method, see IWDFUsbTargetFactory::CreateUsbTargetDevice.

See Also

IWDFUsbInterface, IWDFUsbTargetDevice::GetNumInterfaces, USBD_INTERFACE_INFORMATION


IWDFUsbTargetDevice::SetPowerPolicy

The SetPowerPolicy method sets the WinUsb power policy.

HRESULT
  SetPowerPolicy(
    IN ULONG  PolicyType,
    IN ULONG  ValueLength,
    IN PVOID  Value
    );

Parameters

PolicyType
The type of WinUsb power policy that the UMDF driver sets.
ValueLength
The size, in bytes, of the buffer that SetPowerPolicy supplies in Value.
Value
A pointer to the buffer that contains the WinUsb power policy.

Return Value

SetPowerPolicy returns one of the following values:

S_OK
SetPowerPolicy successfully set the WinUsb power policy.
E_OUTOFMEMORY
SetPowerPolicy encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

Power policy controls the power management that WinUsb for the device performs.

For information about valid policy types and values that a UMDF driver can pass for the PolicyType and Value parameters, see the WinUsb_SetInterfacePowerPolicy function.

The SetPowerPolicy method generates a UMDF request and synchronously sends the request to the I/O target.

Example

To be supplied.

See Also

WinUsb_SetInterfacePowerPolicy, IWDFUsbTargetDevice::RetrievePowerPolicy


IWDFUsbTargetFactory

The IWDFUsbTargetFactory interface is a factory interface that is used to create a USB target device object.

In addition to the methods that IWDFUsbTargetFactory inherits from the IUnknown interface, IWDFUsbTargetFactory supports the following method:

IWDFUsbTargetFactory::CreateUsbTargetDevice


IWDFUsbTargetFactory::CreateUsbTargetDevice

The CreateUsbTargetDevice method creates a USB device object that is also an I/O target.

HRESULT
  CreateUsbTargetDevice(
    OUT IWDFUsbTargetDevice**  ppDevice
    );

Parameters

ppDevice
A pointer to a buffer that receives a pointer to the IWDFUsbTargetDevice interface for the USB target device object.

Return Value

CreateUsbTargetDevice returns one of the following values:

S_OK
CreateUsbTargetDevice successfully created a USB device object that is also an I/O target.
E_OUTOFMEMORY
CreateUsbTargetDevice encounteredan allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb_Initialize function returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

A UMDF driver should release the IWDFUsbTargetDevice interface pointer that the CreateUsbTargetDevice method returns in the ppDevice parameter when the driver is done with the interface.

If the file object that is associated with the created I/O target object is required, the driver should call the IWDFIoTarget::GetTargetFile method.

Note IWDFUsbTargetDevice inherits all of the methods of the IWDFIoTarget interface.

To use the newly created USB I/O target object in a device stack, the INF file that installs the UMDF driver must contain the UmdfDispatcher directive and set UmdfDispatcher to WinUsb (UmdfDispatcher=WinUsb) in the DDInstall.WDF section. UmdfDispatcher is required to inform the UMDF platform that it can allow access to the USB I/O target. For more information about UmdfDispatcher, see Specifying WDF Directives.

Example

The following code example shows how to create and use a USB device object in an implementation of the UMDF driver's IPnpCallbackHardware::OnPrepareHardware method.

HRESULT
CUmdfHidDevice::OnPrepareHardware(
    __in IWDFDevice* WdfDevice
    )
{
    CComPtr<IWDFUsbTargetFactory> factory;
    USB_INTERFACE_DESCRIPTOR interfaceDescriptor;
    bool hidInterfaceFound = false;
    PUSB_HID_DESCRIPTOR hidDescriptor;
    NTSTATUS status;
    HRESULT hr = S_OK;
    //
    // Get the USB I/O target factory interface.
    //
    hr = WdfDevice->QueryInterface(IID_PPV_ARGS(&factory));
    //
    // Create the USB I/O target.
    //
    hr = factory->CreateUsbTargetDevice(&m_UsbTargetDevice);
    //
    // Get the configuration descriptor for the target device.
    //
    if (SUCCEEDED(hr))
    {
        hr = RetrieveConfigDescriptor(&m_ConfigDescriptor,
                              &m_ConfigDescriptorCb);
    }
    //
    // Iterate through the interfaces on the device and find the HID interface.
    //
    if (SUCCEEDED(hr))
    {
        CComPtr<IWDFUsbInterface> usbInterface;
        UCHAR index;
        bool found = true;
        for (index = 0; index < m_ConfigDescriptor->bNumInterfaces; index += 1)
        {
            hr = m_UsbTargetDevice->RetrieveUsbInterface(index, &usbInterface);
            if (SUCCEEDED(hr))
            {
                usbInterface->GetInterfaceDescriptor(&interfaceDescriptor);
                if (interfaceDescriptor.bInterfaceClass == 0x3)
                {
                    hidInterfaceFound = true;
                    break;
                }
            }
            else
            {
                break;
            }
        }
        if (SUCCEEDED(hr) && (hidInterfaceFound == false))
        {
            hr = E_FAIL;
        }
    }
    //
    // Get the HID descriptor associated with this interface.
    //
    if (SUCCEEDED(hr))
    {
        hr = ParseHidDescriptor(
                m_ConfigDescriptor,
                m_ConfigDescriptorCb,
                interfaceDescriptor.bInterfaceNumber
                );
    }
    //
    // Process the HID information from the device and setup
    // the collection data structures.
    //
    if (SUCCEEDED(hr))
    {
        hr = SetupCollections();
    }
    return hr;
}

See Also

WinUsb_Initialize, IWDFIoTarget, IWDFIoTarget::GetTargetFile, IWDFUsbTargetDevice


IWDFUsbTargetPipe

The IWDFUsbTargetPipe interface exposes a USB pipe (endpoint), which is also an I/O target.

In addition to the methods that IWDFUsbTargetPipe inherits from the IWDFIoTarget interface, IWDFUsbTargetPipe supports the following methods:

IWDFUsbTargetPipe::Abort

IWDFUsbTargetPipe::Flush

IWDFUsbTargetPipe::GetInformation

IWDFUsbTargetPipe::GetType

IWDFUsbTargetPipe::IsInEndPoint

IWDFUsbTargetPipe::IsOutEndPoint

IWDFUsbTargetPipe::Reset

IWDFUsbTargetPipe::RetrievePipePolicy

IWDFUsbTargetPipe::SetPipePolicy


IWDFUsbTargetPipe::Abort

The Abort method aborts all pending transfers on a USB pipe.

HRESULT
  Abort(
    void
    );

Parameters

None

Return Value

Abort returns one of the following values:

S_OK
Abort successfully aborted all pending transfers.
E_OUTOFMEMORY
Abort encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The Abort method generates a UMDF request and synchronously sends the request to the I/O target.

For more information about how Abort works, see the WinUsb_AbortPipe function.

Example

To be supplied.

See Also

WinUsb_AbortPipe


IWDFUsbTargetPipe::Flush

The Flush method discards any data that WinUsb saved when the device returned more data than the client requested.

HRESULT
  Flush(
    void
    );

Parameters

None

Return Value

Flush returns one of the following values:

S_OK
Flush successfully discarded any extra data that WinUsb saved.
E_OUTOFMEMORY
Flush encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The Flush method generates a UMDF request and synchronously sends the request to the I/O target.

For more information about how Flush works, see the WinUsb_FlushPipe function.

Example

To be supplied.

See Also

WinUsb_FlushPipe


IWDFUsbTargetPipe::GetInformation

The GetInformation method retrieves information about a USB pipe (endpoint).

void
  GetInformation(
    OUT PWINUSB_PIPE_INFORMATION  pInfo
    );

Parameters

pInfo
A pointer to a variable that receives USB pipe information.

Return Value

None

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

After a UMDF driver calls the IWDFUsbInterface::RetrieveUsbPipeObject method to retrieve a USB pipe object, the UMDF driver should retrieve information about the USB pipe. Therefore, the GetInformation method does not fail.

Example

To be supplied.

See Also

IWDFUsbInterface::RetrieveUsbPipeObject


IWDFUsbTargetPipe::GetType

The GetType method retrieves the type of a USB pipe.

USBD_PIPE_TYPE
  GetType(
    void
    );

Parameters

None

Return Value

GetType returns a USBD_PIPE_TYPE value that identifies the type of the USB pipe.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The GetType method is provided for convenience because a UMDF driver can obtain the type of the USB pipe from the PipeType member of the WINUSB_PIPE_INFORMATION structure that the driver retrieves when it calls the IWDFUsbTargetPipe::GetInformation method.

Example

For a code example of how to use the GetType method, see IWDFUsbInterface::GetNumEndPoints.

See Also

IWDFUsbTargetPipe::GetInformation


IWDFUsbTargetPipe::IsInEndPoint

The IsInEndPoint method determines whether a USB pipe (endpoint) is an IN pipe.

BOOL
  IsInEndPoint(
    void
    );

Parameters

None

Return Value

IsInEndPoint returns a BOOL value that indicates whether the USB pipe is an IN pipe. TRUE indicates the pipe is an IN pipe. FALSE indicates the pipe is not an IN pipe.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

If the USB pipe is an IN pipe, a UMDF driver can call the IWDFIoTarget::FormatRequestForRead method to format a read request. The framework can then send the request to the USB pipe.

Note The meaning of IN and OUT is opposite in WDF and USB.

Example

For a code example of how to use the IsInEndPoint method, see IWDFUsbInterface::GetNumEndPoints.

See Also

IWDFIoTarget::FormatRequestForRead


IWDFUsbTargetPipe::IsOutEndPoint

The IsOutEndPoint method determines whether a USB pipe (endpoint) is an OUT pipe.

BOOL
  IsOutEndPoint(
    void
    );

Parameters

None

Return Value

IsOutEndPoint returns a BOOL value that indicates whether the USB pipe is an OUT pipe. TRUE indicates the pipe is an OUT pipe. FALSE indicates the pipe is not an OUT pipe.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

If the USB pipe is an OUT pipe, a UMDF driver can call the IWDFIoTarget::FormatRequestForWrite method to format a write request. The framework can then send the request to the USB pipe.

Note The meaning of IN and OUT is opposite in WDF and USB.

Example

For a code example of how to use the IsOutEndPoint method, see IWDFUsbInterface::GetNumEndPoints.

See Also

IWDFIoTarget::FormatRequestForWrite


IWDFUsbTargetPipe::Reset

The Reset method resets the data toggle and clears the stall condition on a USB pipe.

HRESULT
  Reset(
    void
    );

Parameters

None

Return Value

Reset returns one of the following values:

S_OK
Reset successfully reset the data toggle and cleared the stall condition.
E_OUTOFMEMORY
Reset encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

The Reset method generates a UMDF request and synchronously sends the request to the I/O target.

For more information about how Reset works, see the WinUsb_ResetPipe function.

Example

To be supplied.

See Also

WinUsb_ResetPipe


IWDFUsbTargetPipe::RetrievePipePolicy

The RetrievePipePolicy method retrieves a WinUsb pipe policy.

HRESULT
  RetrievePipePolicy(
    IN ULONG  PolicyType,
    IN/OUT ULONG*  ValueLength,
    OUT PVOID  Value
    );

Parameters

PolicyType
The type of WinUsb pipe policy that the UMDF driver requests.
ValueLength
A pointer to a variable that, on input, contains the size, in bytes, of the buffer that RetrievePipePolicy supplies for Value. On output, this parameter contains the size that RetrievePipePolicy requires for Value.
Value
A pointer that receives the buffer that contains the WinUsb pipe policy.

Return Value

RetrievePipePolicy returns one of the following values:

S_OK
RetrievePipePolicy successfully retrieved the WinUsb pipe policy.
E_OUTOFMEMORY
RetrievePipePolicy encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

Pipe policy controls the behavior of the USB pipe (for example, time-outs, handling short packets, and so on).

For more information about valid policy types that a UMDF driver can pass for the PolicyType parameter and values that the framework returns, see the WinUsb_GetPipePolicy function.

The RetrievePipePolicy method generates a UMDF request and synchronously sends the request to the I/O target.

Example

To be supplied.

See Also

WinUsb_GetPipePolicy, IWDFUsbTargetPipe::SetPipePolicy


IWDFUsbTargetPipe::SetPipePolicy

The SetPipePolicy method sets the WinUsb pipe policy.

HRESULT
  SetPipePolicy(
    IN ULONG  PolicyType,
    IN ULONG  ValueLength,
    IN PVOID  Value
    );

Parameters

PolicyType
The type of WinUsb pipe policy that the UMDF driver sets.
ValueLength
The size, in bytes, of the buffer that SetPipePolicy supplies for Value.
Value
A pointer to the buffer that contains the WinUsb pipe policy.

Return Value

SetPipePolicy returns one of the following values:

S_OK
SetPipePolicy successfully set the WinUsb pipe policy.
E_OUTOFMEMORY
SetPipePolicy encountered an allocation failure.
An error code that is defined in Winerror.h
This value corresponds to the error code that the WinUsb API returned.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.

Comments

Pipe policy controls the behavior of the USB pipe (for example, time-outs, handling short packets, and so on).

For more information about valid policy types and values that a UMDF driver can pass for the PolicyType and Value parameters, see the WinUsb_SetPipePolicy function.

The SetPipePolicy method generates a UMDF request and synchronously sends the request to the I/O target.

Example

The following code example sets policy for input and output pipes.

HRESULT
CMyDevice::ConfigureUsbIoTargets(
    )
{
    HRESULT                 hr;
    USB_INTERFACE_DESCRIPTOR pInterface;
    WINUSB_PIPE_INFORMATION pipe;
    BOOL                    policy;
    DWORD                   err;
    BOOL                    result;
    LONG                    i;
    LONG                    timeout;
    ULONG                   length;

    length = sizeof(UCHAR);
    hr = m_pIUsbTargetDevice->RetrieveDeviceInformation(DEVICE_SPEED,
                                            &length,
                                            &m_Speed);
    if (FAILED(hr)) {
        // Print out error.
    }
    if (SUCCEEDED(hr)) {
        // Print out device speed.
    }
    //
    // Set timeout policies for input and output pipes.
    //
    if (SUCCEEDED(hr))  {
        timeout = ENDPOINT_TIMEOUT;
        hr = m_pIUsbInputPipe->SetPipePolicy(PIPE_TRANSFER_TIMEOUT,
                                       sizeof(timeout),
                                             &timeout);
        if (FAILED(hr)) {
            // Print out cannot set timeout policy for input pipe.
        }
    }
    if (SUCCEEDED(hr))  {
        timeout = ENDPOINT_TIMEOUT;
        hr = m_pIUsbOutputPipe->SetPipePolicy(PIPE_TRANSFER_TIMEOUT,
                                       sizeof(timeout),
                                             &timeout);
        if (FAILED(hr))  {
            // Print out cannot set timeout policy for output pipe.
        }
    }
    return hr;
}

See Also

WinUsb_SetPipePolicy, IWDFUsbTargetPipe::RetrievePipePolicy


User-Mode Driver Framework Structures and Enumeration Types

The following topics describe the enumeration types and structures that User-Mode Driver Framework (UMDF) interfaces use:

SECURITY_IMPERSONATION_LEVEL

UMDF_VERSION_DATA

WDF_IO_QUEUE_DISPATCH_TYPE

WDF_IO_QUEUE_STATE

WDF_PNP_CAPABILITY

WDF_PNP_STATE

WDF_POWER_DEVICE_STATE

WDF_PROPERTY_STORE_DISPOSITION

WDF_PROPERTY_STORE_RETRIEVE_FLAGS

WDF_REQUEST_STOP_ACTION_FLAGS

WDF_REQUEST_TYPE

WDFMEMORY_OFFSET


SECURITY_IMPERSONATION_LEVEL

The SECURITY_IMPERSONATION_LEVEL enumeration contains values that identify security impersonation levels.

typedef enum _SECURITY_IMPERSONATION_LEVEL {
  SecurityAnonymous,
  SecurityIdentification,
  SecurityImpersonation,
  SecurityDelegation
} SECURITY_IMPERSONATION_LEVEL;

Values

SecurityAnonymous
The driver cannot impersonate or identify the client.
SecurityIdentification
The driver can obtain the identity and privileges of the client but cannot impersonate the client.
SecurityImpersonation
The driver can impersonate the client's security context on the local system.
SecurityDelegation
The driver can impersonate the client's security context on remote systems.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

For more information about impersonation in the UMDF, see Handling Impersonation.

A UMDF driver supplies one of the values of SECURITY_IMPERSONATION_LEVEL to the IWDFIoRequest::Impersonate method to set the security impersonation level.

See Also

IWDFIoRequest::Impersonate


UMDF_VERSION_DATA

The UMDF_VERSION_DATA structure describes a version of the framework.

typedef struct UMDF_VERSION_DATA {
  ULONG  MajorNumber;
  ULONG  MinorNumber;
  ULONG  ServiceNumber;
} UMDF_VERSION_DATA, *PUMDF_VERSION_DATA;

Members

MajorNumber
A number that specifies the major version of the framework.
MinorNumber
A number that specifies the minor version of the framework.
ServiceNumber
A number that specifies the service of the framework.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A UMDF driver supplies a pointer to a UMDF_VERSION_DATA structure to the IWDFDriver::IsVersionAvailable method to describe the minimum version of the framework that the driver supports.

See Also

IWDFDriver::IsVersionAvailable


WDF_IO_QUEUE_DISPATCH_TYPE

The WDF_IO_QUEUE_DISPATCH_TYPE enumeration contains values that identify how a driver must receive requests from an I/O queue.

typedef enum _WDF_IO_QUEUE_DISPATCH_TYPE {
  WdfIoQueueDispatchSequential  = 1,
  WdfIoQueueDispatchParallel  = 2,
  WdfIoQueueDispatchManual  = 3,
  WdfIoQueueDispatchMaximum
} WDF_IO_QUEUE_DISPATCH_TYPE;

Values

WdfIoQueueDispatchSequential
The I/O queue's requests are presented to the driver's I/O queue callback functions one at a time. The framework delivers the next request after the driver calls the IWDFIoRequest::Complete method to complete the current request.
WdfIoQueueDispatchParallel
The framework presents requests to the driver's I/O queue callback functions as soon as the requests are available.
WdfIoQueueDispatchManual
The framework places requests into the queue but does not deliver them to the driver. The driver must call the IWDFIoQueue::RetrieveNextRequest method to retrieve a request from the queue.
WdfIoQueueDispatchMaximum
Valid enumeration values were exceeded.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFIoQueue::RetrieveNextRequest, IWDFIoRequest::Complete


WDF_IO_QUEUE_STATE

The WDF_IO_QUEUE_STATE enumeration contains values that identify the state of an I/O queue.

typedef enum _WDF_IO_QUEUE_STATE {
  WdfIoQueueAcceptRequests  = 0x01,
  WdfIoQueueDispatchRequests  = 0x02,
  WdfIoQueueNoRequests  = 0x04,
  WdfIoQueueDriverNoRequests  = 0x08,
  WdfIoQueuePnpHeld  = 0x10
} WDF_IO_QUEUE_STATE, *PWDF_IO_QUEUE_STATE;

Values

WdfIoQueueAcceptRequests
If this value is set to 1, the queue accepts requests by automatically forwarding them through the setting of the IWDFIoQueue::ConfigureRequestDispatching method or by manually forwarding each request through a call to the IWDFIoRequest::ForwardToIoQueue method.

If this value is set to 0, the queue completes any automatically forwarded requests with “status canceled” or fails IWDFIoRequest::ForwardToIoQueue with “status busy”.

WdfIoQueueDispatchRequests
If this value is set to 1, the queue automatically presents requests to the driver, unless the queue is a WdfIoQueueDispatchManual type (see WDF_IO_QUEUE_DISPATCH_TYPE).

If this value is set to 0, the queue does not automatically dispatch requests to the driver. The setting of this status does not prevent the driver from calling the IWDFIoQueue::RetrieveNextRequest method to manually retrieve a request from the queue.

WdfIoQueueNoRequests
If this value is set to 1, no requests are in the queue, even requests that can be presented to the driver and that can be returned from IWDFIoQueue::RetrieveNextRequest.
WdfIoQueueDriverNoRequests
If this value is set to 1, there are no requests that the driver currently operates on that it received from the queue.
WdfIoQueuePnpHeld
If this value is set to 1, an event from the Plug and Play (PnP) subsystem suspended the queue from processing requests.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFIoQueue::ConfigureRequestDispatching, IWDFIoQueue::RetrieveNextRequest, IWDFIoRequest::ForwardToIoQueue, WDF_IO_QUEUE_DISPATCH_TYPE


WDF_PNP_CAPABILITY

The WDF_PNP_CAPABILITY enumeration contains values that identify Plug and Play (PnP) capabilities for a device.

typedef enum _WDF_PNP_CAPABILITY {
  WdfPnpCapInvalid  = 0,
  WdfPnpCapLockSupported  = 1,
  WdfPnpCapEjectSupported  = 2,
  WdfPnpCapRemovable  = 3,
  WdfPnpCapDockDevice  = 4,
  WdfPnpCapSurpriseRemovalOk  = 5,
  WdfPnpCapNoDisplayInUI  = 6,
  WdfPnpCapMaximum
} WDF_PNP_CAPABILITY;

Values

WdfPnpCapInvalid
Indicates whether PnP capabilities of the device are invalid.
WdfPnpCapLockSupported
Indicates whether the device can be locked in its slot to prevent ejection. (Setting this capability disables ejecting a device from its slot and does not disable ejecting media from a device.)
WdfPnpCapEjectSupported
Indicates whether the device can be ejected from its slot. (Setting this capability enables ejecting a device from its slot and does not enable ejecting media from a device.)
WdfPnpCapRemovable
Indicates whether the device can be removed while the computer is running. If WdfPnpCapRemovable is set to WdfTrue and WdfPnpCapSurpriseRemovalOk is set to WdfFalse, users should use the system's Unplug or Eject Hardware application.
WdfPnpCapDockDevice
Indicates whether the device is a docking station.
WdfPnpCapSurpriseRemovalOk
Indicates whether users can remove the device without using the computer's Unplug or Eject Hardware application.
WdfPnpCapNoDisplayInUI
Indicates whether the device can be hidden (not displayed) in Device Manager.
WdfPnpCapMaximum
Valid enumeration values were exceeded.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A UMDF driver supplies one of the values of WDF_PNP_CAPABILITY to the IWDFDeviceInitialize::GetPnpCapability or IWDFDeviceInitialize::SetPnpCapability method to identify the PnP capability to retrieve or set status for.

See Also

IWDFDeviceInitialize::GetPnpCapability, IWDFDeviceInitialize::SetPnpCapability


WDF_PNP_STATE

The WDF_PNP_STATE enumeration contains values that identify the status of Plug and Play (PnP) for a device.

typedef enum _WDF_PNP_STATE {
  WdfPnpStateInvalid  = 0,
  WdfPnpStateDisabled  = 1,
  WdfPnpStateFailed  = 2,
  WdfPnpStateRemoved  = 3,
  WdfPnpStateResourcesChanged  = 4,
  WdfPnpStateDontDisplayInUI  = 5,
  WdfPnpStateNotDisableable  = 6,
  WdfPnpStateMaximum
} WDF_PNP_STATE;

Values

WdfPnpStateInvalid
The PnP state for the device is invalid.
WdfPnpStateDisabled
The device is disabled.
WdfPnpStateFailed
The device is present but has failed.
WdfPnpStateRemoved
The device has been removed.
WdfPnpStateResourcesChanged
The device's resource requirements have changed.
WdfPnpStateDontDisplayInUI
The device is hidden (not displayed) in Device Manager.
WdfPnpStateNotDisableable
The device cannot be disabled.
WdfPnpStateMaximum
Valid enumeration values were exceeded.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A UMDF driver supplies one of the values of WDF_PNP_STATE to the IWDFDevice::GetPnpState or IWDFDevice::SetPnpState method to identify the PnP property to retrieve or set status for.

See Also

IWDFDevice::GetPnpState, IWDFDevice::SetPnpState


WDF_POWER_DEVICE_STATE

The WDF_POWER_DEVICE_STATE enumeration contains values that identify the power state that a device might support.

typedef enum _WDF_POWER_DEVICE_STATE {
  WdfPowerDeviceInvalid  = 0,
  WdfPowerDeviceD0  = 1,
  WdfPowerDeviceD1  = 2,
  WdfPowerDeviceD2  = 3,
  WdfPowerDeviceD3  = 4,
  WdfPowerDeviceD3Final  = 5,
  WdfPowerDevicePrepareForHibernation  = 6,
  WdfPowerDeviceMaximum
} WDF_POWER_DEVICE_STATE, *PWDF_POWER_DEVICE_STATE;

Values

WdfPowerDeviceInvalid
The device power state is invalid or unknown.
WdfPowerDeviceD0
The device supports the D0 device power state.
WdfPowerDeviceD1
The device supports the D1 device power state.
WdfPowerDeviceD2
The device supports the D2 device power state.
WdfPowerDeviceD3
The device supports the D3 device power state.
WdfPowerDeviceD3Final
The final time that the device enters the D3 device power state. Typically, this value means that the computer's power is being turned off or the device is being removed from the computer. The device might have been already removed.
WdfPowerDevicePrepareForHibernation
The device supports hibernation files, and the computer is ready to hibernate by entering system state S4. The driver must not turn off the device.
WdfPowerDeviceMaximum
Valid enumeration values were exceeded.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

The framework supplies one of the values of WDF_POWER_DEVICE_STATE to the IPnpCallback::OnD0Entry or IPnpCallback::OnD0Exit method to notify the UMDF driver about the power state of the device.

See Also

IPnpCallback::OnD0Entry, IPnpCallback::OnD0Exit


WDF_PROPERTY_STORE_DISPOSITION

The WDF_PROPERTY_STORE_DISPOSITION enumeration contains values that identify whether the device property store is created or already exists in a call to the IWDFDevice::RetrieveDevicePropertyStore or IWDFDeviceInitialize::RetrieveDevicePropertyStore method.

typedef enum _WDF_PROPERTY_STORE_DISPOSITION {
  CreatedNewStore = 0x01,
  OpenedExistingStore = 0x02
} WDF_PROPERTY_STORE_DISPOSITION;

Values

CreatedNewStore
The device property store is created.
OpenedExistingStore
The device property store already exists.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice::RetrieveDevicePropertyStore, IWDFDeviceInitialize::RetrieveDevicePropertyStore


WDF_PROPERTY_STORE_RETRIEVE_FLAGS

The WDF_PROPERTY_STORE_RETRIEVE_FLAGS enumeration contains values that identify how to retrieve a device property store by using the IWDFDevice::RetrieveDevicePropertyStore or IWDFDeviceInitialize::RetrieveDevicePropertyStore method.

typedef enum _WDF_PROPERTY_STORE_RETRIEVE_FLAGS {
  WdfPropertyStoreNormal = 0x00,
  WdfPropertyStoreCreateIfMissing = 0x01
} WDF_PROPERTY_STORE_RETRIEVE_FLAGS;

Values

WdfPropertyStoreNormal
Do not create the device property store if it does not exist.
WdfPropertyStoreCreateIfMissing
Create the device property store if necessary.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IWDFDevice::RetrieveDevicePropertyStore, IWDFDeviceInitialize::RetrieveDevicePropertyStore


WDF_REQUEST_STOP_ACTION_FLAGS

The WDF_REQUEST_STOP_ACTION_FLAGS enumeration contains values that identify the state of a stop action request in a call to the driver's IQueueCallbackIoStop::OnIoStop method.

typedef enum _WDF_REQUEST_STOP_ACTION_FLAGS {
  WdfRequestStopActionInvalid = 0x00000000,
  WdfRequestStopActionSuspend = 0x00000001,
  WdfRequestStopActionPurge = 0x00000002,
  WdfRequestStopRequestCancelable = 0x10000000
} WDF_REQUEST_STOP_ACTION_FLAGS;

Values

WdfRequestStopActionInvalid
If this value is set to 1, the request is invalid.
WdfRequestStopActionSuspend
If this value is set to 1, the device is suspended.
WdfRequestStopActionPurge
If this value is set to 1, the device and queue are removed.
WdfRequestStopRequestCancelable
If this value is set to 1, the request is marked as cancelable.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IQueueCallbackIoStop::OnIoStop


WDF_REQUEST_TYPE

The WDF_REQUEST_TYPE enumeration contains values that identify a type of request object and why the request is sent to a driver.

typedef enum _WDF_REQUEST_TYPE {
  WdfRequestUndefined  = 0,
  WdfRequestCreate  = 1,
  WdfRequestCleanup  = 2,
  WdfRequestRead  = 3,
  WdfRequestWrite  = 4,
  WdfRequestDeviceIoControl  = 5,
  WdfRequestClose  = 6,
  WdfRequestUsb  = 7,
  WdfRequestOther  = 8,
  WdfRequestInternalIoctl  = 9,
  WdfRequestTypeNoFormat  = 10,
  WdfRequestMaximum
} WDF_REQUEST_TYPE, *PWDF_REQUEST_TYPE;

Values

WdfRequestUndefined
The type of the request object is undefined.
WdfRequestCreate
The request object is sent because an application opens the device through the Microsoft Win32 CreateFile function. The framework creates a file object (IWDFFile) and calls the driver's IQueueCallbackCreate::OnCreateFile method to notify the driver. The newly created file object represents the HANDLE that is returned by the Win32 CreateFile. All further operations on this handle, like calls to the Win32 ReadFile function and the DeviceIoControl function, are sent to this new file object.
WdfRequestCleanup
The request object is sent when the application calls the Win32 CloseHandle function, which closes the last handle on the file object that is associated with the target device. The framework calls the driver's IFileCallbackCleanup::OnCleanupFile method to notify the driver.
WdfRequestRead
The request object is sent when the application calls the Win32 ReadFile or ReadFileEx function on the file object that is associated with the target device. The framework calls the driver's IQueueCallbackRead::OnRead method to notify the driver.
WdfRequestWrite
The request object is sent when the application calls the Win32 WriteFile or WriteFileEx function on the file object that is associated with the target device. The framework calls the driver's IQueueCallbackWrite::OnWrite method to notify the driver.
WdfRequestDeviceIoControl
The request object is sent when the application calls the Win32 DeviceIoControl function on the file object that is associated with the target device. The framework calls the driver's IQueueCallbackDeviceIoControl::OnDeviceIoControl method to notify the driver.
WdfRequestClose
The request object is sent when all of the references on the file object that is associated with the target device are closed. Note that this value is different than the WdfRequestCleanup request type, where the framework might hold outstanding references to the file object to ensure that any pending requests are completed even after the cleanup request is received. A client application can close the handle to a device while there are pending requests on it. The close request is not sent until all pending I/Os are completed or canceled. The framework calls the driver's IFileCallbackClose::OnCloseFile method to notify the driver.
WdfRequestUsb
The request object is sent to a USB port.
WdfRequestOther
The type of request object is something other than the preceding types.
WdfRequestInternalIoctl
The request object is sent as internal I/O.
WdfRequestTypeNoFormat
The request object is not formatted.
WdfRequestMaximum
The maximum value for the enumeration is exceeded.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

In the current version of the UMDF, the WdfRequestCleanup value is not supported; all other request types are supported.

See Also

IFileCallbackCleanup::OnCleanupFile, IFileCallbackClose::OnCloseFile, IQueueCallbackCreate::OnCreateFile, IQueueCallbackDeviceIoControl::OnDeviceIoControl, IQueueCallbackRead::OnRead, IQueueCallbackWrite::OnWrite, IWDFFile


WDF_USB_REQUEST_TYPE

The WDF_USB_REQUEST_TYPE enumeration contains values that identify a type of USB request object.

typedef enum _WDF_USB_REQUEST_TYPE {
  WdfUsbRequestTypeInvalid  = 0,
  WdfUsbRequestTypeNoFormat,
  WdfUsbRequestTypeDeviceControlTransfer,
  WdfUsbRequestTypePipeWrite,
  WdfUsbRequestTypePipeRead
} WDF_USB_REQUEST_TYPE, *PWDF_USB_REQUEST_TYPE;

Values

WdfUsbRequestTypeInvalid
The type of the request object is invalid.
WdfUsbRequestTypeNoFormat
The request object is not formatted.
WdfUsbRequestTypeDeviceControlTransfer
The request object is sent when the application calls the Win32 DeviceIoControl function on the file object that is associated with the target device.
WdfUsbRequestTypePipeWrite
The request object is sent when the application calls the Win32 WriteFile or WriteFileEx function on the file object that is associated with the target device.
WdfUsbRequestTypePipeRead
The request object is sent when the application calls the Win32 ReadFile or ReadFileEx function on the file object that is associated with the target device.

Headers

Declared in Wudfusb.h. Include Wudfusb.h.


WDFMEMORY_OFFSET

The WDFMEMORY_OFFSET structure describes the location and size of information that is accessed within a memory block.

typedef struct _WDFMEMORY_OFFSET {
  ULONG_PTR BufferOffset;
  ULONG_PTR BufferLength;
} WDFMEMORY_OFFSET, *PWDFMEMORY_OFFSET;

Members

BufferOffset
The offset, in bytes, into the memory block where information is first accessed.
BufferLength
The size, in bytes, of the information that is accessed in the memory block.

Headers

Declared in Wudfddi.h. Include Wudfddi.h.

Comments

A UMDF driver supplies a pointer to a WDFMEMORY_OFFSET structure to the IWDFMemory::CopyFromMemory method to describe information to copy from a memory block.

See Also

IWDFMemory::CopyFromMemory


Windows Driver Kit

Legal Information

Windows Driver Kit

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Portions of the TCP offload technology in Microsoft's products are used under license from Alacritech and may be covered by one or more of the following U.S. Patents: 6,226,680; 6,247,060; 6,334,153; 6,389,479; 6,393,487; 6,427,171; 6,427,173; 6,434,620; 6,591,302; 6,658,480; 6,697,868; 6,751,665; 6,757,746. Microsoft does not have a license under the Alacritech patents to implement the claimed offloading functionality in hardware. It is expressly agreed and acknowledged that no license is granted under Alacritech's patents expressly, by implication, by exhaustion or otherwise, to use or sell the TCP offload technology in combination with any non-licensed hardware that is specially designed to practice the Alacritech patents. For more information, see the TCP Chimney Licensing page on the WHDC Web site.

© 1985 − 2006 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, Authenticode, BackOffice, Developer Studio, Direct3D, DirectDraw, DirectInput, DirectMusic, DirectPlay, DirectShow, DirectSound, DirectX, DirectAnimation, JScript, Microsoft Press, MSDN, MS-DOS, MSN, Natural, OpenType, Visual Basic, Visual C++, Visual Studio, Win32, Win32s, Windows, Windows NT, Windows Server, and XENIX are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Send feedback on this topic.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    • Remedy: Rerun the Windows Driver Kit Setup and install all documentation components.

  • The destination topic is not part of the currently-selected subset.

    • Remedy: Choose a different subset from the Active Subset list.

Send feedback on this broken link.