Funzione SetupDiRegisterDeviceInfo (setupapi.h)
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.
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:
- 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.
- 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.
-
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.
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 |