Funzione SetupInstallFileA (setupapi.h)
[Questa funzione è disponibile per l'uso nei sistemi operativi indicati nella sezione Requisiti. È possibile che in versioni successive sia stata modificata o non sia più disponibile. SetupAPI non deve più essere usato per l'installazione di applicazioni. Usare invece Windows Installer per lo sviluppo di programmi di installazione di applicazioni. SetupAPI continua a essere usato per l'installazione dei driver di dispositivo.
La funzione SetupInstallFile installa un file come specificato da un INFCONTEXT restituito da SetupFindXXXLine o in modo esplicito dal nome e dal percorso del file.
Se viene copiato un file, il chiamante di questa funzione deve avere privilegi di scrittura nella directory di destinazione.
Sintassi
WINSETUPAPI BOOL SetupInstallFileA(
[in] HINF InfHandle,
[in] PINFCONTEXT InfContext,
[in] PCSTR SourceFile,
[in] PCSTR SourcePathRoot,
[in] PCSTR DestinationName,
[in] DWORD CopyStyle,
[in] PSP_FILE_CALLBACK_A CopyMsgHandler,
[in] PVOID Context
);
Parametri
[in] InfHandle
Puntatore facoltativo all'handle a un file INF che contiene le sezioni SourceDisksNames e SourceDisksFiles. Se esistono sezioni specifiche della piattaforma per il sistema dell'utente, ad esempio SourceDisksNames.x86 e SourceDisksFiles.x86, verrà usata la sezione specifica della piattaforma. Se InfContext è null e CopyStyle include SP_COPY_SOURCE_ABSOLUTE o SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle viene ignorato.
[in] InfContext
Puntatore facoltativo al contesto di una riga in una sezione Copia file in un file INF. La routine cerca questo file nella sezione SourceDisksFiles di InfHandle per ottenere informazioni sulla copia dei file. Se InfHandle non è specificato, SourceFile deve essere.
[in] SourceFile
Puntatore facoltativo al nome del file (nessun percorso) del file da copiare. Il file viene cercato nella sezione SourceDisksFiles. Il parametro SourceFile deve essere specificato se InfContext non è. SourceFile viene ignorato se viene specificato InfContext .
[in] SourcePathRoot
Puntatore facoltativo al percorso radice per la copia del file, ad esempio A:\ o F:). I percorsi nella sezione SourceDisksNames vengono aggiunti a questo percorso. Il parametro SourcePathRoot viene ignorato se CopyStyle include il flag di SP_COPY_SOURCE_ABSOLUTE.
[in] DestinationName
Puntatore facoltativo al nome del file solo (nessun percorso) del file di destinazione. Questo parametro può essere Null per indicare che il file di destinazione deve avere lo stesso nome del file di origine. Se InfContext non è specificato, DestinationName fornisce il percorso completo e il nome del file per la destinazione.
[in] CopyStyle
Contrassegna che controlla il comportamento dell'operazione di copia file. Questi flag possono essere una combinazione dei valori seguenti.
| Valore | Significato |
|---|---|
|
Elimina il file di origine al termine della copia completata. Il chiamante non riceve una notifica se l'operazione di eliminazione ha esito negativo. |
|
Copia il file solo se si esegue questa operazione sovrascrivere un file nel percorso di destinazione. Se la destinazione non esiste, la funzione restituisce FALSE e GetLastError restituisce NO_ERROR. |
|
Esamina ogni file copiato per verificare se le relative risorse di versione indicano che è la stessa versione o meno recente di una copia esistente nella destinazione.
Le informazioni sulla versione del file usate durante i controlli della versione sono specificate nei membri dwFileVersionMS e dwFileVersionLS di una struttura VS_FIXEDFILEINFO, come compilato dalle funzioni di versione. Se uno dei file non dispone di risorse di versione o se hanno informazioni sulla versione identiche, il file di origine viene considerato più recente. Se il file di origine non è più recente o uguale alla versione e CopyMsgHandler viene specificato, il chiamante riceve una notifica e può annullare l'operazione di copia. Se CopyMsgHandler non è specificato, il file non viene copiato. |
|
Esaminare ogni file copiato per verificare se le relative risorse di versione indicano che non è più recente di una copia esistente nella destinazione. Se il file di origine è più recente ma non uguale alla versione esistente, il file viene copiato. |
|
Verificare se il file di destinazione esiste e, in caso affermativo, avvisare il chiamante che può veto la copia. Se CopyMsgHandler non è specificato, il file non viene sovrascritto. |
|
Non decomprimere il file. Quando questo flag è impostato, il file di destinazione non viene dato il formato non compresso del nome di origine (se appropriato). Ad esempio, la copia di F:\x86\cmd.ex_ in \\install\temp genera un file di destinazione di \\install\temp\cmd.ex_. Se il flag SP_COPY_NODECOMP non è stato specificato, il file verrà decompresso e la destinazione verrà chiamata \\install\temp\cmd.exe. La parte del nome file di DestinationName, se specificata, viene rimossa e sostituita con il nome file del file di origine. Quando viene specificato SP_COPY_NODECOMP, non è possibile controllare alcuna lingua o informazioni sulla versione. |
|
Esaminare ogni file copiato per verificare se la lingua è diversa dalla lingua di qualsiasi file esistente già nella destinazione. In tal caso, e CopyMsgHandler viene specificato, il chiamante riceve una notifica e può annullare la copia. Se CopyMsgHandler non è specificato, il file non viene copiato. |
|
SourceFile è un percorso di origine completo. Non cercarlo nella sezione SourceDisksNames del file INF. |
|
SourcePathRoot è la parte completa del percorso del file di origine. Ignorare l'origine relativa specificata nella sezione SourceDisksNames del file INF per il supporto di origine in cui si trova il file. Questo flag viene ignorato se viene specificato SP_COPY_SOURCE_ABSOLUTE. |
|
Se la destinazione esiste, si comporta come se sia in uso e accoda il file per la copia nel riavvio del sistema successivo. |
|
Verifica se il file di destinazione esiste e, in caso affermativo, il file non viene sovrascritto. Il chiamante non riceve una notifica. |
|
Esamina ogni file copiato per verificare se le relative risorse di versione (o i timestamp per i file non immagine) indicano che non è più recente di una copia esistente nella destinazione. Se il file copiato non è più recente, il file non viene copiato. Il chiamante non riceve una notifica. La funzione restituisce FALSE e GetLastError restituisce NO_ERROR. |
[in] CopyMsgHandler
Puntatore facoltativo a una funzione di callback per ricevere una notifica di varie condizioni che possono verificarsi durante l'operazione di copia file.
[in] Context
Puntatore facoltativo a un valore definito dal chiamante passato come primo parametro della funzione di callback.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un valore diverso da zero.
Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Se GetLastError restituisce NO_ERROR, l'operazione di copia del file non è stata completata. Il file potrebbe non essere stato copiato perché l'operazione di copia del file non è necessaria o perché la funzione di callback del file ha restituito FALSE.
Commenti
Se una directory UNC viene specificata come directory di destinazione di un'installazione di file, è necessario assicurarsi che esista prima di chiamare SetupInstallFile. Le funzioni di installazione non controllano l'esistenza di né creare directory UNC. Se la directory UNC di destinazione non esiste, l'installazione del file avrà esito negativo.
Nota
L'intestazione setupapi.h definisce SetupInstallFile come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | setupapi.h |
| Libreria | Setupapi.lib |
| DLL | Setupapi.dll |