Expand Minimize

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:

Return codeDescription
STATUS_INVALID_PARAMETER

An input parameter is invalid.

STATUS_INSUFFICIENT_RESOURCES

There are insufficient system resources to complete the operation.

STATUS_REQUEST_NOT_ACCEPTED

The request's array of I/O stack locations is not large enough to allow the driver to send the request to the specified I/O target.

 

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

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfrequest.h (include Wdf.h)

Library

Wdf01000.sys (KMDF);
WUDFx02000.dll (UMDF)

IRQL

<=DISPATCH_LEVEL

DDI compliance rules

DriverCreate, InvalidReqAccessLocal, KmdfIrql, KmdfIrql2, ReqDelete, RequestForUrbXrb, RequestSendAndForgetNoFormatting2

See also

WdfDeviceInitSetRequestAttributes
WdfDriverCreate
WdfRequestCreateFromIrp
WdfRequestReuse
WDF_OBJECT_ATTRIBUTES
WDF_OBJECT_ATTRIBUTES_INIT

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft