AppSync

UI synchronization layer for AppMessage. More...

Collaboration diagram for AppSync:

Classes
struct	AppSync

Typedefs
typedef void(*	AppSyncTupleChangedCallback) (const uint32_t key, const Tuple *new_tuple, const Tuple *old_tuple, void *context)
typedef void(*	AppSyncErrorCallback) (DictionaryResult dict_error, AppMessageResult app_message_error, void *context)
typedef struct AppSync	AppSync

Functions
void	app_sync_init (struct AppSync *s, uint8_t *buffer, const uint16_t buffer_size, const Tuplet *const keys_and_initial_values, const uint8_t count, AppSyncTupleChangedCallback tuple_changed_callback, AppSyncErrorCallback error_callback, void *context)
void	app_sync_deinit (struct AppSync *s)
AppMessageResult	app_sync_set (struct AppSync *s, const Tuplet *const keys_and_values_to_update, const uint8_t count)
const Tuple *	app_sync_get (const struct AppSync *s, const uint32_t key)

Detailed Description

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.

Typedef Documentation

AppSyncErrorCallback

typedef void(* AppSyncErrorCallback) (DictionaryResult dict_error, AppMessageResult app_message_error, void *context)

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()

AppSyncTupleChangedCallback

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, 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).

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()

Function Documentation

app_sync_deinit()

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.

app_sync_get()

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.

app_sync_init()

void app_sync_init	(	struct AppSync *	s,
		uint8_t *	buffer,
		const uint16_t	buffer_size,
		const Tuplet *const	keys_and_initial_values,
		const uint8_t	count,
		AppSyncTupleChangedCallback	tuple_changed_callback,
		AppSyncErrorCallback	error_callback,
		void *	context
	)

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.

app_sync_set()

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