Condividi tramite


Funzione SetupInstallFileExA (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 delle applicazioni. SetupAPI continua a essere usato per l'installazione dei driver di dispositivo.

La funzione SetupInstallFileEx installa un file come specificato da un INFCONTEXT restituito da SetupFindXXXLine o in modo esplicito dalle informazioni sul nome file e sul percorso. Questa funzione è uguale a SetupInstallFile, ad eccezione del fatto che viene restituito un valore BOOL che indica se il file è in uso.

Se viene copiato un file, il chiamante di questa funzione deve disporre dei privilegi per la scrittura nella directory di destinazione.

Sintassi

WINSETUPAPI BOOL SetupInstallFileExA(
  [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,
  [out] PBOOL               FileWasInUse
);

Parametri

[in] InfHandle

Puntatore facoltativo all'handle in un file INF contenente le sezioni SourceDisksNames e SourceDisksFiles. Se esistono sezioni specifiche della piattaforma per il sistema dell'utente, ad esempio SourceDisksNames.x86 e SourceDisksFiles.x86, viene usata la sezione specifica della piattaforma. Se InfContext non è specificato e CopyStyle include SP_COPY_SOURCE_ABSOLUTE o SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle viene ignorato.

[in] InfContext

Puntatore facoltativo al contesto per 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 InfContext non è specificato, SourceFile deve essere.

[in] SourceFile

Puntatore facoltativo al nome file (nessun percorso) del file da copiare. Il file viene cercato nella sezione SourceDisksFiles. Il parametro SourceFile deve essere specificato se InfContext non è. Tuttavia, SourceFile viene ignorato se viene specificato InfContext .

[in] SourcePathRoot

Puntatore facoltativo al percorso radice per il file da copiare (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 SP_COPY_SOURCE_ABSOLUTE.

[in] DestinationName

Puntatore facoltativo a un nuovo nome per il file copiato. Se si specifica InfContext , DestinationName fornisce solo il nome file (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 di destinazione completo e il nome file per la destinazione.

[in] CopyStyle

Flag che controllano il comportamento dell'operazione di copia file.

Questi flag possono essere una combinazione dei valori seguenti.

Valore Significato
SP_COPY_DELETESOURCE
Eliminare il file di origine al termine della copia. Il chiamante non riceve una notifica se l'eliminazione non riesce.
SP_COPY_REPLACEONLY
Copiare il file solo se si esegue questa operazione sovrascrive un file nel percorso di destinazione.
SP_COPY_NEWER_OR_SAME
Esaminare ogni file copiato per verificare se le relative risorse di versione indicano che si tratta della 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 specificato dalle funzioni della versione. Se uno dei file non dispone di risorse di versione o se dispone di 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 viene specificato CopyMsgHandler , il chiamante riceve una notifica e può annullare la copia. Se CopyMsgHandler non viene specificato, il file non viene copiato.

SP_COPY_NEWER_ONLY
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 della destinazione esistente, il file viene copiato.
SP_COPY_NOOVERWRITE
Controllare se il file di destinazione esiste e, in tal caso, inviare una notifica al chiamante che può assegnare il veto alla copia. Se CopyMsgHandler non viene specificato, il file non viene sovrascritto.
SP_COPY_NODECOMP
Non decomprimere il file. Quando questo flag è impostato, al file di destinazione non viene assegnato 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 "\\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 si specifica SP_COPY_NODECOMP, non è possibile controllare alcuna lingua o informazioni sulla versione.
SP_COPY_LANGUAGEAWARE
Esaminare ogni file copiato per verificare se la lingua è diversa dalla lingua di qualsiasi file esistente già presente nella destinazione. In tal caso, e viene specificato CopyMsgHandler , il chiamante riceve una notifica e può annullare la copia. Se CopyMsgHandler non viene specificato, il file non viene copiato.
SP_COPY_SOURCE_ABSOLUTE
SourceFile è un percorso di origine completo. Non cercarlo nella sezione SourceDisksNames del file INF.
SP_COPY_SOURCEPATH_ABSOLUTE
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.
SP_COPY_FORCE_IN_USE
Se la destinazione esiste, si comporta come se fosse in uso e accoda il file per la copia al successivo riavvio del sistema.
SP_COPY_IN_USE_NEEDS_REBOOT
Se il file era in uso durante l'operazione di copia, avvisare l'utente che il sistema richiede un riavvio.
SP_COPY_NOSKIP
Non concedere all'utente la possibilità di ignorare un file.
SP_COPY_FORCE_NOOVERWRITE
Controllare se il file di destinazione esiste e, in tal caso, il file non viene sovrascritto. Il chiamante non riceve una notifica.
SP_COPY_FORCE_NEWER
Esaminare ogni file copiato per verificare se le relative risorse di versione (o timestamp per i file non di 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.
SP_COPY_WARNIFSKIP
Se l'utente tenta di ignorare un file, avvisarlo che l'omissione di un file può influire sull'installazione. Usato per i file critici del sistema.

[in] CopyMsgHandler

Puntatore facoltativo a una funzione di callback per ricevere una notifica di varie condizioni che possono verificarsi durante la copia del file.

[in] Context

Puntatore a un valore definito dal chiamante passato come primo parametro della funzione di callback.

[out] FileWasInUse

Puntatore a una variabile in cui questa funzione restituisce un flag che indica se il file era in uso. Questo parametro è obbligatorio.

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 file non è stata completata. Il file potrebbe non essere stato copiato perché l'operazione di copia file non è necessaria o perché la funzione di callback del file ha restituito FALSE.

Commenti

Questa API viene in genere usata durante l'installazione di nuove versioni dei file di sistema che potrebbero essere in uso. Aggiorna un valore BOOL che indica se il file era in uso. Se il file era in uso, l'operazione di copia file viene posticipata fino al riavvio del sistema.

Se una directory UNC viene specificata come directory di destinazione di un'installazione di file, è necessario assicurarsi che esista prima di chiamare SetupInstallFileEx. Le funzioni di installazione non controllano l'esistenza di e non creano directory UNC. Se la directory UNC di destinazione non esiste, l'installazione del file non riesce.

Nota

L'intestazione setupapi.h definisce SetupInstallFileEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

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

Vedi anche

Funzioni

Panoramica

SetupCloseFileQueue

SetupCommitFileQueue

SetupInstallFile

SetupOpenFileQueue

SetupPromptReboot

SetupQueueCopy