Funzione SetupDiRegisterDeviceInfo (setupapi.h)

  • Articolo

La funzione SetupDiRegisterDeviceInfo è il gestore predefinito per la richiesta di DIF_REGISTERDEVICE .

Sintassi

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
);

Parametri

[in] DeviceInfoSet

Handle per un set di informazioni sul dispositivo che contiene un elemento informazioni sul dispositivo che rappresenta il dispositivo da registrare. Il set di informazioni sul dispositivo non deve contenere elementi remoti.

[in, out] DeviceInfoData

Puntatore a una struttura SP_DEVINFO_DATA che specifica l'elemento informazioni sul dispositivo in DeviceInfoSet. Si tratta di un parametro IN-OUT perché DeviceInfoData.DevInst potrebbe essere aggiornato con un nuovo valore handle al momento della restituzione.

[in] Flags

Valore del flag che controlla la modalità di registrazione del dispositivo, che può essere zero o il valore seguente:

SPRDI_FIND_DUPS

Cercare un'istanza del dispositivo esistente in precedenza corrispondente al dispositivo rappresentato da DeviceInfoData. Se questo flag non viene specificato, l'istanza del dispositivo viene registrata indipendentemente dal fatto che esista già un'istanza del dispositivo.

Se il chiamante fornisce CompareProc, il chiamante deve anche impostare questo flag.

[in, optional] CompareProc

Puntatore a una funzione di callback di confronto da usare nel rilevamento duplicato. Questo parametro è facoltativo e può essere NULL. Se questo parametro viene specificato, la funzione di callback viene chiamata per ogni istanza del dispositivo che corrisponde alla stessa classe dell'istanza del dispositivo da registrare. Il prototipo della funzione di callback è il seguente:

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

La funzione di confronto deve restituire ERROR_DUPLICATE_FOUND se rileva che i due dispositivi sono duplicati. In caso contrario, deve restituire NO_ERROR. Se viene rilevato un altro errore, la funzione di callback deve restituire il codice ERROR_* appropriato per indicare l'errore.

Se CompareProc non è specificato e viene richiesto il rilevamento della duplicazione, viene usato un comportamento di confronto predefinito. L'impostazione predefinita consiste nel confrontare la firma di rilevamento del nuovo dispositivo con la firma di rilevamento di tutti gli altri dispositivi nella classe . La firma di rilevamento è contenuta nel descrittore di risorse specifico della classe della configurazione del log di avvio del dispositivo.

[in, optional] CompareContext

Puntatore a un buffer di contesto fornito dal chiamante passato alla funzione di callback. Questo parametro viene ignorato se CompareProc non è specificato.

[out, optional] DupDeviceInfoData

Puntatore a una struttura SP_DEVINFO_DATA per ricevere informazioni su un'istanza del dispositivo duplicata, se presente, individuata come risultato del tentativo di registrare il dispositivo. Questo parametro è facoltativo e può essere NULL. Se questo parametro viene specificato, il chiamante deve impostare DupDeviceInfoData.cbSize a sizeof(SP_DEVINFO_DATA). Verrà compilato se la funzione restituisce FALSE e GetLastError restituisce ERROR_DUPLICATE_FOUND. Questo elemento di informazioni sul dispositivo viene aggiunto come membro dell'oggetto DeviceInfoSet specificato, se non è già un membro. Se DupDeviceInfoData non viene specificato, il duplicato non viene aggiunto al set di informazioni sul dispositivo.

Se si chiama questa funzione quando si gestisce una richiesta di DIF_REGISTERDEVICE , il parametro DupDeviceInfoData deve essere NULL.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce TRUE . In caso contrario, restituisce FALSE e l'errore registrato può essere recuperato con una chiamata a GetLastError.

Commenti

SetupDiRegisterDeviceInfo è progettato principalmente per registrare un dispositivo non PnP con il gestore di Plug and Play (PnP) in un computer locale. Anche se SetupDiRegisterDeviceInfo non riuscirà se il set di informazioni sul dispositivo è per un computer remoto, il risultato è limitato perché il set di informazioni sul dispositivo non può essere usato successivamente con le richieste di installazione DIF_Xxx o le funzioni SetupDiXxx che non supportano le operazioni in un computer remoto. Ad esempio, la chiamata a SetupDiCreateDevRegKey per eseguire una sezione INF per un dispositivo appena registrato in un computer remoto avrà esito negativo.

