Função WdfIoTargetSendInternalIoctlOthersSynchronously (wdfiotarget.h)

[Aplica-se somente ao KMDF]

O método WdfIoTargetSendInternalIoctlOthersSynchronously cria uma solicitação de controle de dispositivo interno não padrão e a envia de forma síncrona para um destino de E/S.

Sintaxe

NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg1,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg2,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg4,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesReturned
);

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, optional] Request

Um identificador para um objeto de solicitação de estrutura. Esse parâmetro é opcional e pode ser NULL. 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 ponteiro para uma estrutura WDF_MEMORY_DESCRIPTOR que descreve um buffer de memória que contém informações de contexto. Esse parâmetro é opcional e pode ser NULL.

[in, optional] OtherArg2

Um ponteiro para uma estrutura WDF_MEMORY_DESCRIPTOR que descreve um buffer de memória que contém informações de contexto. Esse parâmetro é opcional e pode ser NULL.

[in, optional] OtherArg4

Um ponteiro para uma estrutura WDF_MEMORY_DESCRIPTOR que descreve um buffer de memória que contém informações de contexto. Esse parâmetro é opcional e pode ser NULL.

[in, optional] RequestOptions

Um ponteiro para uma estrutura de WDF_REQUEST_SEND_OPTIONS alocada por chamador que especifica opções para a solicitação. Esse ponteiro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários a seguir.

[out, optional] BytesReturned

Um ponteiro para um local que recebe informações (como o número de bytes que foram transferidos) que outro driver fornece quando conclui a solicitação chamando WdfRequestCompleteWithInformation. Esse ponteiro é opcional e pode ser NULL.

Valor retornado

Se a operação for bem-sucedida, wdfIoTargetSendInternalIoctlOthersSynchronously após a conclusão da solicitação de controle do dispositivo interno e o valor retornado será o valor de status de conclusão da solicitação. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno Descrição
STATUS_INVALID_PARAMETER
Um parâmetro inválido foi detectado.
STATUS_INFO_LENGTH_MISMATCH
O tamanho da estrutura WDF_REQUEST_SEND_OPTIONS que o parâmetro RequestOptions apontou estava incorreto.
STATUS_INVALID_DEVICE_REQUEST
A solicitação 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_IO_TIMEOUT
O driver forneceu um valor de tempo limite e a solicitação não foi concluída dentro do tempo alocado.
STATUS_REQUEST_NOT_ACCEPTED
O IRP (pacote de solicitação de E/S) que o parâmetro De solicitação 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.

Ocorre uma verificação de bug se o driver fornece um identificador de objeto inválido.

Comentários

Uma solicitação de controle de dispositivo interno não padrão usa um código IOCTL para identificar a operação a ser executada, mas a solicitação não usa os buffers de entrada e saída padrão que outras solicitações de controle de dispositivo internas usam. Se você estiver criando um conjunto de drivers de interação, poderá definir como esse conjunto de drivers usa os argumentos da solicitação: OtherArg1, OtherArg2 e OtherArg4.

Não há nenhum parâmetro chamado OtherArg3 porque a estrutura associa esses parâmetros aos membros Argument1, Argument2 e Argument4 da união Other.Parameters na estrutura de IO_STACK_LOCATION do driver. O membro Argument3 nesse sindicato recebe o valor do parâmetro IoctlCode , portanto, ele não está disponível para outros valores fornecidos pelo driver.

Use o método WdfIoTargetSendInternalIoctlOthersSynchronously para enviar solicitações de controle de dispositivo internas não padrão de forma síncrona. Para enviar solicitações de controle de dispositivo internas de forma assíncrona, use WdfIoTargetFormatRequestForInternalIoctlOthers, seguido por WdfRequestSend.

Para obter mais informações sobre solicitações de controle de dispositivo internas, consulte Usando códigos de controle de E/S.

O método WdfIoTargetSendInternalIoctlOthersSynchronously não retorna até que a solicitação seja concluída, a menos que o driver forneça um valor de tempo limite na estrutura WDF_REQUEST_SEND_OPTIONS do parâmetro RequestOptions ou a menos que um erro seja detectado.

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, possivelmente, algum espaço de contexto.

