Función SetupDiRegisterDeviceInfo (setupapi.h)

  • Artículo

La función SetupDiRegisterDeviceInfo es el controlador predeterminado para la solicitud de DIF_REGISTERDEVICE .

Sintaxis

WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
  [in]            HDEVINFO           DeviceInfoSet,
  [in, out]       PSP_DEVINFO_DATA   DeviceInfoData,
  [in]            DWORD              Flags,
  [in, optional]  PSP_DETSIG_CMPPROC CompareProc,
  [in, optional]  PVOID              CompareContext,
  [out, optional] PSP_DEVINFO_DATA   DupDeviceInfoData
);

Parámetros

[in] DeviceInfoSet

Identificador de un conjunto de información de dispositivo que contiene un elemento de información del dispositivo que representa el dispositivo que se va a registrar. El conjunto de información del dispositivo no debe contener ningún elemento remoto.

[in, out] DeviceInfoData

Puntero a una estructura de SP_DEVINFO_DATA que especifica el elemento de información del dispositivo en DeviceInfoSet. Se trata de un parámetro IN-OUT porque DeviceInfoData.DevInst puede actualizarse con un nuevo valor de identificador al devolverlo.

[in] Flags

Valor de marca que controla cómo se registra el dispositivo, que puede ser cero o el siguiente valor:

SPRDI_FIND_DUPS

Busque una instancia de dispositivo existente que corresponda al dispositivo representado por DeviceInfoData. Si no se especifica esta marca, la instancia del dispositivo se registra independientemente de si ya existe una instancia de dispositivo para ella.

Si el autor de la llamada proporciona CompareProc, el autor de la llamada también debe establecer esta marca.

[in, optional] CompareProc

Puntero a una función de devolución de llamada de comparación que se va a usar en la detección de duplicados. Este parámetro es opcional y puede ser NULL. Si se especifica este parámetro, se llama a la función de devolución de llamada para cada instancia de dispositivo que sea de la misma clase que la instancia de dispositivo que se está registrando. El prototipo de la función de devolución de llamada es el siguiente:

typedef  DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
    IN HDEVINFO  DeviceInfoSet,
    IN PSP_DEVINFO_DATA  NewDeviceData,
    IN PSP_DEVINFO_DATA  ExistingDeviceData,
    IN PVOID  CompareContextOPTIONAL
    );

La función compare debe devolver ERROR_DUPLICATE_FOUND si encuentra que los dos dispositivos son duplicados. De lo contrario, debe devolver NO_ERROR. Si se encuentra algún otro error, la función de devolución de llamada debe devolver el código de ERROR_* adecuado para indicar el error.

Si no se especifica CompareProc y se solicita la detección de duplicación, se usa un comportamiento de comparación predeterminado. El valor predeterminado es comparar la firma de detección del nuevo dispositivo con la firma de detección de todos los demás dispositivos de la clase . La firma de detección se encuentra en el descriptor de recursos específico de la clase de la configuración del registro de arranque del dispositivo.

[in, optional] CompareContext

Puntero a un búfer de contexto proporcionado por el autor de la llamada que se pasa a la función de devolución de llamada. Este parámetro se omite si no se especifica CompareProc .

[out, optional] DupDeviceInfoData

Puntero a una estructura de SP_DEVINFO_DATA para recibir información sobre una instancia de dispositivo duplicada, si existe, detectada como resultado de intentar registrar este dispositivo. Este parámetro es opcional y puede ser NULL. Si se especifica este parámetro, el autor de la llamada debe establecer DupDeviceInfoData.cbSize a sizeof(SP_DEVINFO_DATA). Se rellenará si la función devuelve FALSE y GetLastError devuelve ERROR_DUPLICATE_FOUND. Este elemento de información del dispositivo se agrega como miembro del DeviceInfoSet especificado, si aún no es miembro. Si no se especifica DupDeviceInfoData , el duplicado no se agrega al conjunto de información del dispositivo.

Si llama a esta función al controlar una solicitud de DIF_REGISTERDEVICE , el parámetro DupDeviceInfoData debe ser NULL.

Valor devuelto

La función devuelve TRUE si se realiza correctamente. De lo contrario, devuelve FALSE y el error registrado se puede recuperar con una llamada a GetLastError.

Comentarios

SetupDiRegisterDeviceInfo está diseñado principalmente para registrar un dispositivo que no es PnP con el administrador de Plug and Play (PnP) en un equipo local. Aunque SetupDiRegisterDeviceInfo no producirá un error si el conjunto de información del dispositivo es para un equipo remoto, el resultado es de uso limitado porque el conjunto de información del dispositivo no se puede usar posteriormente con DIF_Xxx solicitudes de instalación o funciones SetupDiXxx que no admiten operaciones en un equipo remoto. Por ejemplo, al llamar a SetupDiCreateDevRegKey para ejecutar una sección INF para un dispositivo recién registrado en un equipo remoto, se producirá un error.

