Функция WdfIoTargetFormatRequestForInternalIoctlOthers (wdfiotarget.h)
[Относится только к 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
Дескриптор объекта памяти платформы. Этот объект представляет буфер, который драйвер использует для получения сведений о контексте конкретного запроса, определяемого драйвером. Дополнительные сведения см. в разделе "Примечания". Этот параметр является необязательным и может иметь значение NULL.
[in, optional] OtherArg2Offset
Указатель на структуру, выделенную вызывающим объектом WDFMEMORY_OFFSET , которая предоставляет необязательные значения смещения и длины байтов. Драйверы могут использовать эти значения для указания начального адреса и длины сегмента области контекста, указанной в OtherArg2. Этот параметр является необязательным и может иметь значение NULL.
[in, optional] OtherArg4
Дескриптор объекта памяти платформы. Этот объект представляет буфер, который драйвер использует для получения сведений о контексте конкретного запроса, определяемого драйвером. Дополнительные сведения см. в разделе "Примечания". Этот параметр является необязательным и может иметь значение NULL.
[in, optional] OtherArg4Offset
Указатель на структуру, выделенную вызывающим объектом WDFMEMORY_OFFSET , которая предоставляет необязательные значения смещения и длины байтов. Драйверы могут использовать эти значения для указания начального адреса и длины сегмента области контекста, указанной в OtherArg4. Этот параметр является необязательным и может иметь значение NULL.
Возвращаемое значение
WdfIoTargetFormatRequestForInternalIoctlOthers возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:
| Код возврата | Описание |
|---|---|
|
Обнаружен недопустимый параметр. |
|
Длина передачи была больше длины буфера, или запрос ввода-вывода уже был помещен в очередь в целевой объект ввода-вывода. |
|
Платформе не удалось выделить системные ресурсы (обычно это память). |
|
Пакет запроса ввода-вывода (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 , использующих один и тот же запрос, не приводят к выделению дополнительных ресурсов. Таким образом, чтобы снизить вероятность того, что 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) |
См. также раздел
WdfIoTargetSendInternalIoctlOthersSynchronously