IPS_GetSnapshotDiff

 string IPS_GetSnapshotDiff (string $Hash) 

Parameterliste

Rückgabewert

Ein JSON-kodierter String. Ist Hash bekannt, enthält er die Unterschiede als JSON Patch (Array), andernfalls den vollständigen Snapshot (Objekt) mit dem zusätzlichen Eintrag hash. Über die JSON-RPC Schnittstelle wird das Ergebnis direkt als Array bzw. Objekt geliefert.

Beschreibung

Diese Funktion ist nur für den internen Gebrauch vorgesehen und kann sich jederzeit ohne Ankündigung ändern oder entfallen.

Die Funktion ermittelt den aktuellen Snapshot wie IPS_GetSnapshot und berechnet dessen Hash (CRC32 über den JSON-kodierten Snapshot, als hexadezimaler String in Großbuchstaben, z.B. "2ADC9D3C"). Der aktuelle Snapshot wird unter diesem Hash zwischengespeichert, damit er beim nächsten Aufruf als Grundlage dienen kann.

• Ist unter Hash ein zwischengespeicherter Snapshot vorhanden, liefert die Funktion die Unterschiede zwischen diesem und dem aktuellen Snapshot als JSON Patch nach RFC 6902. Das ist ein Array von Operationen mit den Feldern op (z.B. "add", "remove", "replace"), path und ggf. value. Der neue Hash ist in der Operation für den Pfad "/hash" enthalten.
• Andernfalls, z.B. beim ersten Aufruf mit einem leeren String oder nach einem Neustart von IP-Symcon, liefert sie den vollständigen Snapshot mit dem zusätzlichen Eintrag hash.

Ein Client kann die beiden Fälle daran unterscheiden, ob ein Array oder ein Objekt geliefert wird.

Jeder Hash kann nur einmal verwendet werden, da der zugehörige Snapshot nach der Berechnung der Unterschiede verworfen wird. Ist der Snapshot unverändert, ist der JSON Patch leer und der Hash bleibt gleich. Da er aber bereits verwendet wurde, liefert der nächste Aufruf mit diesem Hash wieder den vollständigen Snapshot.

Es werden höchstens 10 Snapshots zwischengespeichert, Snapshots älter als 24 Stunden werden verworfen. Verwenden mehrere Clients die Funktion, können Snapshots daher verdrängt werden. Der Client erhält dann wieder den vollständigen Snapshot.

Ist der Spezialschalter "DebugDisableSnapshot" aktiv, schlägt die Funktion mit "This function is disabled for debugging purposes!" fehl.

Beispiel

// Erster Aufruf mit unbekanntem Hash: liefert den vollständigen Snapshot inkl. Hash
$snapshot = json_decode(IPS_GetSnapshotDiff(''), true);
$hash = $snapshot['hash'];

// ... später: nur die Unterschiede als JSON Patch abrufen
$patch = json_decode(IPS_GetSnapshotDiff($hash), true);
foreach ($patch as $operation) {
    echo $operation['op'] . ' ' . $operation['path'] . "\n";
    // Den neuen Hash für den nächsten Aufruf merken
    if ($operation['path'] == '/hash') {
        $hash = $operation['value'];
    }
}

/* liefert z.B.:
replace /hash
replace /objects/ID12345/data/lastChange
replace /objects/ID12345/data/lastUpdate
replace /objects/ID12345/data/value
replace /timestamp
*/