Функция WdfIoTargetSendReadSynchronously (wdfiotarget.h)
[Применимо к KMDF и UMDF]
Метод WdfIoTargetSendReadSynchronously создает запрос на чтение и отправляет его синхронно целевому объекту ввода-вывода.
Синтаксис
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
Указатель на расположение, указывающее начальное смещение для передачи. Целевой объект ввода-вывода (т. е. следующий драйвер ниже) определяет, как использовать это значение. Например, драйверы в стеке драйверов диска могут указывать смещение от начала диска. Целевой объект ввода-вывода получает эти сведения в элементе Parameters.Read.DeviceOffsetструктуры WDF_REQUEST_PARAMETERS запроса. Этот указатель является необязательным. Большинство драйверов устанавливают для этого указателя значение NULL.
[in, optional] RequestOptions
Указатель на структуру WDF_REQUEST_SEND_OPTIONS , выделенную вызывающим объектом, которая задает параметры для запроса на чтение. Этот указатель является необязательным и может иметь значение NULL.
[out, optional] BytesRead
Указатель на расположение, которое получает количество прочитанных байтов, если операция выполнена успешно. Этот указатель является необязательным и может иметь значение NULL.
Возвращаемое значение
Если операция выполнена успешно, WdfIoTargetSendReadSynchronously возвращается после завершения запроса ввода-вывода, а возвращаемое значение — это значение состояния завершения запроса. В противном случае этот метод может возвращать одно из следующих значений:
Код возврата | Описание |
---|---|
|
Обнаружен недопустимый параметр. |
|
Неправильный размер структуры WDF_REQUEST_SEND_OPTIONS, на которую указал параметр RequestOptions . |
|
Запрос ввода-вывода уже помещен в очередь в целевой объект ввода-вывода. |
|
Платформе не удалось выделить системные ресурсы (обычно это память). |
|
Драйвер указал значение времени ожидания, и запрос не был выполнен в течение отведенного времени. |
|
Пакет запроса ввода-вывода (IRP), который представляет параметр Request , не предоставляет достаточно IO_STACK_LOCATION структур, позволяющих драйверу пересылать запрос. |
Этот метод также может возвращать другие значения NTSTATUS.
Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.
Комментарии
Используйте метод WdfIoTargetSendReadSynchronously для синхронной отправки запросов на чтение. Для асинхронной отправки запросов на чтение используйте метод WdfIoTargetFormatRequestForRead , за которым следует метод WdfRequestSend .
WdfIoTargetSendReadSynchronously не возвращается до завершения запроса, если драйвер не предоставляет значение времени ожидания в структуре WDF_REQUEST_SEND_OPTIONS параметра RequestOptions или если не обнаружена ошибка.
Вы можете переслать запрос ввода-вывода, полученный драйвером в очереди ввода-вывода, или создать и отправить новый запрос. В любом случае платформе требуется объект запроса и некоторое буферное пространство.
Чтобы переслать запрос ввода-вывода, полученный драйвером в очереди ввода-вывода, выполните приведенные далее действия.
- Укажите дескриптор полученного запроса для параметра Request .
-
Используйте выходной буфер полученного запроса для параметра OutputBuffer метода WdfIoTargetSendReadSynchronously.
Драйвер должен вызвать WdfRequestRetrieveOutputMemory , чтобы получить дескриптор объекта памяти платформы, который представляет выходной буфер запроса. Затем драйвер должен поместить этот дескриптор в структуру WDF_MEMORY_DESCRIPTOR , которую драйвер предоставляет для параметра OutputBuffer .
Драйверы часто разделяют полученные запросы ввода-вывода на более мелкие запросы, отправляемые в целевой объект ввода-вывода, поэтому драйвер может создавать новые запросы.
Чтобы создать новый запрос ввода-вывода, выполните приведенные далее действия.
-
Укажите дескриптор запроса NULL для параметра Request метода WdfIoTargetSendReadSynchronously или создайте новый объект запроса и укажите его дескриптор:
- Если вы предоставляете дескриптор запроса NULL , платформа использует внутренний объект запроса. Этот метод прост в использовании, но драйвер не может отменить запрос.
- При вызове WdfRequestCreate для создания одного или нескольких объектов запроса можно повторно использовать эти объекты запроса, вызвав WdfRequestReuse. Этот метод позволяет функции обратного вызова EvtDriverDeviceAdd драйвера предварительно выделить объекты запроса для устройства. Кроме того, другой поток драйвера может вызвать WdfRequestCancelSentRequest , чтобы при необходимости отменить запрос.
Драйвер может указать параметр RequestOptions, отличный от NULL, независимо от того, предоставляет ли драйвер параметр запроса, отличный от NULL или NULL. Например, можно использовать параметр RequestOptions , чтобы указать значение времени ожидания.
-
Укажите буферное пространство для параметра OutputBuffer метода WdfIoTargetSendReadSynchronously.
Драйвер может указать это буферное пространство как локально выделенный буфер, как дескриптор WDFMEMORY или как список дескрипторов памяти (MDL). Вы можете использовать любой наиболее удобный метод.
При необходимости платформа преобразует описание буфера в описание, правильное для метода целевого объекта ввода-вывода для доступа к буферам данных.
Доступны следующие методы указания буферного пространства:
-
Укажите локальный буфер.
Так как WdfIoTargetSendReadSynchronously обрабатывает запросы ввода-вывода синхронно, драйвер может создавать буферы запросов, которые являются локальными для вызывающей подпрограммы, как показано в следующем примере кода.
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 , чтобы получить дескриптор объекта памяти платформы, который представляет выходной буфер полученного запроса ввода-вывода, если требуется, чтобы драйвер передавал содержимое этого буфера целевому объекту ввода-вывода. Драйвер не должен выполнять полученный запрос ввода-вывода, пока новый запрос , который WdfIoTargetSendReadSynchronously отправляет в целевой объект ввода-вывода, не будет удален, повторно использован или переформатирован. (WdfIoTargetSendReadSynchronously увеличивает число ссылок объекта памяти. Удаление, повторное использование или переформатирование объекта запроса уменьшает количество ссылок на объект памяти.)
-
Предоставьте MDL.
Драйверы могут получить MDL, связанный с полученным запросом ввода-вывода, вызвав WdfRequestRetrieveOutputWdmMdl.
-
Укажите локальный буфер.
Сведения о получении сведений о состоянии после завершения запроса ввода-вывода см. в разделе Получение сведений о завершении.
Дополнительные сведения о WdfIoTargetSendReadSynchronously см. в разделе Отправка запросов ввода-вывода к общим целевым объектам ввода-вывода.
Дополнительные сведения о целевых объектах ввода-вывода см. в разделе Использование целевых объектов ввода-вывода.
Примеры
В следующем примере кода создается объект памяти платформы, инициализируется структура WDF_MEMORY_DESCRIPTOR и передается в WdfIoTargetSendReadSynchronously. В этом примере для дескриптора объекта запроса задается значение 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 (включая 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) |
См. также раздел
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE
WdfIoTargetFormatRequestForRead
WdfIoTargetSendWriteSynchronously
WdfRequestRetrieveOutputMemory
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по