Função WdfIoTargetFormatRequestForInternalIoctlOthers (wdfiotarget.h)

Artigo
08/08/2023

[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

[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

[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
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_INVALID_DEVICE_REQUEST	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.
STATUS_INSUFFICIENT_RESOURCES	A estrutura não pôde alocar recursos do sistema (normalmente memória).
STATUS_REQUEST_NOT_ACCEPTED	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.

Para obter mais informações sobre como encaminhar uma solicitação de E/S, consulte Encaminhando solicitações de E/S.

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.

Depois que um driver chama WdfIoTargetFormatRequestForInternalIoctlOthers para formatar uma solicitação de controle de dispositivo, o driver deve chamar WdfRequestSend para enviar a solicitação (de forma síncrona ou assíncrona) para um destino de E/S.

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)