UI synchronization layer for AppMessage.
AppSync is a convenience layer that resides on top of AppMessage, and serves as a UI synchronization layer for AppMessage. In so doing, AppSync makes it easier to drive the information displayed in the watchapp UI with messages sent by a phone app.
AppSync maintains and updates a Dictionary, and provides your app with a callback (AppSyncTupleChangedCallback) routine that is called whenever the Dictionary changes and the app's UI is updated. Note that the app UI is not updated automatically. To update the UI, you need to implement the callback.
Pebble OS provides support for data serialization utilities, like Dictionary, Tuple and Tuplet data structures and their accompanying functions. You use Tuplets to create a Dictionary with Tuple structures.
AppSync manages the storage and bookkeeping chores of the current Tuple values. AppSync copies incoming AppMessage Tuples into this "current" Dictionary, so that the key/values remain available for the UI to use. For example, it is safe to use a C-string value provided by AppSync and use it directly in a text_layer_set_text() call.
Your app needs to supply the buffer that AppSync uses for the "current" Dictionary when initializing AppSync.
Refer to the Synchronizing App UI guide for a conceptual overview and code usage.
Initialized an AppSync system with specific buffer size and initial keys and values. The callback.value_changed callback will be called asynchronously with the initial keys and values, as to avoid duplicating code to update your app's UI.
Only updates for the keys specified in this initial array will be accepted by AppSync, updates for other keys that might come in will just be ignored.
The AppSync context to initialize
The buffer that AppSync should use
The size of the backing storage of the "current" dictionary. Use dict_calc_buffer_size_from_tuplets() to estimate the size you need.
An array of Tuplets with the initial keys and values.
The number of Tuplets in the keys_and_initial_values array.
The callback that will handle changed key/value pairs
The callback that will handle errors
Pointer to app specific data that will get passed into calls to the callbacks
Cleans up an AppSync system. It frees the buffer allocated by an app_sync_init() call and deregisters itself from the AppMessage subsystem.
The AppSync context to deinit.
Updates key/value pairs using an array of Tuplets.
The call will attempt to send the updated keys and values to the application on the other end. Only after the other end has acknowledged the update, the .value_changed callback will be called to confirm the update has completed and your application code can update its user interface.
The AppSync context
An array of Tuplets with the keys and values to update. The data in the Tuplets are copied during the call, so the array can be stack-allocated.
The number of Tuplets in the keys_and_values_to_update array.
The result code from the AppMessage subsystem. Can be APP_MSG_OK, APP_MSG_BUSY or APP_MSG_INVALID_ARGS
Called whenever a Tuple changes. This does not necessarily mean the value in the Tuple has changed. When the internal "current" dictionary gets updated, existing Tuples might get shuffled around in the backing buffer, even though the values stay the same. In this callback, the client code gets the chance to remove the old reference and start using the new one. In this callback, your application MUST clean up any references to the old_tuple of a PREVIOUS call to this callback (and replace it with the new_tuple that is passed in with the current call).
The key for which the Tuple was changed.
The new tuple. The tuple points to the actual, updated "current" dictionary, as backed by the buffer internal to the AppSync struct. Therefore the Tuple can be used after the callback returns, until the AppSync is deinited. In case there was an error (e.g. storage shortage), this new_tuple can be NULL_TUPLE.
The values that will be replaced with new_tuple. The key, value and type will be equal to the previous tuple in the old destination dictionary; however, the old_tuple points to a stack-allocated copy of the old data. This value will be NULL_TUPLE when the initial values are being set.
Pointer to application specific data, as set using app_sync_init()
Called whenever there was an error.
The dictionary result error code, if the error was dictionary related.
The app_message result error code, if the error was app_message related.
Pointer to application specific data, as set using app_sync_init()
Do you have questions about the Pebble SDK?
Do you need some help understanding something on this page?
You can either take advantage of our awesome developer community and check out the SDK Help forums, or you can send us a message through the website!