WdfRequestRetrieveInputMemory 函数 (wdfrequest.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfRequestRetrieveInputMemory 方法检索表示 I/O 请求输入缓冲区的框架内存对象的句柄。

语法

NTSTATUS WdfRequestRetrieveInputMemory(
  [in]  WDFREQUEST Request,
  [out] WDFMEMORY  *Memory
);

参数

[in] Request

框架请求对象的句柄。

[out] Memory

指向接收框架内存对象的句柄的位置的指针。

返回值

如果操作成功，WdfRequestRetrieveInputMemory 将返回STATUS_SUCCESS。 否则，此方法可能会返回以下值之一：

返回代码 说明
STATUS_INVALID_PARAMETER
 输入参数无效。
STATUS_INVALID_DEVICE_REQUEST
 请求类型无效，或者请求 既不使用缓冲 I/O，也不使用直接 I/O。 有关用于访问数据缓冲区的受支持方法的详细信息，请参阅以下“备注”部分。
STATUS_INTERNAL_ERROR
 请求已完成。
STATUS_BUFFER_TOO_SMALL
 输入缓冲区的长度为零。
STATUS_INSUFFICIENT_RESOURCES
 内存不足。
 

此方法还可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

请求的输入缓冲区包含由请求发起方提供的信息，例如要写入磁盘的数据。 驱动程序可以调用 WdfRequestRetrieveInputMemory 来获取写入请求或设备 I/O 控制请求的输入缓冲区，但不能为读取请求 (获取输入缓冲区，因为读取请求不提供输入数据) 。

WdfRequestRetrieveInputMemory 方法检索使用缓冲 I/O 方法或直接 I/O 方法访问数据缓冲区的 I/O 请求的输入缓冲区。 如果请求的 I/O 控制代码 IRP_MJ_INTERNAL_DEVICE_CONTROL，或者请求来自另一个内核模式驱动程序， 则 WdfRequestRetrieveInputMemory 还支持 既不使用缓冲 I/O，也不使用直接 I/O 的 I/O 请求。

如果 WdfRequestRetrieveInputMemory 返回STATUS_SUCCESS，驱动程序将接收表示输入缓冲区的框架内存对象的句柄。 若要访问缓冲区，驱动程序必须调用 WdfMemoryGetBuffer。

驱动程序可以访问检索到的框架内存对象，直到它完成 Request 参数表示的 I/O 请求。

驱动程序可以调用 WdfRequestRetrieveInputBuffer，以检索缓冲区的地址和长度，而不是调用 WdfRequestRetrieveInputMemory。

有关 WdfRequestRetrieveInputMemory 的详细信息，请参阅 访问 Framework-Based 驱动程序中的数据缓冲区。

示例

下面的代码示例演示 EvtIoWrite 回调函数如何获取表示写入请求输入缓冲区的框架内存对象的句柄。 然后，该示例格式化写入请求并将其发送到 USB I/O 目标。

VOID 
MyEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    NTSTATUS  status;
    WDFUSBPIPE  pipe;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    //
    // The driver previously stored a pipe handle in 
    // the device object's context space.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkWritePipe;

    //
    // Get input memory.
    //
    status = WdfRequestRetrieveInputMemory(
                                           Request,
                                           &reqMemory
                                           );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }

    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForWrite(
                                          pipe,
                                          Request,
                                          reqMemory,
                                          NULL
                                          );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestWriteCompletionRoutine,
                                   pipe
                                   );

    //
    // Send the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    //
    // Complete the request now if an error occurred.
    //
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfrequest.h (包括 Wdf.h)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL <=DISPATCH_LEVEL
DDI 符合性规则 DriverCreate (kmdf) ， InputBufferAPI (kmdf) ， InvalidReqAccess (kmdf) ， InvalidReqAccessLocal (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf) ， MemAfterReqCompletedIntIoctl (kmdf) 、 MemAfterReqCompletedIntIoctlA (kmdf) 、 MemAfterReqCompletedIoctl (kmdf) 、 MemAfterReqCompletedIoctlA (kmdf) ， MemAfterReqCompletedRead (kmdf) ， MemAfterReqCompletedWrite (kmdf) ， MemAfterReqCompletedWriteA (kmdf)

另请参阅

WdfMemoryGetBuffer

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory