UI Synchronization layer for AppMessage.
AppSync is a thin layer on top of AppMessage, to make it easier to drive the information displayed in the user interface of a watch app with messages sent by a phone app.
Key Points
- One callback to update the user interface, that is called whenever a Tuple changes. See AppSyncTupleChangedCallback.
- Manages storage and book keeping of the current Tuple values: AppSync copies incoming AppMessage Tuples into this "current" Dictionary, so that the key/values remain available for the user interface 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.
Activity Diagram
Also see the activity diagram of the underlying AppMessage subsystem.
Example Project
For a code example, see the sample project demos/feature_app_messages
.
void app_sync_deinit |
( |
struct AppSync * |
s | ) |
|
Cleans up an AppSync system. It frees the buffer allocated by an app_sync_init() call and deregisters itself from the AppMessage subsystem.
- Parameters
-
s | The AppSync context to deinit. |
const Tuple* app_sync_get |
( |
const struct AppSync * |
s, |
|
|
const uint32_t |
key |
|
) |
| |
Finds and gets a tuple in the "current" dictionary.
- Parameters
-
s | The AppSync context |
key | The key for which to find a Tuple |
- Returns
- Pointer to a found Tuple, or NULL if there was no Tuple with the specified key.
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.
- Parameters
-
s | The AppSync context to initialize |
buffer | The buffer that AppSync should use |
buffer_size | The size of the backing storage of the "current" dictionary. Use dict_calc_buffer_size_from_tuplets() to estimate the size you need. |
keys_and_initial_values | An array of Tuplets with the initial keys and values. |
count | The number of Tuplets in the keys_and_initial_values array. |
tuple_changed_callback | The callback that will handle changed key/value pairs |
error_callback | The callback that will handle errors |
context | Pointer to app specific data that will get passed into calls to the callbacks |
- Note
- 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.
AppMessageResult app_sync_set |
( |
struct AppSync * |
s, |
|
|
const Tuplet *const |
keys_and_values_to_update, |
|
|
const uint8_t |
count |
|
) |
| |
Updates key/value pairs using an array of Tuplets.
- Note
- 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.
- Parameters
-
s | The AppSync context |
keys_and_values_to_update | 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. |
count | The number of Tuplets in the keys_and_values_to_update array. |
- Returns
- The result code from the AppMessage subsystem. Can be APP_MSG_OK, APP_MSG_BUSY or APP_MSG_INVALID_ARGS
Called whenever there was an error.
- Parameters
-
dict_error | The dictionary result error code, if the error was dictionary related. |
app_message_error | The app_message result error code, if the error was app_message related. |
context | Pointer to application specific data, as set using app_sync_init() |
- See Also
- app_sync_init()
typedef void(* AppSyncTupleChangedCallback)(const uint32_t key, const Tuple *new_tuple, const Tuple *old_tuple, void *context) |
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, you 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).
- Parameters
-
key | The key for which the Tuple was changed. |
new_tuple | 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. |
old_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. |
context | Pointer to application specific data, as set using app_sync_init() |
- See Also
- app_sync_init()