Función WdfIoTargetOpen (wdfiotarget.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfIoTargetOpen abre un destino de E/S remoto para que el controlador pueda enviar solicitudes de E/S.

Sintaxis

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

Parámetros

[in] IoTarget

Identificador de un objeto de destino de E/S obtenido de una llamada anterior a WdfIoTargetCreate.

[in] OpenParams

Puntero a una estructura de WDF_IO_TARGET_OPEN_PARAMS asignada por el autor de la llamada.

Valor devuelto

WdfIoTargetOpen devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_DEVICE_STATE	El destino de E/S especificado ya está abierto.
STATUS_INSUFFICIENT_RESOURCES	Los recursos del sistema disponibles no eran suficientes para completar la operación.
STATUS_INFO_LENGTH_MISMATCH	El tamaño de la estructura de WDF_IO_TARGET_OPEN_PARAMS que Se especificó OpenParams era incorrecto.
STATUS_NO_SUCH_DEVICE	El miembro TargetFileObject de la estructura WDF_IO_TARGET_OPEN_PARAMS del autor de la llamada especificó un objeto de archivo no válido.
STATUS_INVALID_PARAMETER	Se ha detectado un parámetro no válido.
STATUS_NOT_FOUND	No se encuentra el nombre del dispositivo identificado en el parámetro OpenParams .

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

Los controladores pueden abrir destinos de E/S remotos proporcionando una cadena Unicode que representa un nombre de objeto o proporcionando un puntero a un modelo de controlador de Windows (WDM) DEVICE_OBJECT estructura. (Normalmente, los controladores basados en marcos no tienen punteros a otras estructuras de DEVICE_OBJECT de controladores).

Para obtener un nombre de interfaz de dispositivo antes de llamar a WdfIoTargetOpen, un controlador UMDF debe llamar a CM_Register_Notification para registrarse para la notificación de llegada y eliminación de la interfaz. A continuación, puede abrir el destino remoto mediante el nombre simbólico de la interfaz que recibe en la rutina de devolución de llamada de notificación de interfaz. El controlador debe seguir escuchando la notificación de eliminación mientras el identificador está abierto. Si se produce un error en el controlador de destino, el controlador UMDF debe cerrar el identificador.

Si la interfaz ya existe, un controlador UMDF debe llamar a CM_Get_Device_Interface_List, posiblemente llamando a CM_Get_Device_Interface_List_Size primero para determinar el tamaño de búfer necesario.

Si desea que el controlador use su destino de E/S local, el controlador debe llamar a WdfDeviceGetIoTarget en lugar de WdfIoTargetOpen.

Si se produce un error en una llamada a WdfIoTargetOpen , el controlador debe llamar a WdfObjectDelete para eliminar el objeto de destino de E/S.

Para obtener más información sobre WdfIoTargetOpen, vea Inicializar un destino de E/S general.

Para obtener más información sobre los destinos de E/S, consulte Uso de destinos de E/S.

Ejemplos

En el ejemplo siguiente se crea un objeto de destino de E/S, se inicializa una estructura de WDF_IO_TARGET_OPEN_PARAMS y se abre un destino de E/S remoto especificando el nombre de vínculo simbólico de un 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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfiotarget.h (incluya Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)