SetupInstallFileA-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 zum Installieren von Anwendungen verwendet werden. Verwenden Sie stattdessen den Windows Installer zum Entwickeln von Installationsprogrammen für Anwendungen. SetupAPI wird weiterhin zum Installieren von Gerätetreibern verwendet.]
Die SetupInstallFile-Funktion installiert eine Datei, die entweder durch einen von SetupFindXXXLine zurückgegebenen INFCONTEXT oder explizit durch den Dateinamen und Pfad angegeben wird.
Wenn eine Datei kopiert wird, muss der Aufrufer dieser Funktion über Schreibberechtigungen in das Zielverzeichnis verfügen.
Syntax
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
);
Parameter
[in] InfHandle
Optionaler Zeiger auf das Handle zu einer 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 NULL ist und CopyStyle SP_COPY_SOURCE_ABSOLUTE oder SP_COPY_SOURCEPATH_ABSOLUTE enthält, wird InfHandle ignoriert.
[in] InfContext
Optionaler Zeiger auf den Kontext einer Zeile in einem Abschnitt zum Kopieren von Dateien in einer INF-Datei. Die Routine sucht diese Datei im Abschnitt SourceDisksFiles von InfHandle , um Dateikopierinformationen abzurufen. Wenn InfHandle 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 nicht angegeben ist. SourceFile wird 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 nur auf den Dateinamen (kein Pfad) der Zieldatei. Dieser Parameter kann NULL sein, um anzugeben, dass die Zieldatei den gleichen Namen wie die Quelldatei haben soll. Wenn InfContext nicht angegeben ist, stellt DestinationName den vollständigen Pfad und Dateinamen für das Ziel bereit.
[in] CopyStyle
Flags, die das Verhalten des Dateikopiervorgangs steuern. Diese Flags können eine Kombination der folgenden Werte sein.
| Wert | Bedeutung |
|---|---|
|
Löscht die Quelldatei nach erfolgreichem Kopieren. Der Aufrufer wird nicht benachrichtigt, wenn der Löschvorgang fehlschlägt. |
|
Kopiert die Datei nur, wenn dadurch eine Datei im Zielpfad überschrieben würde. Wenn das Ziel nicht vorhanden ist, gibt die Funktion FALSE und GetLastError NO_ERROR zurück. |
|
Untersucht jede datei, die kopiert wird, um festzustellen, ob die 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 nicht über Versionsressourcen verfügt oder identische Versionsinformationen enthält, wird die Quelldatei als neuer betrachtet. Wenn die Quelldatei nicht neuer oder gleich der Version ist und CopyMsgHandler angegeben ist, wird der Aufrufer benachrichtigt und kann den Kopiervorgang abbrechen. Wenn CopyMsgHandler nicht angegeben ist, wird die Datei nicht kopiert. |
|
Überprüfen Sie jede datei, die kopiert wird, um festzustellen, ob die Versionsressourcen darauf hinweisen, dass sie nicht neuer als eine vorhandene Kopie auf dem Ziel ist. Wenn die Quelldatei neuer, aber nicht gleich der Version des vorhandenen Ziels ist, wird die Datei kopiert. |
|
Überprüfen Sie, ob die Zieldatei vorhanden ist, und benachrichtigen Sie den Aufrufer, der möglicherweise ein Veto gegen die Kopie hat. 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_ nach \\install\temp führt beispielsweise zu einer Zieldatei von \\install\temp\cmd.ex_. Wenn das SP_COPY_NODECOMP-Flag nicht angegeben wurde, wird die Datei dekomprimiert, und das Ziel wird \\install\temp\cmd.exeaufgerufen. Der Dateiname-Teil von DestinationName wird 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 Datei, die kopiert wird, 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 ihn 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, auf dem sich die Datei befindet. Dieses Flag wird ignoriert, wenn SP_COPY_SOURCE_ABSOLUTE angegeben ist. |
|
Wenn das Ziel vorhanden ist, verhält sich so, als ob es verwendet wird, und stellt die Datei zum Kopieren beim nächsten Systemneustart in die Warteschlange. |
|
Überprüft, ob die Zieldatei vorhanden ist, und wenn ja, wird die Datei nicht überschrieben. Der Anrufer wird nicht benachrichtigt. |
|
Untersucht jede datei, die kopiert wird, um festzustellen, ob ihre Versionsressourcen (oder Zeitstempel für Nicht-Imagedateien) darauf hinweisen, dass sie nicht neuer als eine vorhandene Kopie auf dem Ziel ist. Wenn die zu kopierende Datei nicht neuer ist, wird die Datei nicht kopiert. Der Anrufer wird nicht benachrichtigt. Die Funktion gibt FALSE zurück, und GetLastError gibt NO_ERROR zurück. |
[in] CopyMsgHandler
Optionaler Zeiger auf eine Rückruffunktion, um über verschiedene Bedingungen benachrichtigt zu werden, die während des Dateikopiervorgangs auftreten können.
[in] Context
Optionaler Zeiger auf einen vom Aufrufer definierten Wert, der als erster Parameter der Rückruffunktion übergeben wird.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Wert ungleich null.
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 unnötig war oder weil die Dateirückruffunktion FALSE zurückgegeben hat.
Hinweise
Wenn ein UNC-Verzeichnis als Zielverzeichnis einer Dateiinstallation angegeben ist, müssen Sie sicherstellen, dass es vorhanden ist, bevor Sie SetupInstallFile aufrufen. Die Setupfunktionen überprüfen weder, ob UNC-Verzeichnisse vorhanden sind, noch erstellen sie sie. Wenn das UNC-Zielverzeichnis nicht vorhanden ist, schlägt die Dateiinstallation fehl.
Hinweis
Der Header setupapi.h definiert SetupInstallFile 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 Code, der nicht Codierungsneutral ist, 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 |