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

Статья
08/08/2023

[Относится только к KMDF]

Метод WdfIoTargetFormatRequestForInternalIoctlOthers создает нестандартный внутренний запрос управления устройством для целевого объекта ввода-вывода, но не отправляет запрос.

Синтаксис

NTSTATUS WdfIoTargetFormatRequestForInternalIoctlOthers(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in]           ULONG             IoctlCode,
  [in, optional] WDFMEMORY         OtherArg1,
  [in, optional] PWDFMEMORY_OFFSET OtherArg1Offset,
  [in, optional] WDFMEMORY         OtherArg2,
  [in, optional] PWDFMEMORY_OFFSET OtherArg2Offset,
  [in, optional] WDFMEMORY         OtherArg4,
  [in, optional] PWDFMEMORY_OFFSET OtherArg4Offset
);

Параметры

[in] IoTarget

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

[in] Request

Дескриптор объекта запроса платформы. Дополнительные сведения см. в разделе "Примечания".

[in] IoctlCode

Код элемента управления вводом-выводом (IOCTL), поддерживаемый целевым объектом ввода-вывода.

[in, optional] OtherArg1

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

[in, optional] OtherArg1Offset

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

[in, optional] OtherArg2

[in, optional] OtherArg2Offset

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

[in, optional] OtherArg4

[in, optional] OtherArg4Offset

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

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INVALID_DEVICE_REQUEST	Длина передачи была больше длины буфера, или запрос ввода-вывода уже был помещен в очередь в целевой объект ввода-вывода.
STATUS_INSUFFICIENT_RESOURCES	Платформе не удалось выделить системные ресурсы (обычно это память).
STATUS_REQUEST_NOT_ACCEPTED	Пакет запроса ввода-вывода (IRP), который представляет параметр Request , не предоставляет достаточно IO_STACK_LOCATION структур, позволяющих драйверу пересылать запрос.

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

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

Используйте метод WdfIoTargetFormatRequestForInternalIoctlOthers , за которым следует метод WdfRequestSend , чтобы отправлять нестандартные внутренние запросы управления устройствами синхронно или асинхронно. Кроме того, используйте метод WdfIoTargetSendInternalIoctlOthersSynchronously для синхронной отправки нестандартных внутренних запросов управления устройствами.

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

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

Укажите дескриптор полученного запроса для параметра Request метода WdfIoTargetFormatRequestForInternalIoctlOthers.
Используйте сведения контекста полученного запроса для параметров OtherArg1, OtherArg2 и OtherArg4 метода WdfIoTargetFormatRequestForInternalIoctlOthers.
Чтобы получить эти значения параметров, драйвер должен вызвать WdfRequestGetParameters и использовать элемент DeviceIoControl возвращаемой WDF_REQUEST_PARAMETERS структуры.

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

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

Чтобы создать новый запрос ввода-вывода, выполните приведенные далее действия.

Создайте объект запроса и укажите его дескриптор для параметра Request метода WdfIoTargetFormatRequestForInternalIoctlOthers.
Вызовите WdfRequestCreate , чтобы предварительно выделить один или несколько объектов запроса. Эти объекты запроса можно повторно использовать, вызвав WdfRequestReuse. Функция обратного вызова EvtDriverDeviceAdd драйвера может предварительно выделить объекты запроса для устройства.
Предоставьте буферы контекста, если они требуются для запроса, и предоставьте дескрипторы буфера для параметров OtherArg1, OtherArg2 и OtherArg4 метода WdfIoTargetFormatRequestForInternalIoctlOthers.
Драйвер должен указать это буферное пространство, так как WDFMEMORY обрабатывает память, управляемую платформой. Чтобы получить дескрипторы WDFMEMORY, драйвер вызывает WdfMemoryCreate или WdfMemoryCreatePreallocated.

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

Несколько вызовов WdfIoTargetFormatRequestForInternalIoctlOthers , использующих один и тот же запрос, не приводят к выделению дополнительных ресурсов. Таким образом, чтобы снизить вероятность того, что WdfRequestCreate вернет STATUS_INSUFFICIENT_RESOURCES, функция обратного вызова EvtDriverDeviceAdd драйвера может вызвать WdfRequestCreate для предварительного выделения одного или нескольких объектов запроса для устройства. Впоследствии драйвер может повторно использовать (вызвать WdfRequestReuse), переформатировать (вызвать WdfIoTargetFormatRequestForInternalIoctlOthers) и повторно отправить (вызвать WdfRequestSend) каждый объект запроса, не рискуя STATUS_INSUFFICIENT_RESOURCES возвращаемое значение из последующего вызова WdfRequestCreate. (Если драйвер не вызывает один и тот же метод форматирования запросов каждый раз, могут быть выделены дополнительные ресурсы.) Все последующие вызовы WdfIoTargetFormatRequestForInternalIoctlOthers для повторно использованного объекта запроса будут возвращать STATUS_SUCCESS, если значения параметров не изменяются.

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

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

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

Примеры

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

PIRB pIrb;
WDFMEMORY memory;
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(IRB),
                         &memory,
                         NULL
                         );
if (!NT_SUCCESS(status)) {
    goto Done;
}
pIrb = WdfMemoryGetBuffer(
                          memory,
                          NULL
                          );

pIrb->FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
pIrb->Flags = 0;
pIrb->u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
pIrb->u.AllocateAddressRange.fulFlags = fulFlags;
pIrb->u.AllocateAddressRange.nLength = nLength;
pIrb->u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
pIrb->u.AllocateAddressRange.fulAccessType = fulAccessType;
pIrb->u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
pIrb->u.AllocateAddressRange.Callback = NULL;
pIrb->u.AllocateAddressRange.Context = NULL;
pIrb->u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
pIrb->u.AllocateAddressRange.FifoSListHead = NULL;
pIrb->u.AllocateAddressRange.FifoSpinLock = NULL;
pIrb->u.AllocateAddressRange.AddressesReturned = 0;
pIrb->u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
pIrb->u.AllocateAddressRange.DeviceExtension = deviceExtension;

status = WdfIoTargetFormatRequestForInternalIoctlOthers(
                                                        IoTarget,
                                                        Request,
                                                        IOCTL_1394_CLASS,
                                                        memory,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL
                                                        );

if (!NT_SUCCESS(status)) {
    goto Done;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               MyRequestCompletion,
                               NULL
                               );

if (WdfRequestSend(
                   Request,
                   IoTarget,
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
}
else {
    status = STATUS_SUCCESS;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Верхняя часть	wdfiotarget.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)