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

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

  • Статья

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

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

Синтаксис

NTSTATUS WdfIoTargetSendWriteSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    InputBuffer,
  [in, optional]  PLONGLONG                 DeviceOffset,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesWritten
);

Параметры

[in] IoTarget

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

[in, optional] Request

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

[in, optional] InputBuffer

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

[in, optional] DeviceOffset

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

[in, optional] RequestOptions

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

[out, optional] BytesWritten

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

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

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

Возвращаемый код Описание
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.

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

Замечания

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    • Укажите MDL.

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

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

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

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

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

Примеры

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

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

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

Требования

Требование Ценность
целевая платформа Всеобщий
минимальная версия 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), Kmdfdf, Kmdf2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf)

См. также

EvtDriverDeviceAdd

WDF_MEMORY_DESCRIPTOR

WDF_MEMORY_DESCRIPTOR_INIT_HANDLE

WDF_REQUEST_PARAMETERS

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForWrite

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCancelSentRequest

WdfRequestCreate

WdfRequestRetrieveInputMemory

WdfRequestRetrieveInputWdmMdl

WdfRequestReuse

WdfRequestSend