Nota Solo un programma di installazione di classe deve chiamare SetupDiRegisterDeviceInfo e solo in quelle situazioni in cui il programma di installazione della classe deve eseguire operazioni di registrazione del dispositivo dopo che SetupDiRegisterDeviceInfo completa l'operazione di registrazione predefinita del dispositivo. In tali situazioni, il programma di installazione della classe deve chiamare direttamente SetupDiRegisterDeviceInfo quando il programma di installazione elabora una richiesta di DIF_REGISTERDEVICE. Per altre informazioni sulla chiamata al gestore predefinito, vedere Chiamata di gestori di codice DIF predefiniti.
 
Dopo la registrazione di un elemento informazioni sul dispositivo, il chiamante deve aggiornare tutte le copie archiviate dell'handle DevInst associato al dispositivo. Ciò è necessario perché il valore dell'handle potrebbe essere stato modificato durante la registrazione. Il chiamante non deve recuperare di nuovo la struttura SP_DEVINFO_DATA perché il campo DevInst della struttura viene aggiornato in modo da riflettere il valore corrente dell'handle.

Non chiamare direttamente questa funzione per le istanze del dispositivo PnP. Le istanze del dispositivo PnP vengono registrate automaticamente dal sistema operativo. Tuttavia, è necessario registrare istanze del dispositivo non PnP in uno dei modi seguenti:

  1. Se l'applicazione di installazione usa una richiesta di DIF_DETECT per rilevare correttamente un dispositivo, deve usare anche una richiesta di DIF_REGISTERDEVICE per registrare l'istanza del dispositivo. La richiesta deve essere gestita nel modo predefinito. Per impostazione predefinita, SetupDiCallClassInstaller chiama innanzitutto il programma di installazione della classe e i coinstallazioni di classe per eseguire il rilevamento duplicati e registrare l'istanza del dispositivo. Se questi programmi di installazione non registrano l'istanza del dispositivo, SetupDiCallClassInstaller chiama SetupDiRegisterDeviceInfo per eseguire il rilevamento duplicato e registrare l'istanza del dispositivo.
  2. Se l'applicazione di installazione crea un'istanza del dispositivo,ad esempio chiamando SetupDiCreateDeviceInfo, ma non esegue il rilevamento duplicati, l'applicazione di installazione deve usare una richiesta di DIF_REGISTERDEVICE per registrare l'istanza del dispositivo. La richiesta deve essere gestita nel modo predefinito, come descritto in precedenza.
  3. Se l'applicazione di installazione crea un nuovo dispositivo ed esegue il rilevamento dei duplicati, l'applicazione di installazione deve usare una richiesta di DIF_REGISTERDEVICE, ma deve impedire a SetupDiCallClassInstaller di chiamare SetupDiRegisterDeviceInfo. Per impedire a SetupDiCallClassInstaller di chiamare SetupDiRegisterDeviceInfo, impostare il flag di DI_NODI_DEFAULTACTION nel membro Flags della struttura SP_DEVINSTALL_PARAMS per l'istanza del dispositivo.

    Se SetupDiCallClassInstaller restituisce TRUE per la richiesta di DIF_REGISTERDEVICE, il programma di installazione della classe o i coinstallazioni di classe hanno registrato l'istanza del dispositivo. In questo caso, l'applicazione di installazione può continuare a installare il dispositivo.

    Se SetupDiCallClassInstaller restituisceFALSE per la richiesta di DIF_REGISTERDEVICE, il programma di installazione della classe o i coinstallazioni di classe non hanno registrato l'istanza del dispositivo. In questo caso, l'applicazione di installazione deve eseguire una delle operazioni seguenti, a seconda dell'ultimo errore restituito da GetLastError per la richiesta:

    • Se l'ultimo errore è ERROR_DI_DO_DEFAULT, l'applicazione di installazione può chiamare direttamente SetupDiRegisterDeviceInfo e fornire compareProc per eseguire il rilevamento duplicati. Se questa chiamata ha esito positivo e non vengono trovati duplicati, l'installazione del dispositivo può continuare. Se viene trovato un duplicato, SetupDiRegisterDeviceInfo restituisce FALSE e l'applicazione di installazione deve terminare l'installazione del dispositivo.
    • Se l'ultimo errore non è ERROR_DI_DO_DEFAULT, l'applicazione di installazione deve terminare l'installazione del dispositivo.
    Il chiamante di SetupDiRegisterDeviceInfo deve essere membro del gruppo Administrators.

Requisiti

Requisito Valore
Client minimo supportato Disponibile in Microsoft Windows 2000 e versioni successive di Windows.
Piattaforma di destinazione Desktop
Intestazione setupapi.h (include Setupapi.h)
Libreria Setupapi.lib
DLL Setupapi.dll

Vedi anche

DIF_REGISTERDEVICE

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS