SetupInstallFileExA-Funktion (setupapi.h)
[Diese Funktion ist für die Verwendung in den Betriebssystemen verfügbar, die im Abschnitt "Anforderungen" angegeben sind. Es kann in nachfolgenden Versionen geändert oder entfernt werden. SetupAPI sollte nicht mehr für die Installation von Anwendungen verwendet werden. Verwenden Sie stattdessen den Windows Installer zum Entwickeln von Anwendungsinstallationsprogrammen. SetupAPI wird weiterhin zum Installieren von Gerätetreibern verwendet.]
Die SetupInstallFileEx-Funktion installiert eine Datei, die entweder durch einen von SetupFindXXXLine zurückgegebenen INFCONTEXT oder explizit durch den Dateinamen und die Pfadinformationen angegeben wird. Diese Funktion ist identisch mit SetupInstallFile, mit der Ausnahme, dass ein BOOL zurückgegeben wird, der angibt, ob die Datei verwendet wurde.
Wenn eine Datei kopiert wird, muss der Aufrufer dieser Funktion über Berechtigungen zum Schreiben in das Zielverzeichnis verfügen.
Syntax
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
);
Parameter
[in] InfHandle
Optionaler Zeiger auf das Handle auf eine INF-Datei, die die Abschnitte SourceDisksNames und SourceDisksFiles enthält. Wenn plattformspezifische Abschnitte für das System des Benutzers vorhanden sind (z. B. SourceDisksNames.x86 und SourceDisksFiles.x86), wird der plattformspezifische Abschnitt verwendet. Wenn InfContext nicht angegeben ist und CopyStyle SP_COPY_SOURCE_ABSOLUTE oder SP_COPY_SOURCEPATH_ABSOLUTE enthält, wird InfHandle ignoriert.
[in] InfContext
Optionaler Zeiger auf den Kontext für eine Zeile in einem Abschnitt Dateien kopieren in einer INF-Datei. Die Routine sucht diese Datei im Abschnitt SourceDisksFiles von InfHandle , um Dateikopieinformationen abzurufen. Wenn InfContext nicht angegeben ist, muss SourceFile sein.
[in] SourceFile
Optionaler Zeiger auf den Dateinamen (kein Pfad) der zu kopierenden Datei. Die Datei wird im Abschnitt SourceDisksFiles gesucht. Der SourceFile-Parameter muss angegeben werden, wenn InfContext dies nicht ist. SourceFile wird jedoch ignoriert, wenn InfContext angegeben ist.
[in] SourcePathRoot
Optionaler Zeiger auf den Stammpfad für die zu kopierende Datei (z. B. A:\ oder F:). Pfade im Abschnitt SourceDisksNames werden an diesen Pfad angefügt. Der SourcePathRoot-Parameter wird ignoriert, wenn CopyStyle das flag SP_COPY_SOURCE_ABSOLUTE enthält.
[in] DestinationName
Optionaler Zeiger auf einen neuen Namen für die kopierte Datei. Wenn InfContext angegeben ist, gibt DestinationName nur den Dateinamen (kein Pfad) der Zieldatei an. Dieser Parameter kann NULL sein, um anzugeben, dass die Zieldatei den gleichen Namen wie die Quelldatei haben soll. Wenn InfContext nicht angegeben ist, gibt DestinationName den vollständigen Zielpfad und dateinamen für das Ziel an.
[in] CopyStyle
Flags, die das Verhalten des Dateikopiervorgangs steuern.
Diese Flags können eine Kombination der folgenden Werte sein.
| Wert | Bedeutung |
|---|---|
|
Löschen Sie die Quelldatei nach erfolgreicher Kopie. Der Aufrufer wird nicht benachrichtigt, wenn beim Löschen ein Fehler auftritt. |
|
Kopieren Sie die Datei nur, wenn dadurch eine Datei im Zielpfad überschrieben wird. |
|
Untersuchen Sie jede kopierte Datei, um festzustellen, ob ihre Versionsressourcen darauf hinweisen, dass es sich entweder um dieselbe Version oder nicht um eine neuere Version als eine vorhandene Kopie auf dem Ziel handelt.
Die bei Versionsüberprüfungen verwendeten Dateiversionsinformationen sind die in den Membern dwFileVersionMS und dwFileVersionLS einer VS_FIXEDFILEINFO Struktur angegeben, die von den Versionsfunktionen ausgefüllt werden. Wenn eine der Dateien keine Versionsressourcen enthält oder identische Versionsinformationen enthält, wird die Quelldatei als neuer betrachtet. Wenn die Quelldatei nicht neuer oder gleich version ist und CopyMsgHandler angegeben ist, wird der Aufrufer benachrichtigt und kann die Kopie abbrechen. Wenn CopyMsgHandler nicht angegeben ist, wird die Datei nicht kopiert. |
|
Überprüfen Sie jede kopierte Datei, um festzustellen, ob ihre Versionsressourcen darauf hinweisen, dass sie nicht neuer als eine vorhandene Kopie auf dem Ziel ist. Wenn die Quelldatei neuer ist, aber in der Version des vorhandenen Ziels nicht gleich ist, wird die Datei kopiert. |
|
Überprüfen Sie, ob die Zieldatei vorhanden ist, und benachrichtigen Sie in diesem Fall den Aufrufer, der möglicherweise ein Veto gegen die Kopie einlegt. Wenn CopyMsgHandler nicht angegeben ist, wird die Datei nicht überschrieben. |
|
Dekomprimieren Sie die Datei nicht. Wenn dieses Flag festgelegt ist, erhält die Zieldatei nicht die unkomprimierte Form des Quellnamens (falls zutreffend). Das Kopieren von "f:\x86\cmd.ex_" in "\\install\temp" führt beispielsweise zu einer Zieldatei mit "\\install\temp\cmd.ex_". Wenn das SP_COPY_NODECOMP-Flag nicht angegeben wurde, würde die Datei dekomprimiert und das Ziel "\\install\temp\cmd.exe" genannt. Der Dateiname-Teil von DestinationName wird, sofern angegeben, entfernt und durch den Dateinamen der Quelldatei ersetzt. Wenn SP_COPY_NODECOMP angegeben ist, können keine Sprach- oder Versionsinformationen überprüft werden. |
|
Überprüfen Sie jede kopierte Datei, um festzustellen, ob sich ihre Sprache von der Sprache einer vorhandenen Datei unterscheidet, die bereits auf dem Ziel vorhanden ist. Wenn dies der Grund ist und CopyMsgHandler angegeben ist, wird der Aufrufer benachrichtigt und kann die Kopie abbrechen. Wenn CopyMsgHandler nicht angegeben ist, wird die Datei nicht kopiert. |
|
SourceFile ist ein vollständiger Quellpfad. Suchen Sie es nicht im Abschnitt SourceDisksNames der INF-Datei. |
|
SourcePathRoot ist der vollständige Pfadteil der Quelldatei. Ignorieren Sie die relative Quelle, die im Abschnitt SourceDisksNames der INF-Datei für das Quellmedium angegeben ist, in dem sich die Datei befindet. Dieses Flag wird ignoriert, wenn SP_COPY_SOURCE_ABSOLUTE angegeben ist. |
|
Wenn das Ziel vorhanden ist, verhalten Sie sich so, als ob es verwendet wird, und stellen Sie die Datei zum Kopieren beim nächsten Systemneustart in die Warteschlange. |
|
Wenn die Datei während des Kopiervorgangs verwendet wurde, benachrichtigen Sie den Benutzer, dass das System neu gestartet werden muss. |
|
Geben Sie dem Benutzer nicht die Möglichkeit, eine Datei zu überspringen. |
|
Überprüfen Sie, ob die Zieldatei vorhanden ist, und wenn ja, wird die Datei nicht überschrieben. Der Anrufer wird nicht benachrichtigt. |
|
Überprüfen Sie jede kopierte Datei, um festzustellen, ob ihre Versionsressourcen (oder Zeitstempel für Nicht-Bilddateien) darauf hinweisen, dass sie nicht neuer als eine vorhandene Kopie auf dem Ziel ist. Wenn die kopierte Datei nicht neuer ist, wird die Datei nicht kopiert. Der Anrufer wird nicht benachrichtigt. |
|
Wenn der Benutzer versucht, eine Datei zu überspringen, warnen Sie, dass sich das Überspringen einer Datei auf die Installation auswirken kann. (Wird für systemkritische Dateien verwendet.) |
[in] CopyMsgHandler
Optionaler Zeiger auf eine Rückruffunktion, um über verschiedene Bedingungen informiert zu werden, die während der Dateikopie auftreten können.
[in] Context
Zeiger auf einen vom Aufrufer definierten Wert, der als erster Parameter der Rückruffunktion übergeben wird.
[out] FileWasInUse
Zeiger auf eine Variable, in der diese Funktion ein Flag zurückgibt, das angibt, ob die Datei verwendet wurde. Dieser Parameter ist erforderlich.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Nichtzero-Wert.
Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Wenn GetLastError NO_ERROR zurückgibt, wurde der Dateikopiervorgang nicht abgeschlossen. Die Datei wurde möglicherweise nicht kopiert, weil der Dateikopiervorgang nicht erforderlich war oder weil die Dateirückruffunktion FALSE zurückgegeben hat.
Hinweise
Diese API wird in der Regel verwendet, wenn neue Versionen von Systemdateien installiert werden, die wahrscheinlich verwendet werden. Es aktualisiert einen BOOL-Wert , der angibt, ob die Datei verwendet wurde. Wenn die Datei verwendet wurde, wird der Dateikopiervorgang verschoben, bis das System neu gestartet wird.
Wenn ein UNC-Verzeichnis als Zielverzeichnis einer Dateiinstallation angegeben wird, müssen Sie sicherstellen, dass es vorhanden ist, bevor Sie SetupInstallFileEx aufrufen. Die Setupfunktionen überprüfen nicht, ob UNC-Verzeichnisse vorhanden sind, und erstellen sie nicht. Wenn das UNC-Zielverzeichnis nicht vorhanden ist, schlägt die Dateiinstallation fehl.
Hinweis
Der setupapi.h-Header definiert SetupInstallFileEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | setupapi.h |
| Bibliothek | Setupapi.lib |
| DLL | Setupapi.dll |