ThingWorx Edge C SDK > Handling Offline Messages
Handling Offline Messages
The C SDK has multiple options for offline message storage. In general, offline message storage will queue up outgoing request messages for later delivery if the network is down or the duty cycle modulation component of the AlwaysOn protocol happens to be in the “off” state. When offline message storage is enabled and the device is offline, outgoing messages are placed in a queue, up to a limit of OFFLINE_MSG_QUEUE_SIZE. When connectivity is re-established, all the messages in this queue are sent out to the ThingWorx platform.
The default setting for offline message storage is that offline message storage is enabled and will persist the messages to a file. If storage space is not available on the device, you can still enable offline message storage that stores messages in RAM only. For the smallest footprint, you can disable this feature.
If you enable offline message store but limit the storage to RAM only, keep in mind that, if there is a power outage or the system is shut down for any reason, these messages will be lost and not delivered to the ThingWorx platform.
To configure offline message store, open either a CommonSettings file or the file, twConfig.h, and add the following parameters:
OFFLINE_MSG_STORE — To disable the feature, change the 2 to 0. To enable it but store only in RAM, change the 2 to 1.
OFFLINE_MSG_STORE_DIR — If you are using the feature and storing messages in files, specify the directory in which you want to store the messages.
OFFLINE_MSG_QUEUE_SIZE — If you are using the feature, specify the maximum size of the message queue (number of messages).
In both the RAM-based, and file-based offline message stores, when connectivity is re-established all the messages in this queue are sent out to the ThingWorx platform. Note that it is quite likely that all of the original messages will time out while waiting for a response from the platform, so you will not receive any indication or confirmation that these messages were successfully processed by the platform. Also in either use case (RAM-based or file-based), if the total size of the queued messages exceeds the limit defined in OFFLINE_MSG_QUEUE_SIZE, any subsequent attempt to queue more messages will fail and those new messages will be lost.
The structure for offline message store is defined in ./src/utils. A singleton instance of this structure is automatically created when * twOfflineMsgStore_Initialize() is called. You should not need to manipulate this structure directly. You can make the following types of requests to the offline message store:
OFFLINE_MSG_STORE_FLUSH — Request to flush the offline message store buffer.
OFFLINE_MSG_STORE_WRITE — Request to write a message into the offline message store.
As of release 1.3.3 of the C SDK, the offline message store is automatically initialized by twApi_Initialize(). However, if your application requires a more complex offline message store model, you can initialize it separately by calling twOfflineMsgStore_Initialize(), and passing in the following arguments:
enabled — A boolean value to enable/disable the offline message store.
filePath — The path to the offline message store directory.
size — The maximum size of the offline message store.
If the initialization is successful, this function returns TW_OK. If not, it returns an error (see twErrors.h for definitions of the errors).
The following additional functions are available for offline message storage as of release 1.3.3:
Specify the directory in which to store the offline messages — twOfflineMsgStore_SetDir().
Free memory that is associated with the offline message store singleton — twOfflineMsgStore_Delete().
Process requests to the offline message store — twOfflineMsgStore_HandleRequest().
Lost Messages
If the connection to ThingWorx platform is lost and offline message store is enabled, the messages currently waiting to be sent to ThingWorx are stored in the offline message store, as configured. Once the application reconnects and authenticates with ThingWorx platform again, the messages are sent based on your configuration, as described above. However, if the ping timeout and connection retries are exhausted, the SDK will disconnect and not reconnect unless the application invokes twApi_Connect. Messages destined for ThingWorx platform will be lost.
This situation may occur in an environment where network connectivity is forcibly removed. To avoid the loss of messages, consider adjusting the setting for retrying the connection to ThingWorx platform (connection_retries in twApi_initialize()). In addition, if it is not already enabled, enable automatic re-connection. To enable automatic re-connection, set autoreconnect to true in twApi_initialize() so that the application automatically tries to reconnect when a connection is lost.
If these changes do not resolve the situation, set the number of connection retries to -1 (connection_retries= -1). The SDK will try indefinitely to reconnect. Be aware that with these settings, it might appear that the application is in an infinite loop. In reality, the SDK just is not able to connect and is constantly retrying the connection.