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.

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

Confira também

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject