CopyFile(src$, dst$[, t])

CopyFile(src$, dst$[, newname$, func, userdata, pattern$, matchdir])

Dieser Befehl ist mächtig. Es wird vollständig rekursiv alle Unterverzeichnisse erfassen und kopiert außerdem die Dateiattribute, Datumsstempel und Kommentare. Wenn das Zielverzeichnis nicht vorhanden ist, wird es für Sie erstellt werden (auch wenn es Verzeichnisse enthält, die noch nicht existieren). Alle Pfadangaben können lokal in das aktuelle Verzeichnis verweisen. Sie können somit auch Dateien in das aktuelle Verzeichnis kopieren, indem Sie "" als dst$ angeben.

CopyFile() unterstützt viele optionale Argumente. Vor Hollywood 9.0 mussten diese als optionale Parameter übergeben werden (siehe oben). Seit Hollywood 9.0 wird jedoch empfohlen, die neue Syntax zu verwenden, die ein einzelnes optionales Tabellenargument hat, mit dem ein oder mehrere optionale Argumente an CopyFile() übergeben werden können.

Die folgenden Tabellenfelder werden von diesem Befehl erkannt:

NewName:

Wenn Sie den Namen der Datei beim Kopieren ändern möchten, setzen Sie dieses Feld auf den gewünschten neuen Namen für die Datei. Das Setzen dieses Feldes ist natürlich nur sinnvoll, wenn Sie eine Datei in src$ angeben.

Pattern:

Sie können in diesem Tabellenfeld ein Filtermuster übergeben. In diesem Fall kopiert CopyFile() nur die Dateien, die dem angegebenen Muster entsprechen. Wenn Sie beispielsweise .jpg in Pattern angeben, werden nur Dateien kopiert, die die Dateierweiterung .jpg verwenden. Natürlich macht die Verwendung eines Filtermusters nur dann Sinn, wenn Sie ein Verzeichnis in src$ übergeben. Beachten Sie, dass aus historischen Gründen das in Pattern angegebene Muster auch mit allen zu kopierenden Unterverzeichnissen abgeglichen wird, die kopiert werden sollen. Wenn Sie das nicht möchten, setzen Sie das Tabellen-Tag MatchDir auf False (siehe unten). Das in Pattern angegebene Muster muss den Musterregeln entsprechen, die in der Dokumentation des Befehls MatchPattern() beschrieben sind. Siehe MatchPattern für Details. (V5.0)

MatchDir:

Dieses Tabellenfeld gibt an, ob das in Pattern angegebene Filtermuster auch mit Unterverzeichnissen abgeglichen werden soll oder nicht. Wenn dies auf True gesetzt ist, rekursiert CopyFile() nur in Unterverzeichnisse, die dem angegebenen Filtermuster entsprechen. Wenn es auf False gesetzt ist, rekursiert CopyFile() in alle Unterverzeichnisse. Aus Kompatibilitätsgründen ist MatchDir standardmäßig auf True gesetzt, aber meistens möchten Sie hier False übergeben, da es normalerweise keinen Sinn macht, ein Dateimuster mit einem Verzeichnisnamen abzugleichen. Es macht beispielsweise keinen Sinn, das obige Beispiel *.jpg auch mit Verzeichnissen abzugleichen. (V5.0)

BufferSize:

In diesem Tabellenfeld kann die Puffergröße eingestellt werden, die zum Kopieren von Dateien verwendet werden soll. Der hier übergebene Wert muss in Bytes angegeben werden. Der Standardwert ist 16384, also 16 Kilobyte. (V9.0)

FailOnError:

Standardmäßig schlägt CopyFile() fehl, wenn ein Fehler auftritt. Sie können dieses Verhalten ändern, indem Sie FailOnError auf False setzen. In diesem Fall schlägt CopyFile() bei einem Fehler nicht fehl, stattdessen wird Ihre Callback-Funktion, falls vorhanden, mit der Meldung #COPYFILE_FAILED benachrichtigt und Ihre Callback-Funktion muss CopyFile() mitteilen, wie es weitergeht (Wiederholen, Fortfahren, Abbrechen). Siehe unten, um zu erfahren, wie man eine Callback-Funktion für CopyFile() einrichtet. Die Voreinstellung für FailOnError ist True. (V9.0)

Force:

Wenn dieser Tag auf True gesetzt ist, werden schreib- oder löschgeschützte Dateien automatisch überschrieben, ohne vorher die Callback-Funktion abzufragen. Beachten Sie, dass CopyFile() fehlschlägt, wenn es keine Callback-Funktion gibt und Force auf False (Standard) gesetzt ist, wenn es eine Datei nicht überschreiben kann, da diese Datei schreib- oder löschgeschützt ist. Die Voreinstellung ist False. (V9.0)

Async:

Wenn dies auf True gesetzt ist, arbeitet CopyFile() im asynchronen Modus. Das bedeutet, dass der Befehl sofort zurückkehrt und falls Ihr Skript während des Vorgangs etwas anderes tun muss, Ihnen ein asynchroner Operationshandler übergibt. Sie können dann diesen asynchroner Operationshandler verwenden, um den Vorgang abzuschließen, indem Sie wiederholt ContinueAsyncOperation() aufrufen, bis True zurückgegeben wird. Dies ist sehr nützlich, z.B. für die Anzeige eines Fortschrittsbalken oder ähnlichem. Indem Sie CopyFile() in den asynchronen Modus versetzen, ist es Ihrem Skript leicht möglich, während der Verarbeitung des Vorgangs etwas anderes zu tun. Siehe ContinueAsyncOperation für Details. Voreingestellt ist False. (V9.0)

Adapter:

Mit diesem Tag können Sie ein oder mehrere Dateisystem-Adaptermodule angeben, welche die Quelldatei oder das Quellverzeichnis öffnen. Wenn Sie diesen Tag verwenden, müssen Sie ihn auf eine Zeichenkette setzen, die den Namen eines oder mehreren Adaptermodulen enthält. Standardmäßig wird das Adaptermodul verwendet, welches mit SetDefaultAdapter() gesetzt wurde. Siehe Lade- und Adaptermodule für Details. (V10.0)

UserTags:

Dieser Tag kann verwendet werden, um zusätzliche Daten anzugeben, die an das Datei-Adaptermodul übergeben werden sollen. Wenn Sie diesen Tag verwenden, müssen Sie ihn auf eine Tabelle mit Schlüssel-Wert-Paaren setzen, die die zusätzlichen Daten enthalten, die an Plugins übergeben werden sollen. Siehe Benutzer-Tags für Details. (V10.0)

DstAdapter:

Mit diesem Tag können Sie eines oder mehrere Dateisystem-Adaptermodule angeben, alle Operationen auf der Seite des Kopierziels auszuführen. Das hier angegebene Dateisystem-Adaptermodul ist beispielsweise für das Erstellen von Verzeichnissen und das Setzen von Datei- und Verzeichnisattributen zuständig. Dies muss auf eine Zeichenkette festgelegt werden, die den Namen eines oder mehreren Adaptermodulen enthält. Der Standardwert ist default. Siehe Lade- und Adaptermodule für Details. (V10.0)

DstUserTags:

Dieser Tag kann verwendet werden, um zusätzliche Daten anzugeben, die an Dateisystem-Adaptermodulen übergeben werden sollen, welche in DstAdapter angegeben sind. Siehe oben für Details. Wenn Sie diesen Tag verwenden, müssen Sie ihn auf eine Tabelle mit Schlüssel-Wert-Paaren setzen, die die zusätzlichen Daten enthalten, die an Plugins übergeben werden sollen. Siehe Benutzer-Tags für Details. (V10.0)

FileDst:

Wenn dieser Wert auf True gesetzt ist, betrachtet CopyFile() sein zweites Argument als gewünschte Zieldatei anstelle des Zielverzeichnisses. Das bedeutet natürlich, dass das Quellargument ebenfalls nur eine einzelne Datei sein darf. Außerdem darf das Tag NewName nicht verwendet werden, wenn FileDst auf True gesetzt ist, da in diesem Fall das zweite Argument offensichtlich bereits den neuen Namen enthält. Das Setzen dieses Tags auf True ist erforderlich, wenn CopyFile() unter Android mit einem SAF/MediaStore-Dateiziel verwendet wird, da diese Dateien in einem speziellen Format vorliegen und es oft nicht wirklich möglich ist, Pfad und Datei für SAF/MediaStore-Dateien separat anzugeben. Stattdessen liegen diese Dateien in einer einzigen URI vor. Beachten Sie, dass Sie, wenn Sie eine Datei in ein SAF/MediaStore-Dateiziel kopieren möchten, zunächst sicherstellen müssen, dass diese Datei erstellt wurde, indem Sie zuerst CreateFile() aufrufen. Siehe Arbeiten mit Android-URIs für Details. (V11.0)

Callback:

Dieses Tabellenfeld kann verwendet werden, um eine Callback-Funktion zu übergeben, die von CopyFile() bei verschiedenen Gelegenheiten aufgerufen wird, damit Sie beispielsweise einen Fortschrittsbalken aktualisieren können. Die Callback-Funktion wird auch aufgerufen, wenn bereits eine Zieldatei existiert oder sie schreib-/löschgeschützt ist. Die Callback-Funktion erhält ein Argument: Eine Tabelle, die weitere Informationen enthält.

Die folgenden Callback-Typen sind verfügbar:

#COPYFILE_OVERWRITE:

CopyFile() führt diesen Callback aus, um zu fragen, ob eine Datei überschrieben werden kann. Ihre Callback-Funktion muss True zurückgeben, wenn die Datei überschrieben werden soll oder False, wenn sie übersprungen werden soll. Um den Kopiervorgang vollständig abzubrechen, geben Sie -1 zurück. Die folgenden Felder werden im Tabellenparameter gesetzt, der an Ihre Callback-Funktion übergeben wird:

Action:

#COPYFILE_OVERWRITE

Source:

Enthält den vollständigen Pfad der zu kopierenden Datei.

Destination:

Enthält den vollständigen Pfad der Datei, die bereits vorhanden ist.

UserData:

Enthält den Wert, den Sie im Tabellenfeld UserData übergeben haben (siehe unten).

#COPYFILE_UNPROTECT:

Die Callback-Funktion vom Typ #COPYFILE_UNPROTECT wird aufgerufen, wenn die zu überschreibende Datei schreib- oder löschgeschützt ist. Diese Callback-Funktion muss True zurückgeben, wenn der Schutz der Datei aufgehoben werden kann, oder False, wenn sie übersprungen werden soll. Wenn Sie -1 zurückgeben, wird der Kopiervorgang vollständig abgebrochen.

Ab Hollywood 9.0 kann Ihre Callback-Funktion auch -2 zurückgeben, um anzugeben, dass das Kopieren trotzdem versucht werden soll, obwohl die Datei schreib- oder löschgeschützt ist. Dies führt jedoch in der Regel zu einem Fehler, da schreib- oder löschgeschützte Dateien nicht überschrieben werden können, ohne den Schutz zuvor aufzuheben. Wenn Sie jedoch -2 zurückgeben, können Sie den folgenden Fehler in Ihrem #COPYFILE_FAILED-Callback abfangen, wenn Sie FailOnError auf False gesetzt haben (siehe oben).

Die folgenden Felder werden im Tabellenparameter gesetzt, der an Ihre Callback-Funktion übergeben wird:

Action:

#COPYFILE_UNPROTECT

Destination:

Enthält die schreib- oder löschgeschützte Zieldatei, deren Schutz aufgehoben werden soll.

UserData:

Enthält den Wert, den Sie im Tabellenfeld UserData übergeben haben (siehe unten).

#COPYFILE_STATUS:

Diese Callback-Funktion wird von Zeit zu Zeit ausgeführt, damit Sie eine Statusleiste oder ähnliches aktualisieren können. Die Callback-Funktion vom Typ #COPYFILE_STATUS sollte normalerweise False zurückgeben. Wenn True zurückgegeben wird, wird der Kopiervorgang abgebrochen. Die folgenden Felder werden im Tabellenparameter gesetzt, der an Ihre Callback-Funktion übergeben wird:

