Funzione UpdateDriverForPlugAndPlayDevicesA (newdev.h)

Articolo
08/25/2023

Dato un file INF e un ID hardware, la funzione UpdateDriverForPlugAndPlayDevices installa i driver aggiornati per i dispositivi che corrispondono all'ID hardware.

Sintassi

BOOL UpdateDriverForPlugAndPlayDevicesA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR HardwareId,
  [in]            LPCSTR FullInfPath,
  [in]            DWORD  InstallFlags,
  [out, optional] PBOOL  bRebootRequired
);

Parametri

[in, optional] hwndParent

Handle della finestra di primo livello da usare per qualsiasi interfaccia utente correlata all'installazione dei dispositivi.

[in] HardwareId

Puntatore a una stringa con terminazione NULL che fornisce l'identificatore hardware per corrispondere ai dispositivi esistenti nel computer. La lunghezza massima di un identificatore hardware con terminazione NULL è MAX_DEVICE_ID_LEN. Per altre informazioni sugli identificatori hardware, vedere Stringhe di identificazione del dispositivo.

[in] FullInfPath

Puntatore a una stringa con terminazione NULL che fornisce il nome completo del file del percorso di un file INF. I file devono trovarsi nel supporto di distribuzione o in una directory creata dal fornitore, non in un percorso di sistema, ad esempio %SystemRoot%\inf. UpdateDriverForPlugAndPlayDevices copia i file driver nei percorsi di sistema appropriati se l'installazione ha esito positivo.

[in] InstallFlags

Valore fornito dal chiamante creato usando OR per combinare zero o più flag di bit seguenti:

INSTALLFLAG_FORCE

Se questo flag è impostato e la funzione trova un dispositivo che corrisponde al valore HardwareId , la funzione installa nuovi driver per il dispositivo se i driver migliori esistono già nel computer.

Importante Usare questo flag solo con estrema cautela. L'impostazione di questo flag può causare l'installazione di un driver precedente su un driver più recente, se un utente esegue l'applicazione del fornitore dopo che sono disponibili driver più recenti.

INSTALLFLAG_READONLY

Se questo flag è impostato, la funzione non copia, rinomina o elimina tutti i file di installazione. L'uso di questo flag deve essere limitato agli ambienti in cui l'accesso ai file è limitato o impossibile, ad esempio un sistema operativo "incorporato".

INSTALLFLAG_NONINTERACTIVE

Se questo flag è impostato, la funzione restituirà FALSE quando viene rilevato qualsiasi tentativo di visualizzazione dell'interfaccia utente. Impostare questo flag solo se la funzione verrà chiamata da un componente (ad esempio un servizio) che non può visualizzare l'interfaccia utente.

Nota Se questo flag è impostato e viene tentato un display dell'interfaccia utente, il dispositivo può essere lasciato in uno stato indeterminato.

Il parametro InstallFlags è in genere zero.

[out, optional] bRebootRequired

Puntatore a una variabile tipizzata BOOL che indica se è necessario un riavvio e chi deve richiederlo. Questo puntatore è facoltativo e può essere NULL.

Se il puntatore è NULL, UpdateDriverForPlugAndPlayDevices richiede un riavvio dopo l'installazione dei driver, se necessario. Se viene fornito il puntatore, la funzione restituisce un valore BOOLEAN true se il sistema deve essere riavviato. È quindi responsabilità del chiamante richiedere un riavvio.

Per altre informazioni, vedere la sezione Osservazioni seguenti.

Valore restituito

La funzione restituisce TRUE se un dispositivo è stato aggiornato al driver specificato.

In caso contrario, restituisce FALSE e l'errore registrato può essere recuperato con una chiamata a GetLastError. I valori di errore possibili restituiti da GetLastError sono inclusi nella tabella seguente.

Codice restituito	Descrizione
ERROR_FILE_NOT_FOUND	Il percorso specificato per FullInfPath non esiste.
ERROR_IN_WOW64	L'applicazione chiamante è un'applicazione a 32 bit che tenta di eseguire in un ambiente a 64 bit, che non è consentito.
ERROR_INVALID_FLAGS	Il valore specificato per InstallFlags non è valido.
ERROR_NO_SUCH_DEVINST	Il valore specificato per HardwareId non corrisponde a alcun dispositivo nel sistema. Ovvero, il dispositivo non è collegato.
ERROR_NO_MORE_ITEMS	La funzione ha trovato una corrispondenza per il valore HardwareId , ma il driver specificato non era una corrispondenza migliore del driver corrente e il chiamante non specificava il flag di INSTALLFLAG_FORCE.

Commenti

UpdateDriverForPlugAndPlayDevices analizza i dispositivi nel sistema e tenta di installare i driver specificati da FullInfPath per tutti i dispositivi che corrispondono al valore HardwareId specificato.

Il comportamento predefinito consiste nell'installare solo i driver specificati se corrispondono meglio dei driver attualmente installati e i driver specificati sono anche una corrispondenza migliore di qualsiasi driver in %SystemRoot%\inf. Per altre informazioni, vedere How Windows Selects Driver(How Windows Selects Drivers).

UpdateDriverForPlugAndPlayDevices può essere usato anche per determinare se il dispositivo con il valore HardwareId specificato è collegato. Per altre informazioni, vedere Scrittura di un'applicazione di installazione del dispositivo.

UpdateDriverForPlugAndPlayDevices invia una richiesta di IRP_MN_QUERY_REMOVE_DEVICE al dispositivo specificato, tutti gli elementi figlio del dispositivo e tutti gli altri dispositivi che fanno parte ricorsivamente delle relazioni di rimozione per il dispositivo. Se uno di questi dispositivi non riesce una richiesta di rimozione delle query, UpdateDriverForPlugAndPlayDevices imposta il flag di DI_NEEDREBOOT nel membro Flag della struttura SP_DEVINSTALL_PARAMS per il dispositivo. Per informazioni sulle relazioni di rimozione, vedere la richiesta di IRP_MN_QUERY_DEVICE_RELATIONS .

In genere, le applicazioni di installazione del dispositivo devono fornire NULL per bRebootRequired. Quindi, il sistema avvierà un riavvio se necessario. Un'applicazione deve specificare un valore puntatore solo nei casi seguenti:

L'applicazione deve chiamare UpdateDriverForPlugAndPlayDevices più volte per completare un'installazione.
L'applicazione deve eseguire altre operazioni prima del riavvio (se necessario).
L'applicazione è un programma di installazione della classe, che deve impostare DI_NEEDREBOOT in SP_DEVINSTALL_PARAMS se è necessario un riavvio.

Se l'applicazione deve chiamare UpdateDriverForPlugAndPlayDevices più volte, deve salvare qualsiasi valore di stato di riavvio TRUE ricevuto e quindi richiedere un riavvio dopo la restituzione della chiamata finale.

Se la funzione restituisce ERROR_IN_WOW64 in un'applicazione a 32 bit, l'applicazione viene eseguita in un sistema a 64 bit, che non è consentito. Per altre informazioni, vedere Installazione di dispositivi in sistemi a 64 bit.

Requisiti

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

Condividi tramite