« Back to Product

Documentation

Send feedback!

IPS_GetSnapshotDiff

 string IPS_GetSnapshotDiff (string $Hash)

Parameters

Hash

Hash of the snapshot the client already has. For an unknown hash (e.g. an empty string) the complete snapshot is returned

Returns

A JSON-encoded string. If Hash is known, it contains the differences as JSON Patch (array), otherwise the complete snapshot (object) with the additional entry hash. Via the JSON-RPC interface the result is returned directly as an array or object.

Description

Warning

This function is intended for internal use only and may change or be removed at any time without notice.

The function determines the current snapshot like IPS_GetSnapshot and calculates its hash (CRC32 of the JSON-encoded snapshot, as a hexadecimal string in upper case, e.g. "2ADC9D3C"). The current snapshot is cached under this hash so that it can serve as the base for the next call.

  • If a cached snapshot exists for Hash, the function returns the differences between it and the current snapshot as JSON Patch according to RFC 6902. This is an array of operations with the fields op (e.g. "add", "remove", "replace"), path and, if applicable, value. The new hash is contained in the operation for the path "/hash".
  • Otherwise, e.g. on the first call with an empty string or after a restart of IP-Symcon, it returns the complete snapshot with the additional entry hash.

A client can distinguish the two cases by whether an array or an object is returned.

Every hash can only be used once, as the associated snapshot is discarded after the differences have been calculated. If the snapshot is unchanged, the JSON Patch is empty and the hash stays the same. As it has already been used, however, the next call with this hash returns the complete snapshot again.

At most 10 snapshots are cached, snapshots older than 24 hours are discarded. If several clients use the function, snapshots can therefore be displaced. The client then receives the complete snapshot again.

If the special switch "DebugDisableSnapshot" is active, the function fails with "This function is disabled for debugging purposes!".

Example

// First call with an unknown hash: returns the complete snapshot including the hash
$snapshot = json_decode(IPS_GetSnapshotDiff(''), true);
$hash = $snapshot['hash'];

// ... later: retrieve only the differences as JSON Patch
$patch = json_decode(IPS_GetSnapshotDiff($hash), true);
foreach ($patch as $operation) {
    echo $operation['op'] . ' ' . $operation['path'] . "\n";
    // Remember the new hash for the next call
    if ($operation['path'] == '/hash') {
        $hash = $operation['value'];
    }
}

/* e.g. returns:
replace /hash
replace /objects/ID12345/data/lastChange
replace /objects/ID12345/data/lastUpdate
replace /objects/ID12345/data/value
replace /timestamp
*/
Any questions?