IWDFDevice::CreateRequest method (wudfddi.h)

Article
10/21/2021

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The CreateRequest method creates an unformatted request object.

Syntax

HRESULT CreateRequest(
  [in, optional] IUnknown      *pCallbackInterface,
  [in, optional] IWDFObject    *pParentObject,
  [out]          IWDFIoRequest **ppRequest
);

Parameters

[in, optional] pCallbackInterface

A pointer to the IUnknown interface that the framework uses to determine the object-related event callback functions that the driver subscribes to on the newly created request object. This parameter is optional. The driver can pass NULL if the driver does not require notification. If the driver passes a valid pointer, the framework will call QueryInterface on the IUnknown interface for the IObjectCleanup interface. If the framework obtains the driver's IObjectCleanup interface, the framework can subsequently call the driver's IObjectCleanup::OnCleanup method to notify the driver that the request object is cleaned up.

[in, optional] 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.

[out] 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.

Remarks

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:

If a driver calls CreateRequest to create a request object, it must not call IWDFIoRequest::Complete for the request object. Instead, the driver must call IWDFObject::DeleteWdfObject when it has finished using the request object. For more information, see Completing I/O Requests.

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.

Examples

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;

    IWDFFile *pTargetFile = NULL;

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

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

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

    return hr;
}

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.5
Header	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll