SetupQueueCopyW-Funktion (setupapi.h)

Artikel
08/26/2023

[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 SetupQueueCopy-Funktion fügt einer Setupdateiwarteschlange einen einzelnen Dateikopiervorgang hinzu.

Syntax

WINSETUPAPI BOOL SetupQueueCopyW(
  [in] HSPFILEQ QueueHandle,
  [in] PCWSTR   SourceRootPath,
  [in] PCWSTR   SourcePath,
  [in] PCWSTR   SourceFilename,
  [in] PCWSTR   SourceDescription,
  [in] PCWSTR   SourceTagfile,
  [in] PCWSTR   TargetDirectory,
  [in] PCWSTR   TargetFilename,
  [in] DWORD    CopyStyle
);

Parameter

[in] QueueHandle

Handle für eine Setupdateiwarteschlange, wie von SetupOpenFileQueue zurückgegeben.

[in] SourceRootPath

Zeiger auf eine NULL-endende Zeichenfolge, die den Stamm der Quelle für diese Kopie angibt, z. B. A:.

[in] SourcePath

Zeiger auf eine NULL-endende Zeichenfolge, die den Pfad relativ zu SourceRootPath angibt, in dem die Datei gefunden werden kann. Dieser Parameter kann NULL sein.

[in] SourceFilename

Zeiger auf eine NULL-endende Zeichenfolge, die den Dateinamenteil der zu kopierenden Datei angibt.

[in] SourceDescription

Zeiger auf eine NULL-endende Zeichenfolge, die eine Beschreibung des Quellmediums angibt, das bei Datenträgeraufforderungen verwendet werden soll. Dieser Parameter kann NULL sein.

[in] SourceTagfile

Zeiger auf eine NULL-endende Zeichenfolge, die eine Tagdatei angibt, deren Anwesenheit in SourceRootPath das Vorhandensein des Quellmediums angibt. Dieser Parameter kann NULL sein. Wenn nicht angegeben, wird die Datei selbst bei Bedarf als Tagdatei verwendet.

[in] TargetDirectory

Zeiger auf eine NULL-endende Zeichenfolge, die das Verzeichnis angibt, in das die Datei kopiert werden soll.

[in] TargetFilename

Zeiger auf eine NULL-endende Zeichenfolge, die den Namen der Zieldatei angibt. Dieser Parameter kann NULL sein. Wenn nicht angegeben, hat die Zieldatei den gleichen Namen wie die Quelldatei.

[in] CopyStyle

Gibt das Verhalten des Dateikopiervorgangs an. Dieser Parameter kann eine Kombination der folgenden Werte sein.

SP_COPY_DELETESOURCE

Löschen Sie die Quelldatei nach erfolgreichem Kopieren. Der Aufrufer wird nicht benachrichtigt, wenn beim Löschen ein Fehler auftritt.

SP_COPY_REPLACEONLY

Kopieren Sie die Datei nur, wenn dadurch eine Datei im Zielpfad überschrieben würde. Der Anrufer wird nicht benachrichtigt.

SP_COPY_NEWER_OR IDENTISCH

Überprüfen Sie jede datei, die kopiert wird, um festzustellen, ob die Versionsressourcen darauf hindeuten, 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 in der Version oder neuer nicht gleich ist 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_NEWER_ONLY

Ü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.

SP_COPY_NOOVERWRITE

Ü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.

SP_COPY_NODECOMP

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 flag SP_COPY_NODECOMP nicht angegeben wurde, wird die Datei dekomprimiert, und das Ziel wird \install\temp\cmd.exe aufgerufen. 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.

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 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.

SP_COPY_SOURCE_ABSOLUTE

SourceFile ist ein vollständiger Quellpfad. Suchen Sie ihn nicht im Abschnitt SourceDisksNames der INF-Datei.

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 das Quellmedium angegeben ist, auf dem sich die Datei befindet. Dieses Flag wird ignoriert, wenn SP_COPY_SOURCE_ABSOLUTE angegeben ist.

SP_COPY_FORCE_IN_USE

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.

SP_COPY_IN_USE_NEEDS_REBOOT

Wenn die Datei während des Kopiervorgangs verwendet wurde, benachrichtigen Sie den Benutzer, dass das System neu gestartet werden muss.

SP_COPY_NOSKIP

Geben Sie dem Benutzer nicht die Möglichkeit, eine Datei zu überspringen.

SP_COPY_FORCE_NOOVERWRITE

Überprüfen Sie, ob die Zieldatei vorhanden ist, und wenn ja, wird die Datei nicht überschrieben. Der Anrufer wird nicht benachrichtigt.

SP_COPY_FORCE_NEWER

Überprüfen Sie jede Datei, die kopiert wird, um festzustellen, ob ihre Versionsressourcen (oder Zeitstempel für Nicht-Imagedateien) darauf hindeuten, 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.

SP_COPY_WARNIFSKIP

Wenn der Benutzer versucht, eine Datei zu überspringen, warnt er, dass sich das Überspringen einer Datei auf die Installation auswirken kann. (Wird für systemkritische Dateien verwendet.)

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.

Hinweise

Wenn ein UNC-Verzeichnis als Zielverzeichnis eines Dateikopiervorgangs angegeben wird, müssen Sie sicherstellen, dass es vorhanden ist, bevor ein Commit für die Warteschlange ausgeführt wird. Die Setupfunktionen überprüfen nicht, ob UNC-Verzeichnisse vorhanden sind, und erstellen sie nicht. Wenn das UNC-Zielverzeichnis nicht vorhanden ist, schlägt die Dateikopie fehl.

Hinweis

Der Setupapi.h-Header definiert SetupQueueCopy 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