Data serialization utilities.
Data residing in different parts of Pebble memory (RAM) may need to be gathered and assembled into a single continuous block for transport over the network via Bluetooth. The process of gathering and assembling this continuous block of data is called serialization.
You use data serialization utilities, like Dictionary, Tuple and Tuplet data structures and accompanying functions, to accomplish this task. No transformations are performed on the actual data, however. These Pebble utilities simply help assemble the data into one continuous buffer according to a specific format.
AppMessage uses these utilities-in particular, Dictionary-to send information between mobile and Pebble watchapps.
To write two key/value pairs, without using Tuplets, you would do this:
// Byte array + key:
static const uint32_t SOME_DATA_KEY = 0xb00bf00b;
static const uint8_t data[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
// CString + key:
static const uint32_t SOME_STRING_KEY = 0xabbababe;
static const char *string = "Hello World";
// Calculate the buffer size that is needed for the final Dictionary:
const uint8_t key_count = 2;
const uint32_t size = dict_calc_buffer_size(key_count, sizeof(data),
strlen(string) + 1);
// Stack-allocated buffer in which to create the Dictionary:
uint8_t buffer[size];
// Iterator variable, keeps the state of the creation serialization process:
DictionaryIterator iter;
// Begin:
dict_write_begin(&iter, buffer, sizeof(buffer));
// Write the Data:
dict_write_data(&iter, SOME_DATA_KEY, data, sizeof(data));
// Write the CString:
dict_write_cstring(&iter, SOME_STRING_KEY, string);
// End:
const uint32_t final_size = dict_write_end(&iter);
// buffer now contains the serialized information
To iterate over the key/value pairs in the dictionary that was created in the previous example code, you would do this:
Tuple *tuple = dict_read_begin_from_buffer(&iter, buffer, final_size);
while (tuple) {
switch (tuple->key) {
case SOME_DATA_KEY:
foo(tuple->value->data, tuple->length);
break;
case SOME_STRING_KEY:
bar(tuple->value->cstring);
break;
}
tuple = dict_read_next(&iter);
}
To understand the difference between Tuple and Tuplet data structures: Tuple is the header for a serialized key/value pair, while Tuplet is a helper data structure that references the value you want to serialize. This data structure exists to make the creation of a Dictionary easier to write. Use this mnemonic to remember the difference: TupleT(emplate), the Tuplet being a template to create a Dictionary with Tuple structures.
For example:
Tuplet pairs[] = {
TupletInteger(WEATHER_ICON_KEY, (uint8_t) 1),
TupletCString(WEATHER_TEMPERATURE_KEY, "1234 Fahrenheit"),
};
uint8_t buffer[256];
uint32_t size = sizeof(buffer);
dict_serialize_tuplets_to_buffer(pairs, ARRAY_LENGTH(pairs), buffer, &size);
// buffer now contains the serialized information
Calculates the number of bytes that a dictionary will occupy, given one or more value lengths that need to be stored in the dictionary.
The formula to calculate the size of a Dictionary in bytes is:
1 + (n * 7) + D1 + ... + DnWhere
n is the number of Tuples in the Dictionary and Dx are the sizes of the values in the Tuples. The size of the Dictionary header is 1 byte. The size of the header for each Tuple is 7 bytes.
The total number of key/value pairs in the dictionary.
The sizes of each of the values that need to be stored in the dictionary.
The total number of bytes of storage needed.
Calculates the size of data that has been written to the dictionary. AKA, the "dictionary size". Note that this is most likely different than the size of the backing storage/backing buffer.
The dictionary iterator
The total number of bytes which have been written to the dictionary.
Initializes the dictionary iterator with a given buffer and size, resets and empties it, in preparation of writing key/value tuples.
The dictionary iterator
The storage of the dictionary
The storage size of the dictionary
DICT_OK, DICT_NOT_ENOUGH_STORAGE or DICT_INVALID_ARGS
Adds a key with a byte array value pair to the dictionary.
The data will be copied into the backing storage of the dictionary.
There is no checking for duplicate keys.
The dictionary iterator
The key
Pointer to the byte array
Length of the byte array
Adds a key with a C string value pair to the dictionary.
The string will be copied into the backing storage of the dictionary.
There is no checking for duplicate keys.
The dictionary iterator
The key
Pointer to the zero-terminated C string
Adds a key with an integer value pair to the dictionary.
There is no checking for duplicate keys. dict_write_int() is only for serializing a single integer. width_bytes can only be 1, 2, or 4.
The dictionary iterator
The key
Pointer to the integer value
The width of the integer value
Whether the integer's type is signed or not
Adds a key with an unsigned, 8-bit integer value pair to the dictionary.
There is no checking for duplicate keys.
There are counterpart functions for different signedness and widths, dict_write_uint16(), dict_write_uint32(), dict_write_int8(), dict_write_int16() and dict_write_int32(). The documentation is not repeated for brevity's sake.
The dictionary iterator
The key
The unsigned, 8-bit integer value
End a series of writing operations to a dictionary. This must be called before reading back from the dictionary.
The dictionary iterator
The size in bytes of the finalized dictionary, or 0 if the parameters were invalid.
Initializes the dictionary iterator with a given buffer and size, in preparation of reading key/value tuples.
The dictionary iterator
The storage of the dictionary
The storage size of the dictionary
The first tuple in the dictionary, or NULL in case the dictionary was empty or if there was a parsing error.
Progresses the iterator to the next key/value pair.
The dictionary iterator
The next tuple in the dictionary, or NULL in case the end has been reached or if there was a parsing error.
Resets the iterator back to the same state as a call to dict_read_begin_from_buffer() would do.
The dictionary iterator
The first tuple in the dictionary, or NULL in case the dictionary was empty or if there was a parsing error.
Utility function that takes a list of Tuplets from which a dictionary will be serialized, ready to transmit or store.
The callback will be called before the function returns, so the data that that context points to, can be stack allocated.
The callback that will be called with the serialized data of the generated dictionary.
Pointer to any application specific data that gets passed into the callback.
An array of Tuplets that need to be serialized into the dictionary.
The number of tuplets that follow.
Utility function that takes an array of Tuplets and serializes them into a dictionary with a given buffer and size.
The array of tuplets
The number of tuplets in the array
The buffer in which to write the serialized dictionary
The available buffer size in bytes
The number of bytes written
Serializes an array of Tuplets into a dictionary with a given buffer and size.
The dictionary iterator
The array of tuplets
The number of tuplets in the array
The buffer in which to write the serialized dictionary
The available buffer size in bytes
The number of bytes written
The dictionary iterator
The Tuplet describing the key/value pair to write
Calculates the number of bytes that a dictionary will occupy, given one or more Tuplets that need to be stored in the dictionary.
See dict_calc_buffer_size() for the formula for the calculation.
An array of Tuplets that need to be stored in the dictionary.
The total number of Tuplets that follow.
The total number of bytes of storage needed.
Merges entries from another "source" dictionary into a "destination" dictionary. All Tuples from the source are written into the destination dictionary, while updating the exsting Tuples with matching keys.
The destination dictionary to update
In: the maximum size of buffer backing dest. Out: the final size of the updated dictionary.
The source dictionary of which its Tuples will be used to update dest.
Specify True if only the existing keys in dest should be updated.
The callback that will be called for each Tuple in the merged destination dictionary.
Pointer to app specific data that will get passed in when update_key_callback is called.
An iterator can be used to iterate over the key/value tuples in an existing dictionary, using dict_read_begin_from_buffer(), dict_read_first() and dict_read_next(). An iterator can also be used to append key/value tuples to a dictionary, for example using dict_write_data() or dict_write_cstring().
The dictionary being iterated.
Points to the first memory address after the last byte of the dictionary Points to the next Tuple in the dictionary. Given the end of the Dictionary has not yet been reached: when writing, the next key/value pair will be written at the cursor. When reading, the next call to dict_read_next() will return the cursor.
Data structure for one serialized key/value tuple.
The structure is variable length! The length depends on the value data that the tuple contains.
The key.
The type of data that the .value fields contains.
The length of .value in bytes.
The value itself.
The different union fields are provided for convenience, avoiding the need for manual casts.
The array length is of incomplete length on purpose, to facilitate variable length data and because a data length of zero is valid.
Important: The integers are little endian!
Non-serialized, template data structure for a key/value pair. For strings and byte arrays, it only has a pointer to the actual data. For integers, it provides storage for integers up to 32-bits wide. The Tuplet data structure is useful when creating dictionaries from values that are already stored in arbitrary buffers. See also Tuple, with is the header of a serialized key/value pair.
Return values for dictionary write/conversion functions.
The operation returned successfully.
There was not enough backing storage to complete the operation.
One or more arguments were invalid or uninitialized.
The lengths and/or count of the dictionary its tuples are inconsistent.
A requested operation required additional memory to be allocated, but the allocation failed, likely due to insufficient remaining heap memory.
Values representing the type of data that the value field of a Tuple contains.
The value is an array of bytes.
The value is a zero-terminated, UTF-8 C-string.
The value is an unsigned integer. The tuple's .length field is used to determine the size of the integer (1, 2, or 4 bytes).
The value is a signed integer. The tuple's .length field is used to determine the size of the integer (1, 2, or 4 bytes).
Callback for dict_serialize_tuplets() utility.
The data of the serialized dictionary
The size of data
The context pointer as passed in to dict_serialize_tuplets()
Type of the callback used in dict_merge()
The key that is being updated.
The new tuple. The tuple points to the actual, updated destination dictionary or NULL_TUPLE in case there was an error (e.g. backing buffer was too small). Therefore the Tuple can be used after the callback returns, until the destination dictionary storage is free'd (by the application itself).
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.
Pointer to application specific data The storage backing old_tuple can only be used during the callback and will no longer be valid after the callback returns.
Macro to create a Tuplet with a byte array value.
The key
Pointer to the bytes
Length of the buffer
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!