Nota Solo un instalador de clase debe llamar a SetupDiRegisterDeviceInfo y solo en aquellas situaciones en las que el instalador de clase debe realizar operaciones de registro de dispositivos después de que SetupDiRegisterDeviceInfo complete la operación de registro de dispositivos predeterminada. En tales situaciones, el instalador de clase debe llamar directamente a SetupDiRegisterDeviceInfo cuando el instalador procesa una solicitud de DIF_REGISTERDEVICE. Para obtener más información sobre cómo llamar al controlador predeterminado, vea Llamar a controladores de código DIF predeterminados.
 
Después de registrar un elemento de información del dispositivo, el autor de la llamada debe actualizar las copias almacenadas del identificador de DevInst asociado a este dispositivo. Esto es necesario porque es posible que el valor del identificador haya cambiado durante el registro. El autor de la llamada no tiene que recuperar de nuevo la estructura de SP_DEVINFO_DATA porque el campo DevInst de la estructura se actualiza para reflejar el valor actual del identificador.

No llame directamente a esta función para instancias de dispositivo PnP. El sistema operativo registra automáticamente las instancias de dispositivo PnP. Sin embargo, debe registrar instancias de dispositivo que no son PnP de una de las maneras siguientes:

  1. Si la aplicación de instalación usa una solicitud de DIF_DETECT para detectar correctamente un dispositivo, también debe usar una solicitud de DIF_REGISTERDEVICE para registrar la instancia del dispositivo. La solicitud debe controlarse de forma predeterminada. (De forma predeterminada, SetupDiCallClassInstaller llama primero al instalador de clase y a los coinstaladores de clase para realizar la detección de duplicados y registrar la instancia del dispositivo. Si estos instaladores no registran la instancia del dispositivo, SetupDiCallClassInstaller llama a SetupDiRegisterDeviceInfo para realizar la detección duplicada y registrar la instancia del dispositivo).
  2. Si la aplicación de instalación crea una instancia de dispositivo (por ejemplo, llamando a SetupDiCreateDeviceInfo), pero no realiza la detección de duplicados, la aplicación de instalación debe usar una solicitud de DIF_REGISTERDEVICE para registrar la instancia del dispositivo. La solicitud se debe controlar de forma predeterminada, como se ha descrito anteriormente.
  3. Si la aplicación de instalación crea un nuevo dispositivo y realiza la detección de duplicados, la aplicación de instalación debe usar una solicitud de DIF_REGISTERDEVICE, pero debe impedir que SetupDiCallClassInstaller llame a SetupDiRegisterDeviceInfo. Para evitar que SetupDiCallClassInstaller llame a SetupDiRegisterDeviceInfo, establezca la marca de DI_NODI_DEFAULTACTION en el miembro Flags de la estructura de SP_DEVINSTALL_PARAMS para la instancia del dispositivo.

    Si SetupDiCallClassInstaller devuelve TRUE para la solicitud de DIF_REGISTERDEVICE, el instalador de clase o los coinstaladores de clase registraron la instancia del dispositivo. En este caso, la aplicación de instalación puede seguir instalando el dispositivo.

    Si SetupDiCallClassInstaller devuelve FALSE para la solicitud de DIF_REGISTERDEVICE, los instaladores de clase o coinstaladores de clase no registraron la instancia del dispositivo. En este caso, la aplicación de instalación debe realizar una de las siguientes acciones, dependiendo del último error que GetLastError devuelve para la solicitud:

    • Si el último error es ERROR_DI_DO_DEFAULT, la aplicación de instalación puede llamar directamente a SetupDiRegisterDeviceInfo y proporcionar un CompareProc para realizar la detección de duplicados. Si esta llamada se realiza correctamente y no se encuentra ningún duplicado, la instalación del dispositivo puede continuar. Si se encuentra un duplicado, SetupDiRegisterDeviceInfo devuelve FALSE y la aplicación de instalación debe finalizar la instalación del dispositivo.
    • Si el último error no es ERROR_DI_DO_DEFAULT, la aplicación de instalación debe finalizar la instalación del dispositivo.
    El autor de la llamada de SetupDiRegisterDeviceInfo debe ser miembro del grupo Administradores.

Requisitos

Requisito Value
Cliente mínimo compatible Disponible en Microsoft Windows 2000 y versiones posteriores de Windows.
Plataforma de destino Escritorio
Encabezado setupapi.h (incluya Setupapi.h)
Library Setupapi.lib
Archivo DLL Setupapi.dll

Consulte también

DIF_REGISTERDEVICE

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS