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.
Valor de retorno
Se o driver especificou 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 retorna NULL .
Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.
Observações
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 WdfIoTargetCloseForQueryRemoveou 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 do dispositivo WDM depois que ele for 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 IDENTIFICADOr 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 hEvent membro da estrutura de 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 está 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 umgeral de destino 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 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 subjacente no modo kernel 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(¶ms, NULL);
status = WdfIoTargetOpen(ioTarget, ¶ms);
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 |
|---|---|
| da 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 o Controle de Versão da Biblioteca da Estrutura.) |
| IRQL | <=DISPATCH_LEVEL |
| regras de conformidade de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |