Methoden¶

ImportTar()/ImportTarEx() und ImportRaw()/ImportRawEx() importieren ein Plattenabbild und legen es im Abbildverzeichnis ab. Das erste Argument sollte ein Dateideskripter (zum Lesen geöffnet) sein, der sich auf die zu importierende Tar- oder rohe Datei bezieht. Es sollte eine Datei auf der Platte, eine Pipe oder ein Socket referenzieren. Wenn ImportTar()/ImportTarEx() verwandt wird, sollte sich der Dateideskriptor auf eine Tar-Datei, die optional mit gzip(1), bzip2(1) oder xz(1) komprimiert ist, beziehen. systemd-importd(8) wird automatisch das verwandte Komprimierungsschema (falls vorhanden) erkennen. Wenn ImportRaw()/ImportRawEx() verwandt wird, sollte sich der Dateideskriptor auf ein rohes oder qcow2-Plattenabbild beziehen, das optional mit gzip(1), bzip2(1) oder xz(1) komprimiert ist. In beiden Fällen wird Fortschrittsinformation für die Importaktion erstellt, falls die Datei als Dateideskriptor auf Platte festgelegt ist (da dann die Gesamtgröße auf Platte bekannt ist). Falls ein Socket oder eine Pipe festgelegt ist, ist keine Fortschrittsinformation verfügbar. Dem Dateideskriptorargument folgt ein lokaler Name für das Abbild. Dieser Name sollte für einen Rechnernamen geeignet sein und wird zur Benennung des importierten Abbildes unterhalb von /var/lib/machines/ verwandt. Ein Tar-Import wird als Verzeichnisbaum oder als ein btrfs(8)-Teildatenträger unterhalb des Abbild-Verzeichnisses unter dem festgelegten Namen ohne zusätzliche Erweiterung abgelegt. Ein roher Import wird als eine Datei im Abbildverzeichnis mit angehängter Endung .raw abgelegt. Im Falle von ImportTar()/ImportRaw() und falls das Argument force true ist, werden alle vorher bestehenden Abbilder mit dem gleichen Namen entfernt, bevor die Aktion gestartet wird. Andernfalls schlägt die Aktion fehl, falls ein Abbild mit dem gleichen Namen bereits existiert. Das Argument read_only steuert, ob ein schreibbares oder schreibgeschütztes Abbild erstellt wird. Im Falle von ImportTarEx()/ImportRawEx() werden diese logischen Schalter stattdessen mittels eines 64-bit-Schalterparameters bereitgestellt, wobei Bit 0 auf den Parameter force und Bit 1 auf read_only abgebildet ist. Der Parameter class legt die Abbildklasse fest und akzeptiert entweder »machine«, »portable«, »sysext« oder »confext«. Alle vier Methoden kehren direkt nach Start des Imports zurück, während die Importübertragung läuft. Sie liefern ein Paar von Übertragungskennzeichner und Objektpfad zurück, die zum Ermitteln von Fortschrittsinformationen über die Übertragung und zum Abbruch der Übertragung verwandt werden können. Der Übertragungskennzeichner ist ein einfacher numerischer Kennzeichner, der Objektpfad referenziert das Objekt org.freedesktop.import1.Transfer, siehe unten. Warten Sie auf ein Signal TransferRemoved() für die Übertragungskennung um zu erkennen, wenn eine Übertragung abgeschlossen ist. Das zurückgelieferte Übertragungsobjekt ist zur Bestimmung des aktuellen Fortschrittes oder zur Protokollausgabe der laufenden Importaktion nützlich.

ExportTar()/ExportTarEx() und ExportRaw()/ExportRaw() implementieren die umgekehrte Aktion und können zum Exportieren eines Systemabbildes verwandt werden, um es in ein Tar- oder rohes Abbild abzulegen. Sie akzeptieren den zu exportierenden Maschinennamen als ersten Parameter, gefolgt von einem (zum schreiben geöffneten) Dateideskriptor, wohin die Tar- oder rohe Datei geschrieben wird. Er kann entweder eine Datei auf der Platte oder eine Pipe/ein Socket referenzieren. Das dritte Argument legt das zu verwendende Kompressionsformat des Abbildes fest. Es akzeptiert entweder »uncompressed«, »xz«, »bzip2« oder »gzip«, abhängig vom benötigten Komprimierungsschema. Das in den angegebenen Dateideskriptor geschriebene Abbild wird im Falle von ExportTar()/ExportTarEx() eine Tar-Datei oder im Falle von ExportRaw()/ExportRawEx() eine rohe Datei sein. Beachten Sie, dass derzeit rohe Plattenabbilder nicht als Tar-Dateien (und umgekehrt) exportiert werden können. Diese Einschränkung könnte irgendwann aufgehoben werden. Die Methode liefert einen Übertragungs-Kennzeichner und einen Objektpfad zum Abbruch oder zum Nachverfolgen der Export-Aktion, ähnlich wie bei den oben beschriebenen ImportTar()/ImportTarEx() oder ImportRaw()/ImportRawEx(). ExportTarEx()/ExportRawEx() erwarten die Abbildklasse als zusätzlichen Parameter, sowie einen 64-bit-Schalterparameter, der derzeit als Null festgelegt sein muss.

PullTar()/PullTarEx() und PullRaw()/PullRawEx() können zum herunterladen, überprüfen und importieren eines Systemabbildes von einer URL verwandt werden. Sie akzeptieren ein URL-Argument, das auf eine Tar- oder rohe Datei unter dem Protokoll »http://« oder »https://« zeigen soll und möglicherweise mit gzip(1), bzip2(1) oder xz(1) komprimiert ist. Das zweite Argument ist ein lokaler Name für das Abbild. Es sollte als Rechnername, ähnlich wie bei dem entsprechenden Argument wie bei den oben beschriebenen Methoden ImportTar()/ImportTarEx() und ImportRaw()/ImportRawEx() geeignet sein. Das dritte Argument kennzeichnet die Überprüfungsmethode für das Abbild. Es kann entweder »no«, »checksum« oder »signature« sein. »no« schaltet jede Art von Überprüfung des Abbildes aus; »checksum« sucht nach einer SHA256SUM-Datei neben dem heruntergeladenen Abbild und überprüft jeden SHA256-Hash-Wert in dieser Datei gegen das Abbild; »signature« macht das Gleiche, versucht aber auch zuerst die SHA256SUM mittels gpg(8) zu authentifizieren. Im Falle von PullTar()/PullRaw() kennzeichnet das letzte Argument, ob ein möglicherweise bereits existierendes Abbild mit dem gleichen lokalen Namen ersetzt wird (falls »true«) oder ob ein Fehlschlag erfolgt (falls »false«). Im Falle von PullTarEx()/PullRawEx() ist das letzte Argument ein 64-bit-Schalter-Parameter, wobei Bit 0 den Schalter »force« steuert, Bit 1 ist ein »read_only«-Schalter, der steuert, ob das erstellte Abbild als schreibgeschützt markiert werden soll und Bit 2 ist ein »keep_download«-Schalter, der kennzeichnet, ob eine unverfälschte, schreibgeschützte Kopie des heruntergeladenen Abbildes zusätzlich zu der lokalen Kopie des Abbildes beibehalten werden soll. Die Varianten …_Ex() erwarten auch eine Abbildklassenzeichenkette (wie oben). Wie die oben beschriebenen Import- und Exportaufrufe liefern diese Aufrufe ein Paar an Übertragungskennzeichner und Objektpfad für die laufende Herunterladungen zurück.

ImportFileSystem()/ImportFileSystemEx() sind ähnlich zu ImportTar()/ImportTarEx(), importieren aber ein Verzeichnisbaum. Das erste Argument muss sich auf ein Verzeichnisdateideskriptor für die zu importierende Quell-Hierarchie beziehen.

ListTransfers()/ListTransfersEx() liefern eine Liste der laufenden Importe, Exporte oder Herunterlade-Aktionen, wie sie mit den sechs oben beschriebenen Aufrufen erstellt werden, zurück. Sie liefern ein Feld von Strukturen zurück, das aus dem numerischen Übertragungskennzeichner, einer Zeichenkette, die die Aktion bezeichnet (entweder »import-tar«, »import-raw«, »export-tar«, »export-raw«, »pull-tar« oder »pull-raw«), einer Zeichenkette, die die ferne Datei bezeichnet (im Falle von Herunterladeaktionen ist dies die Quell-URL, im Falle von Import-/Export-Aktionen ist dies eine kurze Zeichenkette, die den hereingereichten Dateideskriptor beschreibt), einer Zeichenkette mit dem lokalen Maschinennamen, der Abbildklasse (nur im Falle von ListTransfersEx(); entweder »machine«, »portable«, »sysext« oder »confext«), einem Fortschrittswert zwischen 0.0 (für 0%) und 1.0 (für 100%) sowie den Übertragungsobjektpfad besteht.