Para encaminhar uma solicitação de controle de dispositivo interno não padrão que o driver recebeu em uma fila de E/S:

  1. Especifique o identificador da solicitação recebida para o parâmetro Solicitação do método WdfIoTargetSendInternalIoctlOthersSynchronously.
  2. Use as informações de contexto da solicitação recebida para os parâmetros OtherArg1, OtherArg2 e OtherArg4 do método WdfIoTargetSendInternalIoctlOthersSynchronously.

    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 Solicitações de E/S de Encaminhamento.

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:

  1. Forneça um identificador de solicitação NULL para o parâmetro solicitação do método WdfIoTargetSendInternalIoctlOthersSynchronously ou crie um novo objeto de solicitação e forneça seu identificador:
    • Se você fornecer um identificador de solicitação NULL, a estrutura usará um objeto de solicitação interna. Essa técnica é simples de usar, mas o driver não pode cancelar a solicitação.
    • Se você chamar WdfRequestCreate para criar um ou mais objetos de solicitação, poderá reutilizar esses objetos de solicitação chamando WdfRequestReuse. Essa técnica permite que a função de retorno de chamada EvtDriverDeviceAdd do driver prealoce objetos de solicitação para um dispositivo. Além disso, outro thread de driver pode chamar WdfRequestCancelSentRequest para cancelar a solicitação, se necessário.

    Seu driver pode especificar um parâmetro RequestOptions não NULL, se o driver fornece um parâmetro de solicitação não NULL ou NULL. Você pode, por exemplo, usar o parâmetro RequestOptions para especificar um valor de tempo limite.

  2. Forneça espaço de contexto para os parâmetros OtherArg1, OtherArg2 e OtherArg4 do método WdfIoTargetSendInternalIoctlOthersSynchronously, OtherArg2 e OtherArg4, se a solicitação exigir.

    Seu driver pode especificar esse espaço de contexto como buffers alocados localmente, como identificadores WDFMEMORY ou como MDLs (listas de descritores de memória). Você pode usar qualquer método mais conveniente.

    As seguintes técnicas para especificar o espaço em buffer estão disponíveis:

    • Forneça buffers locais.

      Como o WdfIoTargetSendInternalIoctlOthersSynchronously manipula solicitações de E/S de forma síncrona, o driver pode criar buffers de solicitação que são locais para a rotina de chamada, como mostra o exemplo de código a seguir.

      WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
      MY_BUFFER_TYPE  MyBuffer;
      WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                        (PVOID) &MyBuffer,
                                        sizeof(MyBuffer));
      
    • Forneça identificadores WDFMEMORY.

      Chame WdfMemoryCreate ou WdfMemoryCreatePreallocated para obter um identificador para a memória gerenciada por estrutura, como mostra o exemplo de código a seguir.

      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);
      
    • Fornecer MDLs.

      Os drivers podem obter MDLs associadas a uma solicitação de E/S recebida chamando WdfRequestRetrieveInputWdmMdl e WdfRequestRetrieveOutputWdmMdl.

Para obter informações sobre como obter informações de status após a conclusão de uma solicitação de E/S, consulte Obter informações de conclusão.

Para obter mais informações sobre WdfIoTargetSendInternalIoctlOthersSynchronously, consulte Como enviar solicitações de E/S para destinos gerais de E/S.

Para obter mais informações sobre destinos de E/S, consulte Como usar destinos de E/S.

Exemplos

O exemplo de código a seguir inicializa uma estrutura IRB IEEE 1394, usa o endereço da estrutura para inicializar uma estrutura WDF_MEMORY_DESCRIPTOR e, em seguida, chama WdfIoTargetSendInternalIoctlOthersSynchronously.

WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;

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

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &descriptor,
                                  &Irb,
                                  sizeof (IRB)
                                  );

ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
                                                           IoTarget, 
                                                           NULL,
                                                           IOCTL_1394_CLASS,
                                                           &descriptor,
                                                           NULL,
                                                           NULL,
                                                           NULL,
                                                           NULL
                                                           );

Requisitos

   
Plataforma de Destino Universal
Versão mínima do KMDF 1,0
Cabeçalho wdfiotarget.h (include Wdf.h)
Biblioteca Wdf01000.sys (consulte o Controle de Versão da Biblioteca de Estruturas).)
IRQL PASSIVE_LEVEL
Regras de conformidade DDI DeferredRequestCompleted(kmdf), DriverCreate(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), WriteReqs(kmdf)

Confira também

EvtDriverDeviceAdd

IO_STACK_LOCATION

WDF_MEMORY_DESCRIPTOR

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WDF_REQUEST_PARAMETERS

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForInternalIoctlOthers

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCancelSentRequest

WdfRequestCompleteWithInformation

WdfRequestCreate

WdfRequestGetParameters

WdfRequestRetrieveInputWdmMdl

WdfRequestRetrieveOutputWdmMdl

WdfRequestReuse

WdfRequestSend