Handling Offline Messages
The C SDK has multiple options for offline message storage. In general, offline message storage queues up outgoing request messages for later delivery if the network is down or the duty cycle modulation component of the AlwaysOn protocol is 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 set for the OFFLINE_MSG_QUEUE_SIZE parameter in the twDefaultSettings.h file. When connectivity is re-established, all the messages in this queue are sent to the ThingWorx Platform.
 |
As of v.2.2.12, the C SDK no longer stores AUTH and BIND type messages in the offline message store during network disconnections.
|
The default setting for offline message storage is that offline message storage is enabled and persists 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, and there is a power outage or the system is shut down for any reason, these messages are 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 in bytes.
|
|
As of v.2.2.8 of the C SDK, the size of the subscribed property update queue matches the setting of the twcfg.subscribed_props_queue_size property instead of the size of the offline message queue set by OFFLINE_MSG_QUEUE_SIZE. This change prevents the error generated when the twSubscribedPropsMgr_setPropertyVTQ function tries to add a property update that would increase the subscribed properties queue past the size limit of the offline message queue.
|
In both the RAM-based, and file-based offline message stores, when connectivity is re-established all the messages in this queue are sent to the ThingWorx Platform. Note that it is possible for all of the original messages to 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. Additionally, in either the RAM-based or file-based use case, if the total size of the queued messages exceeds the limit defined in OFFLINE_MSG_QUEUE_SIZE, any subsequent attempt to queue more messages fails 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 need not 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 in bytes.
If the initialization is successful, this function returns TW_OK. If not, it returns an error (refer to 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 the 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 the platform again, the messages are sent based on your configuration, as described in the preceding section. However, if the ping timeout and connection retries are exhausted, the SDK disconnects and does not reconnect unless the application invokes twApi_Connect. Messages destined for the 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 the ThingWorx Platform (connection_retries in twApi_initialize()). In addition, if it is not already enabled, enable automatic reconnection. To enable automatic reconnection, 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 to reconnect indefinitely. Be aware that with these settings, it may 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. In this situation, try a specific number of retries again.