CancelTransfer() kann zum Abbruch einer laufenden Import-, Export- oder Herunterladeaktion verwandt werden. Es reicht die einfache Angabe des Übertragungskennzeichners, um die laufende Aktion abzubrechen.

ListImages() liefert eine Liste der derzeit installierten Abbilder zurück. Sie akzeptiert eine Abbildklassenzeichenkette und einen Schalter-Parameter. Die Abbildklasse ist entweder die leere Zeichenkette oder sie legt eine der vier Abbildklassen fest, nach der dann gefiltert wird. Der Schalter-Parameter muss derzeit Null sein. Sie liefert ein Feld von Einträgen, wobei jeder ein Abbild beschreibt. Die Eintragsfelder sind der Reihe nach: die Abbildklasse, der lokale Abbildname, der Abbildtyp, der Abbildpfad, der Schreibschutz-Schalter, die Erstellungs- und Veränderungszeiten (in Mikrosekunden seit der UNIX-Epoch) sowie der derzeitige Plattenverbrauch in Byte (sowohl gesamt als auch exklusiv), sowie alle Größenbegrenzungen in Byte, die für das Abbild gesetzt sind (sowohl gesamt als auch exklusiv).

Signale¶

Das Signal TransferNew() wird für jedes Auftreten des Starts einer neuen Übertragung mit den oben beschriebenen Import-, Export oder Herunterlade-Aufrufen erstellt. Es transportiert den frisch erstellten Übertragungskennzeichner und Objektpfad.

Das Signal TransferRemoved() wird für jedes Auftreten des Beendens, Abbruchs oder Fehlschlags einer Übertragung gesandt. Es transportiert auch den Übertragungskennzeichner und Objektpfad, gefolgt von einer Zeichenkette, die das Ergebnis der Aktion anzeigt. Diese ist entweder »done« (im Erfolgsfall), »canceled« (abgebrochen) oder »failed« (fehlgeschlagen).

Methoden¶

Die Methode Cancel() kann zum Abbruch der Übertragung verwandt werden. Sie akzeptiert keine Parameter. Diese Methode ist ziemlich ähnlich der Methode CancelTransfer() auf der Manager-Schnittstelle (siehe oben), wird aber auf dem Transfer-Objekt selbst offengelegt, anstatt eine Übertragungskennzeichnung zu akzeptieren.

Eigenschaften¶

Die Eigenschaft Id legt die numerische Übertragungskennzeichnung des Transfer-Objekts offen.

Die Eigenschaften Local, Remote und Type legen den lokalen Container-Namen dieser Übertragung offen, die ferne Quelle (im Falle vom Herunterladen: die URL, im Falle vom Im-/Export: eine Zeichenkette, die den hereingereichten Dateideskriptor beschreibt) und die Art der Aktion (siehe die obige Methode ListTransfer() des Managers für eine Erklärung der möglichen Werte).

Die Eigenschaft Verify legt die ausgewählte Überprüfungseinstellung offen und ist nur für die Herunterladeaktionen definiert (siehe oben).

Die Eingenschaft Progress legt den aktuellen Fortschritt der Übertragung als Wert zwischen 0.0 und 1.0 offen. Um einen Fortschrittsbalken auf dem Bildschirm darzustellen, wird die Abfrage des Wertes in regelmäßigen Abständen empfohlen, beispielsweise alle 500 ms oder so.

Signale¶

Das Signal LogMessage() wird für Protokollmeldungen ausgesandt, die durch eine Übertragung erstellt werden. Es transportiert ein Paar aus Syslog-Protokollstufen-Ganzzahl und Protokoll-Zeichenkette.

Das Signal ProgressUpdate() wird in regelmäßigen Abständen ausgesandt, wenn neue Herunterlade-Fortschrittsinformationen für eine Übertragung verfügbar sind. Es transportiert eine doppelt-genaue Fließkommazahl zwischen 0.0 und 1.0, die den Übertragungsfortschritt anzeigt.

Das Objekt »Manager«¶

ImportTarEx(), ImportRawEx(), ImportFileSystemEx(), ExportTarEx(), ExportRawEx(), PullTarEx(), PullRawEx(), ListTransfersEx(), ListImages() wurden in Version 256 hinzugefügt.

Übertragungsobjekte¶

ProgressUpdate() wurde in Version 256 hinzugefügt.