WdfRequestCreate method

[Applies to KMDF and UMDF]

The WdfRequestCreate method creates an empty framework request object.

Syntax

NTSTATUS WdfRequestCreate(
  [in, optional]  PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in, optional]  WDFIOTARGET IoTarget,
  [out]           WDFREQUEST *Request
);

Parameters

RequestAttributes [in, optional]

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that specifies object attributes for the request object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

IoTarget [in, optional]

A handle to a framework I/O target object. This parameter is optional and can be NULL. If non-NULL, WdfRequestCreate verifies that the driver can eventually send the request to the specified I/O target.

Request [out]

A pointer to a location that receives a handle to a framework request object.

Return value

WdfRequestCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

For a list of additional return values, see Framework Object Creation Errors.

This method might also return other NTSTATUS values.

Remarks

A framework-based driver can call WdfRequestCreate to create a new request that the driver subsequently passes to other framework functions for initialization. For example, a driver for a USB device might call WdfUsbTargetPipeFormatRequestForRead to format a new read request.

A framework-based driver that communicates with WDM drivers might specify the contents of a request by calling WdfRequestCreateFromIrp.

If a driver calls WdfRequestCreate to create a request object, it must not call WdfRequestComplete for the request object. Instead, the driver must call WdfObjectDelete when it has finished using the request object. For more information, see Completing I/O Requests.

By default, the new request object's parent is the framework driver object that the WdfDriverCreate method created. You can use the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure to specify a different parent. The framework deletes the request object when it deletes the parent object. If your driver does not change the default parent, the driver should delete the request object when it has finished using the object; otherwise, the request object will remain until the I/O manager unloads your driver.

For more information about calling WdfRequestCreate, see Creating Framework Request Objects.

Examples

The following code example creates an I/O target object, initializes a WDF_OBJECT_ATTRIBUTES structure, and calls WdfRequestCreate. The new request object's parent is the I/O target object.

WDF_OBJECT_ATTRIBUTES  attributes;
WDFREQUEST newRequest;
WDFIOTARGET ioTarget;
...
status = WdfIoTargetCreate(
                           Device,
                           WDF_NO_OBJECT_ATTRIBUTES,
                           &ioTarget
                           );
  ...
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = ioTarget;

status = WdfRequestCreate(
                          &attributes,
                          ioTarget,
                          &newRequest
                          );

if (!NT_SUCCESS(status)) {
    return status;
}

Requirements

See also

WdfDeviceInitSetRequestAttributes

WdfDriverCreate

WdfRequestCreateFromIrp

WdfRequestReuse

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

Send comments about this topic to Microsoft