SetupInstallFileW-Funktion (setupapi.h)

Artikel
11/20/2024

[Diese Funktion steht für die Verwendung in den im Abschnitt "Anforderungen" angegebenen Betriebssystemen zur Verfügung. Sie kann in nachfolgenden Versionen geändert oder nicht verfügbar sein. 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 für die Installation von Gerätetreibern verwendet.]

Die SetupInstallFile--Funktion installiert eine Datei, die entweder durch eine INFCONTEXT- von SetupFindXXXLine oder explizit vom Dateinamen und Pfad zurückgegeben wird.

Wenn eine Datei kopiert wird, muss der Aufrufer dieser Funktion Schreibberechtigungen in das Zielverzeichnis besitzen.

Syntax

WINSETUPAPI BOOL SetupInstallFileW(
  [in] HINF                InfHandle,
  [in] PINFCONTEXT         InfContext,
  [in] PCWSTR              SourceFile,
  [in] PCWSTR              SourcePathRoot,
  [in] PCWSTR              DestinationName,
  [in] DWORD               CopyStyle,
  [in] PSP_FILE_CALLBACK_W CopyMsgHandler,
  [in] PVOID               Context
);

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- 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 "Dateien kopieren" in einer INF-Datei. Die Routine sucht diese Datei im Abschnitt "SourceDisksFiles" von InfHandle-, um Dateikopieinformationen 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" nachschlagen. Der SourceFile Parameter muss angegeben werden, wenn InfContext- nicht ist. SourceFile- wird ignoriert, wenn InfContext- angegeben wird.

[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 SP_COPY_SOURCE_ABSOLUTE Flag enthält.

[in] DestinationName

Optionaler Zeiger auf den Dateinamen (kein Pfad) der Zieldatei. Dieser Parameter kann null sein, um anzugeben, dass die Zieldatei denselben Namen wie die Quelldatei haben soll. Wenn InfContext- nicht angegeben ist, stellt DestinationName- den vollständigen Pfad und Dateinamen für das Ziel ein.

[in] CopyStyle

Flags, die das Verhalten des Dateikopievorgangs steuern. Diese Flags können eine Kombination aus den folgenden Werten sein.

Wert	Bedeutung
SP_COPY_DELETESOURCE	Löscht die Quelldatei nach erfolgreicher Kopie. Der Aufrufer wird nicht benachrichtigt, wenn der Löschvorgang fehlschlägt.
SP_COPY_REPLACEONLY	Kopiert die Datei nur, wenn dies geschieht, eine Datei im Zielpfad überschreiben würde. Wenn das Ziel nicht vorhanden ist, gibt die Funktion FALSE- zurück, und GetLastError- gibt NO_ERROR zurück.
SP_COPY_NEWER_OR_SAME	Überprüft jede Datei, die kopiert wird, um festzustellen, ob die Versionsressourcen angeben, dass sie entweder die gleiche Oder nicht neuer als eine vorhandene Kopie des Ziels ist. Die Dateiversionsinformationen, die bei Versionsüberprüfungen verwendet werden, sind die in der dwFileVersionMS und dwFileVersionLS Member einer VS_FIXEDFILEINFO Struktur angegeben, wie sie von den Versionsfunktionen ausgefüllt werden. Wenn eine der Dateien keine Versionsressourcen enthält oder identische Versionsinformationen enthalten, 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.
SP_COPY_NEWER_ONLY	Überprüfen Sie jede Datei, die kopiert wird, um festzustellen, ob die Versionsressourcen angeben, dass sie nicht neuer als eine vorhandene Kopie des Ziels ist. Wenn die Quelldatei neuer, aber nicht gleich der Version des vorhandenen Ziels ist, wird die Datei kopiert.
SP_COPY_NOOVERWRITE	Überprüfen Sie, ob die Zieldatei vorhanden ist, und benachrichtigen Sie in diesem Fall den Anrufer, der die Kopie veto kann. Wenn CopyMsgHandler nicht angegeben ist, wird die Datei nicht überschrieben.
SP_COPY_NODECOMP	Dekomprimieren Sie die Datei nicht. Wenn dieses Flag festgelegt ist, erhält die Zieldatei nicht die nicht komprimierte Form des Quellnamens (falls zutreffend). Beispielsweise führt das Kopieren von F:\x86\cmd.ex_ zu \\Installation\temp 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 Dateinameteil DestinationName, falls angegeben, wird entfernt und durch den Dateinamen der Quelldatei ersetzt. Wenn SP_COPY_NODECOMP angegeben ist, können keine Sprach- oder Versionsinformationen überprüft werden.
SP_COPY_LANGUAGEAWARE	Überprüfen Sie jede Datei, die kopiert wird, um festzustellen, ob sich ihre Sprache von der Sprache einer vorhandenen Datei unterscheidet, die sich bereits auf dem Ziel befindet. Wenn ja, und CopyMsgHandler angegeben ist, wird der Aufrufer benachrichtigt und kann die Kopie abbrechen. Wenn CopyMsgHandler nicht angegeben ist, wird die Datei nicht kopiert.
SP_COPY_SOURCE_ABSOLUTE	SourceFile- ist ein vollständiger Quellpfad. Suchen Sie sie nicht im Abschnitt "SourceDisksNames" der INF-Datei nach.
SP_COPY_SOURCEPATH_ABSOLUTE	SourcePathRoot- ist der vollständige Pfadteil der Quelldatei. Ignorieren Sie die relative Quelle, die im Abschnitt "SourceDisksNames" der INF-Datei für die Quellmedien angegeben ist, in der sich die Datei befindet. Dieses Kennzeichen wird ignoriert, wenn SP_COPY_SOURCE_ABSOLUTE angegeben wird.
SP_COPY_FORCE_IN_USE	Wenn das Ziel vorhanden ist, verhält es sich so, als ob es verwendet wird und die Datei zum Kopieren beim nächsten Systemneustart in die Warteschlange gestellt wird.
SP_COPY_FORCE_NOOVERWRITE	Überprüft, ob die Zieldatei vorhanden ist, und wenn ja, wird die Datei nicht überschrieben. Der Anrufer wird nicht benachrichtigt.
SP_COPY_FORCE_NEWER	Überprüft jede Datei, die kopiert wird, um festzustellen, ob ihre Versionsressourcen (oder Zeitstempel für Nicht-Bilddateien) angeben, dass sie nicht neuer als eine vorhandene Kopie des Ziels ist. Wenn die kopierte 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 Dateikopievorgangs auftreten können.

[in] Context

Optionaler Zeiger auf einen aufruferdefinierten 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 fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Wenn GetLastError- NO_ERROR zurückgibt, wurde der Dateikopievorgang nicht abgeschlossen. Die Datei wurde möglicherweise nicht kopiert, weil der Dateikopievorgang nicht erforderlich war oder weil die Dateirückruffunktion FALSEzurückgegeben wurde.

Bemerkungen

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 nicht, ob UNC-Verzeichnisse vorhanden sind oder erstellt werden. Wenn das UNC-Zielverzeichnis nicht vorhanden ist, schlägt die Dateiinstallation fehl.

Anmerkung

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
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	setupapi.h
Library	Setupapi.lib
DLL-	Setupapi.dll