WdfRequestCompleteWithInformation function (wdfrequest.h)
[Applies to KMDF and UMDF]
The WdfRequestCompleteWithInformation method stores completion information and then completes a specified I/O request with a supplied completion status.
Syntax
void WdfRequestCompleteWithInformation(
[in] WDFREQUEST Request,
[in] NTSTATUS Status,
[in] ULONG_PTR Information
);
Parameters
[in] Request
A handle to the request object.
[in] Status
An NTSTATUS value that represents the completion status of the request. Valid status values include, but are not limited to, the following:
STATUS_SUCCESS
The driver successfully completed the request.
STATUS_CANCELLED
The driver canceled the request.
STATUS_UNSUCCESSFUL
The driver encountered an error while processing the request.
[in] Information
A ULONG_PTR that is set to a request-dependent value. For example, on successful completion of a transfer request, this is set to the number of bytes transferred. This field is not extensible by the driver.
Return value
None
Remarks
A bug check occurs if the driver supplies an invalid object handle.
For read, write and IOCTL requests, it is necessary for the driver to call WdfRequestCompleteWithInformation
For a non-data transfer request, calling WdfRequestComplete instead is an option.
Calling WdfRequestCompleteWithInformation is equivalent to calling WdfRequestSetInformation and then calling WdfRequestComplete.
After a call to WdfRequestCompleteWithInformation returns, the request handle is no longer valid unless the driver has called WdfObjectReference to add one or more additional reference counts to the request object. Note that after WdfRequestCompleteWithInformation returns, the driver must not attempt to access the associated WDM IRP structure, even if it has called WdfObjectReference.
When your driver calls WdfRequestCompleteWithInformation, the framework supplies a default value that the system uses to boost the run-time priority of the thread that requested the I/O operation. For information about default priority boost values, see Specifying Priority Boosts When Completing I/O Requests. Your driver can call WdfRequestCompleteWithPriorityBoost to override the default priority boost value.
For more information about calling WdfRequestCompleteWithInformation, see Completing I/O Requests.
For a code example that shows how to use WdfRequestCompleteWithInformation to retrieve the number of bytes copied, see the VirtualSerial2 driver sample.
Examples
The following code example shows how a driver for a USB device might call WdfRequestCompleteWithInformation in a CompletionRoutine callback function .
VOID
EvtRequestReadCompletionRoutine(
IN WDFREQUEST Request,
IN WDFIOTARGET Target,
PWDF_REQUEST_COMPLETION_PARAMS CompletionParams,
IN WDFCONTEXT Context
)
{
NTSTATUS status;
size_t bytesRead = 0;
PWDF_USB_REQUEST_COMPLETION_PARAMS usbCompletionParams;
UNREFERENCED_PARAMETER(Target);
UNREFERENCED_PARAMETER(Context);
status = CompletionParams->IoStatus.Status;
usbCompletionParams = CompletionParams->Parameters.Usb.Completion;
bytesRead = usbCompletionParams->Parameters.PipeRead.Length;
if (NT_SUCCESS(status)){
TraceEvents(
TRACE_LEVEL_INFORMATION,
DBG_READ,
"Number of bytes read: %I64d\n",
(INT64)bytesRead
);
} else {
TraceEvents(
TRACE_LEVEL_ERROR,
DBG_READ,
"Read failed - request status 0x%x UsbdStatus 0x%x\n",
status,
usbCompletionParams->UsbdStatus
);
}
WdfRequestCompleteWithInformation(
Request,
status,
bytesRead
);
return;
}
Requirements
See also
WDF_USB_REQUEST_COMPLETION_PARAMS