« Back to Product

Documentation

Send feedback!

IPS_GetSnapshotChanges

 string IPS_GetSnapshotChanges (int $LastTimestamp)

Parameters

LastTimestamp

Number of the last known message (timestamp from the snapshot or TimeStamp of the last received message)

Returns

A JSON-encoded array with all messages after LastTimestamp in ascending order. Via the JSON-RPC interface it is returned directly as an array.

Description

Warning

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

Warning

This function is planned to be removed in the future, once the old iOS/Android apps are no longer in use and IPSView has switched to WebSockets. Changes should be received via the WebSocket interface instead, see Data exchange.

The function returns all messages that occurred after the message with the number LastTimestamp. Clients that initialized themselves with IPS_GetSnapshot can thereby keep their state up to date by polling regularly, see Snapshots.

For this purpose IP-Symcon stores the last messages in a ring buffer. Every message receives a consecutive number (TimeStamp). Despite its name, this is not a point in time but a counter that restarts on every start of IP-Symcon. The size of the ring buffer is defined by the special switch "MessageRingBufferSize" (default: 8192 messages).

Every entry of the array contains the following fields:

Field Type Description
TimeStamp integer Consecutive number of the message
SenderID integer ID of the object that sent the message (0 for the kernel)
Message integer ID of the message, see messages
Data array Data of the message. Structure and number depend on the respective message

If LastTimestamp equals the number of the most recent message, the function returns an empty array. If LastTimestamp is 0, it returns only the most recent message.

The following errors are possible:

  • If LastTimestamp is greater than the number of the most recent message, the function fails with "Requests into the future are not possible".
  • If LastTimestamp lies back more messages than the ring buffer can hold, it fails with "Request range is bigger than message buffer".
  • If requested messages have already been overwritten in the ring buffer, it fails with "Invalid request. Check timestamp" or "Invalid timestamp requested ...".
  • If the special switch "DebugDisableSnapshotChanges" is active, it fails with "This function is disabled for debugging purposes!".

In these cases, and after a restart of IP-Symcon, the client has to reload the snapshot.

Example

// Load the snapshot and remember the number of the last included message
$snapshot = json_decode(IPS_GetSnapshot(), true);
$lastTimestamp = $snapshot['timestamp'];

// ... later: retrieve all messages that occurred since then
$changes = json_decode(IPS_GetSnapshotChanges($lastTimestamp), true);
foreach ($changes as $message) {
    printf("#%d: Sender %d, Message %d, Data %s\n", $message['TimeStamp'], $message['SenderID'], $message['Message'], json_encode($message['Data']));
    $lastTimestamp = $message['TimeStamp'];
}

/* e.g. returns:
#991: Sender 0, Message 10202, Data ["Kernel","*** IPS READY",1790081169]
*/
Any questions?