Action:

#COPYFILE_STATUS

Source:

Enthält den vollständigen Pfad der Datei, die gerade kopiert wird (Quelle).

Destination:

Enthält den vollständigen Pfad der Datei, die gerade geschrieben wird (Ziel).

Copied:

Enthält die Anzahl der Bytes, die bereits kopiert wurden.

Filesize:

Enthält die Dateigröße der Quelldatei.

UserData:

Enthält den Wert, den Sie im Tabellenfeld UserData übergeben haben (siehe unten).

#COPYFILE_FAILED:

Dieser Callback kann nur aufgerufen werden, wenn der Tag FailOnError auf False gesetzt wurde (siehe oben). In diesem Fall wird die Callback-Funktion vom Typ #COPYFILE_FAILED immer dann aufgerufen, wenn ein Kopiervorgang fehlgeschlagen ist. Es muss True zurückgegeben werden, um den Kopiervorgang abzubrechen, False, um fortzufahren, obwohl ein Fehler aufgetreten ist, oder -1, um den gerade fehlgeschlagenen Kopiervorgang erneut zu versuchen. Die folgenden Felder werden im Tabellenparameter gesetzt, der an Ihre Callback-Funktion übergeben wird:

Action:

#COPYFILE_FAILED

Source:

Enthält den vollständigen Pfad der Datei, die gerade kopiert wird (Quelle).

Destination:

Enthält den vollständigen Pfad der Datei, die gerade geschrieben wird (Ziel).

UserData:

Enthält den Wert, den Sie im Tabellenfeld UserData übergeben haben (siehe unten).

(V9.0)

UserData:

Dieses Feld kann verwendet werden, um Ihrer Callback-Funktion einen beliebigen Wert zu übergeben. Der hier angegebene Wert wird bei jedem Aufruf an Ihre Callback-Funktion übergeben. Dies ist nützlich, wenn Sie vermeiden möchten, mit globalen Variablen zu arbeiten. Mit dem Tag UserData können Sie ganz einfach Daten an Ihre Callback-Funktion übergeben. Sie können in UserData einen beliebigen Wert beliebigen Typs angeben. Als Benutzerdaten können Zahlen, Zeichenketten, Tabellen und sogar Funktionen übergeben werden. Ihre Callback-Funktion erhält diese Daten im Feld UserData in der ihm übergebenen Tabelle. (V5.1)

Beachten Sie, dass beim Übergeben einer Android-Inhalts-URI im Quellargument es sich um eine einzelne Datei handeln muss. Das Kopieren von nicht leeren Verzeichnissen wird derzeit für Android-Inhalts-URIs nicht unterstützt. Beachten Sie auch die wichtigen Informationen, die in der Dokumentation des Tags FileDst oben beschrieben sind.

Siehe auch DeleteFile(), MoveFile(), Rename() und Exists().

src$

Die zu kopierende Quelldatei oder Verzeichnis

dst$

Zielverzeichnis

t

Optional: Tabelle mit zusätzlichen Optionen (siehe oben) (V9.0)

CopyFile("image.png", "TestDir")

CopyFile("Images", "Images_Bak")

CopyFile("Hollywood_Sources/WarpOS", "HW_BAK", {Pattern = "*.c;*.h",
    MatchDir = False})

Function p_CopyCallback(msg)
  Switch msg.action
  Case #COPYFILE_STATUS:
    DebugPrint("Now copying", FilePart(msg.source), "to",
               PathPart(msg.destination))
  Case #COPYFILE_OVERWRITE:
    Return(SystemRequest("Hollywood", FilePart(msg.destination) ..
      " does already exist!\nDo you want me to overwrite it?",
      "Yes|No"))
  Case #COPYFILE_UNPROTECT:
    Return(SystemRequest("Hollywood", FilePart(msg.destination) ..
      " is write/delete protected!\nDo you want me to unprotect it?",
      "Yes|No"))
  EndSwitch
  Return(False)
EndFunction
CopyFile("Images", "Copy_of_Images", {Callback = p_CopyCallback})