IWDFIoRequest::Send 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 Send method sends a request to the specified I/O target.

Syntax

HRESULT Send(
  [in] IWDFIoTarget *pIoTarget,
  [in] ULONG        Flags,
  [in] LONGLONG     Timeout
);

Parameters

[in] pIoTarget

A pointer to the IWDFIoTarget interface for the I/O target object, which typically represents a lower driver in the stack.

[in] Flags

A valid bitwise OR of WDF_REQUEST_SEND_OPTIONS_FLAGS-typed flags.

[in] Timeout

The amount of time, in system time units (100-nanosecond intervals), that can elapse before the framework automatically cancels the I/O request.

If the value is negative, the expiration time is relative to the current system time.
If the value is positive, the expiration time is specified as an absolute time (which is relative to January 1, 1601).
If the value is zero, the framework does not time out the request.

Relative expiration times are not affected by any changes to the system time that might occur within the specified time-out period. Absolute expiration times reflect system time changes.

Return value

Send returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Note that the return value represents the status of the Send method's attempt to send the I/O request to the I/O target. The return value does not represent the completion status of the I/O request. Your driver must use the IWDFRequestCompletionParams interface to obtain the I/O request's completion status.

Remarks

If Send returns an error code, the driver should typically complete the request with the error code that Send returned, as the code in the following Example section shows.

If your driver sets the WDF_REQUEST_SEND_OPTION_SYNCHRONOUS flag in the Flags parameter, and if Send successfully sends the I/O request to the I/O target, Send returns after the I/O target completes the I/O request. In this case, Send returns S_OK and the driver can immediately call IWDFIoRequest::GetCompletionParams to obtain the IWDFRequestCompletionParams interface. The code example at IWDFIoRequest::GetCompletionParams shows a call to Send with the WDF_REQUEST_SEND_OPTION_SYNCHRONOUS flag set.

If your driver does not set the WDF_REQUEST_SEND_OPTION_SYNCHRONOUS flag, and if Send successfully sends the I/O request to the I/O target, Send returns S_OK while the I/O target is still processing the I/O request asynchronously. In this case, the driver provides an IRequestCallbackRequestCompletion::OnCompletion callback function that the framework calls after the I/O target completes the I/O request. Typically, the OnCompletion callback function calls IWDFIoRequest::GetCompletionParams. The code example in the following Example section shows a call to Send without the WDF_REQUEST_SEND_OPTION_SYNCHRONOUS flag.

A driver cannot call Send to send an I/O request to a USB pipe, if the driver has configured a continuous reader for the pipe.

Examples

The following code example forwards a request to a device's I/O target.

    IWDFIoRequest* FxRequest;

    //
    // Set the completion callback.
    // When the lower request is completed, the driver is 
    // notified through the completion callback. 
    //

    IRequestCallbackRequestCompletion *completionCallback = 
        QueryIRequestCallbackRequestCompletion();
 
    FxRequest->SetCompletionCallback(
                                     completionCallback,
                                     NULL  //pContext
                                     );

    completionCallback->Release();
 
    //
    // Format the I/O request.  
 
    FxRequest->FormatUsingCurrentType( );

    //
    // Send down the request.
    //
    HRESULT hrSend = S_OK;
 
    hrSend = FxRequest->Send(
                             m_FxIoTarget,
                             0, // Asynchronous
                             0  // No time-out
                             );
 
    if (S_OK != hrSend) {
        //
        // If the send failed, the driver must complete the 
        // request with the failure.
        FxRequest->CompleteWithInformation(hrSend, 0);
    }

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