Функция 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 возвращается после завершения запроса ввода-вывода, а возвращаемое значение — значение состояния завершения запроса. В противном случае этот метод может вернуть одно из следующих значений:

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

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

Замечания

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

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

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

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

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

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

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
                                          );