Função WdfIoTargetWdmGetTargetFileHandle (wdfiotarget.h)

[Aplica-se a KMDF e UMDF]

O método WdfIoTargetWdmGetTargetFileHandle retorna um identificador para o arquivo associado a um destino de E/S remoto especificado.

Sintaxe

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

Parâmetros

[in] IoTarget

Um identificador para um objeto de destino de E/S remoto. Esse identificador foi obtido de uma chamada anterior para WdfIoTargetCreate.

Retornar valor

Se o driver tiver especificado um nome de objeto quando ele chamou WdfIoTargetOpen, WdfIoTargetWdmGetTargetFileHandle retornará o identificador de arquivo associado ao destino de E/S especificado. Caso contrário , WdfIoTargetWdmGetTargetFileHandle retornará NULL.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

Para KMDF, o identificador de arquivo retornado é um identificador de modo kernel válido em um contexto de thread arbitrário. Para obter informações sobre como um driver pode usar esse identificador de arquivo, consulte Usando um identificador de arquivo.

O identificador de arquivo que o método WdfIoTargetWdmGetTargetFileHandle retorna é válido até que o driver chame WdfIoTargetClose ou WdfIoTargetCloseForQueryRemove ou até que o objeto de destino de E/S remoto seja excluído. Se o driver fornecer uma função EvtCleanupCallback para o objeto de destino de E/S remoto e se o objeto for excluído antes que o destino de E/S remoto seja fechado, o ponteiro será válido até que a função EvtCleanupCallback retorne.

Se o driver tentar acessar o objeto de dispositivo WDM depois que ele tiver sido removido, o driver poderá causar uma falha no sistema. O exemplo toastmon demonstra como o driver pode fornecer uma função de retorno de chamada EvtIoTargetQueryRemove para que ele seja notificado se o destino de E/S for removido.

Para UMDF, WdfIoTargetWdmGetTargetFileHandle retorna um HANDLE Win32 válido somente no processo atual. Um driver UMDF herdado (versão 1).x) chama IWDFDevice::RetrieveDeviceName para obter o nome do dispositivo de modo kernel subjacente e, em seguida, abre um identificador para ele com CreateFile. Em seguida, o driver pode enviar E/S diretamente para os dispositivos inferiores usando DeviceIoControl. A partir do UMDF 2.15, os drivers UMDF v2 podem abrir o destino de E/S local por arquivo (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) e recuperar o identificador de arquivo usando WdfIoTargetWdmGetTargetFileHandle. A estrutura é aberta e fecha o identificador de arquivo quando o destino remoto é fechado ou excluído. O identificador de arquivo permanece válido dentro do contrato de WdfIoTargetWdmGetTargetFileHandle descrito acima.

Aviso

Se um driver UMDF v2 chamar WdfIoTargetWdmGetTargetFileHandle para obter o identificador Win32 de um destino remoto aberto usando WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, não envie E/S sobreposta/assíncrona com APIs como DeviceIoControl. Isso pode travar o processo que hospeda o driver. Se o driver precisar enviar E/S sobreposta, ele também deverá definir o bit de baixa ordem do membro hEvent da estrutura OVERLAPPED . Isso ocorre porque a estrutura associa internamente o identificador a uma porta de conclusão de E/S. Um identificador de evento válido cujo bit de baixa ordem é definido impede que a conclusão de E/S seja enfileirada para a porta de conclusão.

Para obter mais informações sobre WdfIoTargetWdmGetTargetFileHandle, consulte Obtendo informações sobre um destino de E/S geral.

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

Exemplos

O exemplo de código a seguir obtém um identificador para o arquivo associado a um destino de E/S remoto especificado.

HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

Um driver UMDF herdado (versão 1).x) chama IWDFDevice::RetrieveDeviceName para obter o nome do dispositivo de modo kernel subjacente e, em seguida, abrir um identificador para ele com CreateFile. Em seguida, o driver envia E/S diretamente para o dispositivo usando DeviceIoControl.

A partir do UMDF 2.15, o driver abre o destino de E/S local por arquivo e recupera seu identificador. A estrutura é aberta e fecha o identificador de arquivo. O identificador de arquivo permanece válido dentro do contrato de WdfIoTargetWdmGetTargetFileHandle.

NTSTATUS status;

WDF_IO_TARGET_OPEN_PARAMS params;

WDFIOTARGET ioTarget = NULL;

HANDLE handle = NULL;

status = WdfIoTargetCreate(Device, &attr, &ioTarget);

if (!NT_SUCCESS(status)) {

    // error handling

}

WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE(&params, NULL);

status = WdfIoTargetOpen(ioTarget, &params);

if (!NT_SUCCESS(status)) {

    // error handling

}

handle = WdfIoTargetWdmGetTargetFileHandle(ioTarget);

if (handle == NULL) {

    // error handling

}

if (ioTarget != NULL) {
    WdfIoTargetClose(ioTarget);
}
// You can now call DeviceIoControl(handle, ...) etc.
// NOTE: See Warning above on submitting overlapped or asynchronous I/O

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2.15
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 da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Confira também

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject