« Back to Product

Documentation

Send feedback!

IPS_GetSnapshot

 string IPS_GetSnapshot ()

Returns

The snapshot as a JSON-encoded string. Via the JSON-RPC interface it is returned directly as an object.

Description

Warning

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

Warning

The structure of the snapshot may change between versions of IP-Symcon.

The function returns the complete current state of IP-Symcon, the so-called snapshot. It is based on the saved settings (settings.json) and is enriched with runtime information. Clients initialize themselves with it and afterwards follow the changes via messages.

Among others, the snapshot contains the following entries:

Key Description
timestamp Number of the last message included in the snapshot. Starting from this number, the following changes can be retrieved with IPS_GetSnapshotChanges
timezone Time zone of the server in IANA format (e.g. "Europe/Berlin"). This allows clients e.g. to render graphs in the time zone of the server
language System language of IP-Symcon (e.g. "de-DE")
server Information about the server: version, revision, platform, architecture, date and starttime
license Information about the license: licensee, edition, limits (demo, variables, webfront, server, features) and expiration (demo, subscription)
options All special switches with their current, pending and default value
compatibility Version and date of the server (version, date). Only present for compatibility reasons
objects All objects. The key is "ID" followed by the ObjectID (e.g. "ID12345"). The type-specific data is located under data
profiles All variable profiles. readOnly is TRUE for system profiles (name starts with "~")
templates All templates for presentations

Further entries of the saved settings, e.g. sync or permissions, are included unchanged.

Every object under objects contains its general properties (e.g. name, ident, parentID, position, type) as well as the summary. Depending on the object type, runtime information is added under data: status and visualizationType for instances, isLocked, profile and customProfile for variables, crc and size for scripts, nextRun for events and crc, size and isAvailable for media.

The snapshot is returned as uncompressed JSON. Via HTTP the response is compressed with gzip if the client specifies this in the "Accept-Encoding" header.

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

Example

// Retrieve the snapshot and output some information
$snapshot = json_decode(IPS_GetSnapshot(), true);
echo "Last message: " . $snapshot['timestamp'] . "\n";
echo "Time zone: " . $snapshot['timezone'] . "\n";
echo "Objects: " . count($snapshot['objects']) . "\n";
echo "Profiles: " . count($snapshot['profiles']) . "\n";

// Objects are stored under "ID" followed by the ObjectID
print_r($snapshot['objects']['ID12345']);

/* e.g. returns:
Last message: 990
Time zone: Europe/Berlin
Objects: 166
Profiles: 111
Array
(
    [data] => Array
        (
            [action] => 54227
            [customAction] => 0
            [customPresentation] => Array
                (
                )

            [customProfile] =>
            [isLocked] =>
            [lastChange] => 1789241479
            [lastUpdate] => 1790080547
            [presentation] => Array
                (
                    [MAX] => 254
                    [MIN] => 1
                    [PERCENTAGE] => 1
                    [PRESENTATION] => {6B9CAEEC-5958-C223-30F7-BD36569FC57A}
                    [SUFFIX] =>  %
                    [USAGE_TYPE] => 2
                )

            [profile] =>
            [type] => 1
            [value] => 254
        )

    [disabled] =>
    [hidden] =>
    [hiddenMaximize] =>
    [hiddenTitle] =>
    [icon] =>
    [ident] => Brightness
    [info] =>
    [name] => Brightness
    [parentID] => 23456
    [position] => 0
    [readOnly] =>
    [summary] =>
    [type] => 2
)
*/
Any questions?