Función IoRegisterDeviceInterface (wdm.h)

  • Artículo

La rutina IoRegisterDeviceInterface registra una clase de interfaz de dispositivo, si no se ha registrado previamente y crea una nueva instancia de la clase de interfaz, que posteriormente un controlador puede habilitar para su uso por aplicaciones u otros componentes del sistema.

Sintaxis

NTSTATUS IoRegisterDeviceInterface(
  [in]           PDEVICE_OBJECT  PhysicalDeviceObject,
  [in]           const GUID      *InterfaceClassGuid,
  [in, optional] PUNICODE_STRING ReferenceString,
  [out]          PUNICODE_STRING SymbolicLinkName
);

Parámetros

[in] PhysicalDeviceObject

Puntero al PDO del dispositivo.

[in] InterfaceClassGuid

Puntero al GUID de clase que identifica la funcionalidad (la clase de interfaz de dispositivo) que se está registrando.

[in, optional] ReferenceString

Opcionalmente, apunta a un UNICODE_STRING. La cadena no debe contener caracteres separadores de ruta de acceso ("/" o "\"). Normalmente, los controladores de función especifican NULL para este parámetro. Los controladores de filtro deben especificar NULL.

Las cadenas de referencia solo las usan algunos controladores de autobús, como swenum, que es un controlador de autobús que usa instancias de interfaz de dispositivo como marcadores de posición para dispositivos de software creados a petición. Cuando se abre una instancia de una interfaz, el administrador de E/S pasa la cadena de referencia de la instancia al controlador. La cadena forma parte del nombre de la instancia de interfaz (como un componente de ruta de acceso anexado). A continuación, el controlador puede usar la cadena de referencia para diferenciar entre dos instancias de interfaz de la misma clase para un único dispositivo.

En los sistemas de Microsoft Windows 98/Me, el valor ReferenceString no puede tener más de MAX_PATH caracteres. No hay ningún límite de longitud en Windows 2000 y versiones posteriores de Windows.

[out] SymbolicLinkName

Puntero a una estructura de cadena Unicode asignada por el autor de la llamada. Si esta rutina se realiza correctamente, inicializa la cadena Unicode y asigna el búfer de cadena que contiene la ruta de acceso del modo kernel al vínculo simbólico de una instancia de la clase de interfaz de dispositivo especificada.

El autor de la llamada debe tratar SymbolicLinkName como opaco y no debe desensamblarlo.

El autor de la llamada es responsable de liberar SymbolicLinkName con RtlFreeUnicodeString cuando ya no es necesario.

Valor devuelto

IoRegisterDeviceInterface devuelve STATUS_SUCCESS si la llamada se realizó correctamente. Entre los valores devueltos de error posibles se incluyen los siguientes.

Código devuelto Descripción
STATUS_INVALID_DEVICE_REQUEST
 Los parámetros no son válidos. Entre las posibilidades se incluyen que PhysicalDeviceObject no apunta a un PDO válido o que la cadena ReferenceString contiene un carácter no válido.

Comentarios

IoRegisterDeviceInterface registra una clase de interfaz de dispositivo, si no se ha registrado previamente y crea una nueva instancia de la clase de interfaz. Un controlador puede llamar a esta rutina varias veces para que un dispositivo determinado registre varias clases de interfaz y cree instancias de las clases. Normalmente, un controlador de filtro o función registra interfaces de dispositivo en su rutina AddDevice . Por ejemplo, un controlador de volumen tolerante a errores podría registrar una instancia de una interfaz de volumen tolerante a errores y una instancia de una interfaz de volumen para un volumen determinado.

Si la clase de interfaz de dispositivo no se ha registrado anteriormente, el administrador de E/S crea una clave del Registro para ella, junto con el almacenamiento persistente específico de la instancia en la clave. Los controladores pueden acceder a este almacenamiento persistente mediante IoOpenDeviceInterfaceRegistryKey.

Un controlador registra una instancia de interfaz una vez y, a continuación, llama a IoSetDeviceInterfaceState para habilitar y deshabilitar la interfaz.

Las interfaces registradas se conservan en los reinicios del sistema operativo. Si la interfaz especificada ya está registrada, el administrador de E/S pasa su nombre en SymbolicLinkName y devuelve el estado de éxito informativo STATUS_OBJECT_NAME_EXISTS.

La mayoría de los controladores usan una cadena de referencia NULL para una instancia de interfaz de dispositivo. Si un controlador usa una cadena de referencia que no es NULL , debe realizar un trabajo adicional, incluida la administración posible de su propio espacio de nombres y seguridad. Un controlador de filtro que expone una interfaz de dispositivo debe usar referenceStringNULL para evitar conflictos con otros controladores de la pila de dispositivos.

No es necesario que los autores de llamadas de esta rutina quiten el registro de una interfaz de dispositivo cuando ya no sea necesario. Los registros de interfaz de dispositivo se pueden quitar del modo de usuario, si es necesario.

Los autores de llamadas de IoRegisterDeviceInterface deben ejecutarse en IRQL = PASSIVE_LEVEL en el contexto de un subproceso del sistema.

Requisitos

Requisito Value
Cliente mínimo compatible Disponible a partir de Windows 2000.
Plataforma de destino Universal
Encabezado wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
Archivo DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (consulte la sección Comentarios)
Reglas de cumplimiento de DDI HwStorPortProhibitedDIs(storport), IrqlIoPassive3(wdm), PowerIrpDDis(wdm)

Consulte también

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString