Função WdfIoTargetOpen (wdfiotarget.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfIoTargetOpen abre um destino de E/S remoto para que o driver possa enviar solicitações de E/S para ele.

Sintaxe

NTSTATUS WdfIoTargetOpen(
  [in] WDFIOTARGET                IoTarget,
  [in] PWDF_IO_TARGET_OPEN_PARAMS OpenParams
);

Parâmetros

[in] IoTarget

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

[in] OpenParams

Um ponteiro para uma estrutura de WDF_IO_TARGET_OPEN_PARAMS alocada pelo chamador.

Retornar valor

WdfIoTargetOpen retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_DEVICE_STATE	O destino de E/S especificado já está aberto.
STATUS_INSUFFICIENT_RESOURCES	Os recursos do sistema disponíveis não foram suficientes para concluir a operação.
STATUS_INFO_LENGTH_MISMATCH	O tamanho da estrutura de WDF_IO_TARGET_OPEN_PARAMS especificada pelo OpenParams estava incorreto.
STATUS_NO_SUCH_DEVICE	O membro TargetFileObject da estrutura WDF_IO_TARGET_OPEN_PARAMS do chamador especificou um objeto de arquivo inválido.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_NOT_FOUND	O nome do dispositivo identificado no parâmetro OpenParams não pode ser encontrado.

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

Os drivers podem abrir destinos de E/S remotos fornecendo uma cadeia de caracteres Unicode que representa um nome de objeto ou fornecendo um ponteiro para uma estrutura do WDM (Modelo de Driver do Windows) DEVICE_OBJECT. (Os drivers baseados em estrutura normalmente não têm ponteiros para estruturas de DEVICE_OBJECT de outros drivers.)

Para obter um nome de interface do dispositivo antes de chamar WdfIoTargetOpen, um driver UMDF deve chamar CM_Register_Notification para se registrar para a notificação de chegada e remoção da interface. Em seguida, ele pode abrir o destino remoto usando o nome simbólico da interface que recebe na rotina de retorno de chamada de notificação de interface. O driver deve continuar a escutar a notificação de remoção enquanto o identificador está aberto. Se o driver de destino falhar, o driver UMDF deverá fechar o identificador.

Se a interface já existir, um driver UMDF deverá chamar CM_Get_Device_Interface_List, possivelmente chamando CM_Get_Device_Interface_List_Size primeiro para determinar o tamanho do buffer necessário.

Se você quiser que o driver use seu destino de E/S local, o driver deverá chamar WdfDeviceGetIoTarget em vez de WdfIoTargetOpen.

Se uma chamada para WdfIoTargetOpen falhar, o driver deverá chamar WdfObjectDelete para excluir o objeto de destino de E/S.

Para obter mais informações sobre WdfIoTargetOpen, consulte Inicializando 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 a seguir cria um objeto de destino de E/S, inicializa uma estrutura WDF_IO_TARGET_OPEN_PARAMS e abre um destino de E/S remoto especificando o nome simbólico do link de um dispositivo.

WDF_OBJECT_ATTRIBUTES  ioTargetAttrib;
WDFIOTARGET  ioTarget;
WDF_IO_TARGET_OPEN_PARAMS  openParams;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ioTargetAttrib,
                                        TARGET_DEVICE_INFO
                                        );
status = WdfIoTargetCreate(
                           device,
                           &ioTargetAttrib,
                           &ioTarget
                           );
if (!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(
                                            &openParams,
                                            SymbolicLink,
                                            STANDARD_RIGHTS_ALL
                                            );
status = WdfIoTargetOpen(
                         ioTarget,
                         &openParams
                         );
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(ioTarget);
    return status;
}

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfiotarget.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)