Поделиться через

Функция WdfIoTargetSendReadSynchronously (wdfiotarget.h)

  • Статья

[Применимо к KMDF и UMDF]

Метод WdfIoTargetSendReadSynchronous создает запрос на чтение и отправляет его в целевой объект ввода-вывода синхронно.

Синтаксис

NTSTATUS WdfIoTargetSendReadSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OutputBuffer,
  [in, optional]  PLONGLONG                 DeviceOffset,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesRead
);

Параметры

[in] IoTarget

Дескриптор локального или удаленного целевого объекта ввода-вывода, полученного из предыдущего вызова WdfDeviceGetIoTarget или WdfIoTargetCreate или из метода, который предоставляет специализированный целевой объект ввода-вывода.

[in, optional] Request

Дескриптор объекта запроса платформы. Этот параметр является необязательным и может быть null. Дополнительные сведения об этом параметре см. в следующем разделе "Примечания".

[in, optional] OutputBuffer

Указатель на выделенную вызывающим WDF_MEMORY_DESCRIPTOR структуру, описывающую буфер, который будет получать данные от устройства. Этот параметр является необязательным и может быть NULL. Дополнительные сведения об этом параметре см. в следующем разделе "Примечания".

[in, optional] DeviceOffset

Указатель на расположение, указывающее начальное смещение для передачи. Целевой объект ввода-вывода (т. е. следующий драйвер) определяет, как использовать это значение. Например, драйверы в стеке драйверов диска могут указывать смещение с начала диска. Целевой объект ввода-вывода получает эти сведения в элементе WDF_REQUEST_PARAMETERSWDF_REQUEST_PARAMETERSParameters.Read.DeviceOff set. Этот указатель является необязательным. Большинство драйверов задают этот указатель на NULL.

[in, optional] RequestOptions

Указатель на структуру, выделенную вызывающим объектом, WDF_REQUEST_SEND_OPTIONS, которая задает параметры запроса на чтение. Этот указатель необязателен и может быть null.

[out, optional] BytesRead

Указатель на расположение, которое получает число операций чтения байтов, если операция выполнена успешно. Этот указатель необязателен и может быть null.

Возвращаемое значение

Если операция выполнена успешно, WdfIoTargetSendReadSynchronous возвращается после завершения запроса ввода-вывода, а возвращаемое значение — значение состояния завершения запроса. В противном случае этот метод может вернуть одно из следующих значений:

Возвращаемый код Описание
STATUS_INVALID_PARAMETER
 Обнаружен недопустимый параметр.
STATUS_INFO_LENGTH_MISMATCH
 Размер структуры WDF_REQUEST_SEND_OPTIONS, на которую указал параметр RequestOptions, был неверным.
STATUS_INVALID_DEVICE_REQUEST
 Запрос ввода-вывода уже был помещен в очередь в целевой объект ввода-вывода.
STATUS_INSUFFICIENT_RESOURCES
 Платформа не могла выделить системные ресурсы (обычно память).
STATUS_IO_TIMEOUT
 Драйвер предоставил значение времени ожидания и запрос не завершился в течение выделенного времени.
STATUS_REQUEST_NOT_ACCEPTED
 Пакет запроса ввода-вывода (IRP), который представляет параметр запроса , не предоставляет достаточно IO_STACK_LOCATION структур, чтобы разрешить драйверу пересылать запрос.
 

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Используйте метод WdfIoTargetSendReadSynchronous для синхронной отправки запросов на чтение. Чтобы асинхронно отправлять запросы на чтение, используйте метод WdfIoTargetFormatRequestForRead, а затем метод WdfRequestSend.

WdfIoTargetSendReadSynchronous не возвращается до завершения запроса, если драйвер не предоставляет значение времени ожидания в структуре WDF_REQUEST_SEND_OPTIONS requestOptions или если не обнаружена ошибка.

Вы можете пересылать запрос ввода-вывода, полученный драйвером в очереди ввода-вывода, или создать и отправить новый запрос. В любом случае для платформы требуется объект запроса и некоторое пространство буфера.

Чтобы перенаправить запрос ввода-вывода, полученный драйвером в очереди ввода-вывода:

  1. Укажите дескриптор полученного запроса для параметра запроса .
  2. Используйте выходной буфер полученного запроса для параметра WdfIoTargetSendReadSynchronous метода OutputBuffer.

    Драйвер должен вызвать WdfRequestRetrieveOutputMemory, чтобы получить дескриптор объекта памяти платформы, представляющего выходной буфер запроса. Затем драйвер должен поместить этот дескриптор в структуру WDF_MEMORY_DESCRIPTOR, которую драйвер предоставляет для параметра OutputBuffer.

Дополнительные сведения о переадресации запроса ввода-вывода см. в запросах на пересылку операций ввода-вывода.

Драйверы часто делят полученные запросы ввода-вывода на небольшие запросы, которые они отправляют в целевой объект ввода-вывода, поэтому ваш драйвер может создавать новые запросы.

Чтобы создать новый запрос ввода-вывода:

  1. Укажите дескриптор запроса NULL для параметра WdfIoTargetSendReadSynchronous метода request или создайте новый объект запроса и предоставьте его дескриптор:
    • Если вы предоставляете дескриптор запроса NULL, платформа использует внутренний объект запроса. Этот метод прост в использовании, но драйвер не может отменить запрос.
    • При вызове WdfRequestCreate для создания одного или нескольких объектов запроса можно повторно использовать эти объекты запроса, вызвав WdfRequestReuse. Этот метод позволяет драйвера EvtDriverDeviceAdd функцию обратного вызова для предварительного размещения объектов запросов для устройства. Кроме того, другой поток драйвера может вызывать WdfRequestCancelSentRequest, чтобы отменить запрос при необходимости.

    Драйвер может указать параметр, отличный отNULLRequestOptions, предоставляет ли драйвер параметрNULL или параметр NULLRequest. Например, можно использовать параметр RequestOptions для указания значения времени ожидания.

  2. Предоставьте буферное пространство для параметра метода OutputBuffer WdfIoTargetSendReadSynchronous.

    Драйвер может указать это пространство буфера в качестве локально выделенного буфера, в качестве дескриптора WDFMEMORY или в виде списка дескрипторов памяти (MDL). Вы можете использовать любой метод, наиболее удобный.

    При необходимости платформа преобразует описание буфера в то, что правильно для метода целевого объекта ввода-вывода для доступа к буферам данных.

    Доступны следующие методы указания пространства буфера:

    • Укажите локальный буфер.

      Так как WdfIoTargetSendReadSynchronous обрабатывает запросы ввода-вывода синхронно, драйвер может создавать буферы запросов, которые являются локальными для вызывающей подпрограммы, как показано в следующем примере кода.

      WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
MY_BUFFER_TYPE  MyBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                  (PVOID) &MyBuffer,
                                  sizeof(MyBuffer));
    • Укажите дескриптор WDFMEMORY.

      Вызов WdfMemoryCreate или WdfMemoryCreatePreallocated для получения дескриптора в управляемой платформой памяти, как показано в следующем примере кода.

      WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&MemoryDescriptor,
                                  MemoryHandle,
                                  NULL);

      Кроме того, драйвер может вызывать WdfRequestRetrieveOutputMemory для получения дескриптора объекта памяти платформы, представляющего выходной буфер запроса ввода-вывода, если требуется передать содержимое этого буфера целевому объекту ввода-вывода. Драйвер не должен завершить полученный запрос ввода-вывода, пока новый запрос, который WdfIoTargetSendReadSynchronous отправляется в целевой объект ввода-вывода, был удален, повторно использован или переформатирован. (WdfIoTargetSendReadSynchronous увеличивает число ссылок объекта памяти. Удаление, повторное использование или переформатирование объекта запроса уменьшает количество ссылок объекта памяти.)

    • Укажите MDL.

      Драйверы могут получить MDL, связанный с полученным запросом ввода-вывода, вызвав WdfRequestRetrieveOutputWdmMdl.

Некоторые целевые объекты ввода-вывода принимают запросы на чтение с буфером нулевой длины. Для таких целевых объектов ввода-вывода драйвер может указать NULL для параметра outputBuffer .

Сведения о получении сведений о состоянии после завершения запроса ввода-вывода см. в получения сведений о завершении.

Дополнительные сведения о WdfIoTargetSendReadSynchronousсм. в отправке запросов ввода-вывода в общие целевые объекты ввода-вывода.

Дополнительные сведения о целевых объектах ввода-вывода см. в разделе Использование целевых объектов ввода-вывода.

Примеры

Следующий пример кода создает объект памяти платформы, инициализирует структуру WDF_MEMORY_DESCRIPTOR и передает структуру в WdfIoTargetSendReadSynchronous. В этом примере указывается null для дескриптора объекта запроса, поэтому платформа создаст новый объект запроса для целевого объекта ввода-вывода.

WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
ULONG_PTR  bytesRead = NULL;

status = WdfMemoryCreate(
                         NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL
                         );
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(
                                  &MemoryDescriptor,
                                  MemoryHandle,
                                  NULL
                                  );
status = WdfIoTargetSendReadSynchronously(
                                          ioTarget,
                                          NULL,
                                          &MemoryDescriptor,
                                          NULL,
                                          NULL,
                                          &bytesRead
                                          );

Требования

Требование Ценность
целевая платформа Всеобщий
минимальная версия KMDF 1.0
минимальная версия UMDF 2.0
заголовка wdfiotarget.h (include Wdf.h)
библиотеки Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
правил соответствия DDI DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), , KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf), WriteReqs(kmdf)

См. также

EvtDriverDeviceAdd

WDF_MEMORY_DESCRIPTOR

WDF_MEMORY_DESCRIPTOR_INIT_HANDLE

WDF_REQUEST_PARAMETERS

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForRead

WdfIoTargetSendWriteSynchronous

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCancelSentRequest

WdfRequestCreate

WdfRequestRetrieveOutputMemory

WdfRequestRetrieveOutputWdmMdl

WdfRequestReuse

WdfRequestSend