- Using COM to Develop UMDF Drivers (Part 1 of 2)
- Returns from a COM Method (<tt>HRESULT</tt> Type)/Using UMDF COM Objects
- Obtaining an Interface on a UMDF Object
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Returns from a COM Method (HRESULT Type)
Before we examine how to use COM objects, let's look at the return from a COM method. COM methods often return a 32-bit type called an HRESULT. It's similar to the NTSTATUS type that the Kernel Mode Driver routines use as a return value, and it's used in much the same way. Figure 3 shows the layout of an HRESULT.
){kind=link}
)
Figure 3 HRESULT layout.
The HRESULT type has three fields:
- Severity. Essentially a Boolean value that indicates success or failure.
- Facility. You can usually ignore this field.
- Return code. Provides a more detailed description of the results.
As with NTSTATUS values, it's rarely necessary to parse the HRESULT and examine the individual fields. Standard HRESULT values are defined in header files and described on method reference pages. By convention, success codes are assigned names that begin with S_ and failure codes with E_. For example, S_OK is the standard HRESULT value for simple success.
Using UMDF COM Objects
A process that uses a COM object is known as a COM client. Both UMDF drivers and the UMDF runtime function as COM clients. UMDF drivers interact with the UMDF runtime by using UMDF-provided COM objects. For example, the UMDF device object represents the device, and drivers can use the object for tasks such as setting or retrieving the device's Plug-and-Play state.
The UMDF runtime interacts with drivers through the drive-provided COM-based callback objects. For example, a driver can create one or more queue callback objects to handle I/O requests. The UMDF runtime uses those objects to pass requests to the driver.
After you get a pointer to an interface, you can call the interface methods by using the same syntax that's used for a pointer to a C++ method. For example, if pWdfRequest is a pointer to an IWDFIoRequest interface, the following code is an example of how to invoke the interface's SEND method:
HRESULT hr; hr = pWdfRequest->Send(m_pIUsbTargetDevice, WDR_REQUEST_SEND_OPTION_SYNCHRONOUS, 0);
The method's return value is an HRESULT, a typical return type for COM methods.