Função WdfIoTargetFormatRequestForInternalIoctlOthers (wdfiotarget.h)
[Aplica-se somente ao KMDF]
O método WdfIoTargetFormatRequestForInternalIoctlOthers cria uma solicitação de controle de dispositivo interno não padrão para um destino de E/S, mas não envia a solicitação.
Sintaxe
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
);
Parâmetros
[in] IoTarget
Um identificador para um objeto de destino de E/S local ou remoto que foi obtido de uma chamada anterior para WdfDeviceGetIoTarget ou WdfIoTargetCreate, ou de um método que um destino de E/S especializado fornece.
[in] Request
Um identificador para um objeto de solicitação de estrutura. Para obter mais informações, consulte a seção Comentários a seguir.
[in] IoctlCode
Um IOCTL (código de controle de E/S) compatível com o destino de E/S.
[in, optional] OtherArg1
Um identificador para um objeto de memória de estrutura. Esse objeto representa um buffer que o driver usa para informações de contexto específicas de solicitação e definidas pelo driver. Para obter mais informações, consulte a seção Comentários a seguir. Esse parâmetro é opcional e pode ser NULL.
[in, optional] OtherArg1Offset
Um ponteiro para uma estrutura de WDFMEMORY_OFFSET alocada pelo chamador que fornece valores opcionais de deslocamento e comprimento de bytes. Os drivers podem usar esses valores para especificar o endereço inicial e o comprimento de um segmento da área de contexto especificada por OtherArg1. Esse parâmetro é opcional e pode ser NULL.
[in, optional] OtherArg2
Um identificador para um objeto de memória de estrutura. Esse objeto representa um buffer que o driver usa para informações de contexto específicas de solicitação e definidas pelo driver. Para obter mais informações, consulte a seção Comentários a seguir. Esse parâmetro é opcional e pode ser NULL.
[in, optional] OtherArg2Offset
Um ponteiro para uma estrutura de WDFMEMORY_OFFSET alocada pelo chamador que fornece valores opcionais de deslocamento e comprimento de bytes. Os drivers podem usar esses valores para especificar o endereço inicial e o comprimento de um segmento da área de contexto especificada por OtherArg2. Esse parâmetro é opcional e pode ser NULL.
[in, optional] OtherArg4
Um identificador para um objeto de memória de estrutura. Esse objeto representa um buffer que o driver usa para informações de contexto específicas de solicitação e definidas pelo driver. Para obter mais informações, consulte a seção Comentários a seguir. Esse parâmetro é opcional e pode ser NULL.
[in, optional] OtherArg4Offset
Um ponteiro para uma estrutura de WDFMEMORY_OFFSET alocada pelo chamador que fornece valores opcionais de deslocamento e comprimento de bytes. Os drivers podem usar esses valores para especificar o endereço inicial e o comprimento de um segmento da área de contexto especificada por OtherArg4. Esse parâmetro é opcional e pode ser NULL.
Retornar valor
WdfIoTargetFormatRequestForInternalIoctlOthers retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
|
Um parâmetro inválido foi detectado. |
|
O comprimento da transferência era maior que o comprimento do buffer ou a solicitação de E/S já estava na fila para um destino de E/S. |
|
A estrutura não pôde alocar recursos do sistema (normalmente memória). |
|
O IRP (pacote de solicitação de E/S) que o parâmetro Request representa não fornece estruturas de IO_STACK_LOCATION suficientes para permitir que o driver encaminhe a solicitação. |
Esse método também pode retornar outros valores NTSTATUS.
Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.
Comentários
Use o método WdfIoTargetFormatRequestForInternalIoctlOthers , seguido pelo método WdfRequestSend , para enviar solicitações de controle de dispositivo internas não padrão de forma síncrona ou assíncrona. Como alternativa, use o método WdfIoTargetSendInternalIoctlOthersSynchronously para enviar solicitações de controle de dispositivo internas não padrão de forma síncrona.
Você pode encaminhar uma solicitação de controle de dispositivo interno não padrão que o driver recebeu em uma fila de E/S ou pode criar e enviar uma nova solicitação. Em ambos os casos, a estrutura requer um objeto de solicitação e algum espaço de buffer.
Para encaminhar uma solicitação de controle de dispositivo interno não padrão que seu driver recebeu em uma fila de E/S:
- Especifique o identificador da solicitação recebida para o parâmetro Request do método WdfIoTargetFormatRequestForInternalIoctlOthers.
-
Use as informações de contexto da solicitação recebida para os parâmetros OtherArg1, OtherArg2 e OtherArg4 do método WdfIoTargetFormatRequestForInternalIoctlOthers.
Para obter esses valores de parâmetro, o driver deve chamar WdfRequestGetParameters e usar o membro DeviceIoControl da estrutura WDF_REQUEST_PARAMETERS retornada.
Os drivers geralmente dividem as solicitações de E/S recebidas em solicitações menores que eles enviam para um destino de E/S, para que o driver possa criar novas solicitações.
Para criar uma nova solicitação de E/S:
-
Crie um novo objeto de solicitação e forneça seu identificador para o parâmetro Request do método WdfIoTargetFormatRequestForInternalIoctlOthers.
Chame WdfRequestCreate para pré-alocar um ou mais objetos de solicitação. Você pode reutilizar esses objetos de solicitação chamando WdfRequestReuse. A função de retorno de chamada EvtDriverDeviceAdd do driver pode pré-alocar objetos de solicitação para um dispositivo.
-
Forneça buffers de contexto, se a solicitação exigir e forneça identificadores de buffer para os parâmetros OtherArg1, OtherArg2 e OtherArg4 do método WdfIoTargetFormatRequestForInternalIoctlOthers.
Seu driver deve especificar esse espaço de buffer como identificador WDFMEMORY para memória gerenciada por estrutura. Para obter identificadores WDFMEMORY, o driver chama WdfMemoryCreate ou WdfMemoryCreatePreallocated.
Várias chamadas para WdfIoTargetFormatRequestForInternalIoctlOthers que usam a mesma solicitação não causam alocações de recursos adicionais. Portanto, para reduzir a chance de WdfRequestCreate retornar STATUS_INSUFFICIENT_RESOURCES, a função de retorno de chamada EvtDriverDeviceAdd do driver pode chamar WdfRequestCreate para pré-alocar um ou mais objetos de solicitação para um dispositivo. O driver pode reutilizar posteriormente (chamar WdfRequestReuse), reformat (chamar WdfIoTargetFormatRequestForInternalIoctlOthers) e reenviar (chamar WdfRequestSend) cada objeto de solicitação sem arriscar uma STATUS_INSUFFICIENT_RESOURCES retornar valor de uma chamada posterior para WdfRequestCreate. (Se o driver não chamar o mesmo método de formatação de solicitação todas as vezes, recursos adicionais poderão ser alocados.) Todas as chamadas subsequentes para WdfIoTargetFormatRequestForInternalIoctlOthers para o objeto de solicitação reutilizado retornarão STATUS_SUCCESS, se os valores de parâmetro não forem alterados.
Para obter informações sobre como obter informações de status após a conclusão de uma solicitação de E/S, consulte Obtendo informações de conclusão.
Para obter mais informações sobre WdfIoTargetFormatRequestForInternalIoctlOthers, consulte Enviando solicitações de E/S para destinos gerais de E/S.
Para obter mais informações sobre destinos de E/S, consulte Usando destinos de E/S.
Exemplos
O exemplo de código a seguir cria um objeto de memória de estrutura, obtém o buffer que o objeto de memória contém e inicializa o buffer. Em seguida, o exemplo formata a solicitação, define uma função de retorno de chamada CompletionRoutine e envia a solicitação para um destino de E/S.
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;
}
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Versão mínima do KMDF | 1.0 |
| Cabeçalho | wdfiotarget.h (inclua Wdf.h) |
| Biblioteca | Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.) |
| IRQL | <=DISPATCH_LEVEL |
| Regras de conformidade de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf) |
Confira também
WdfIoTargetSendInternalIoctlOthersSynchronously