BlobDB

Key/value databases the phone synchronizes with the watch. More...

Modules
	App database
	Installed apps (BlobDBIdApps).
	App glance database
	App glances (BlobDBIdAppGlance), keyed by app UUID.
	App glance records
	Serialized app glance format stored in the app glance database.
	Contacts database
	Contacts (BlobDBIdContacts), keyed by contact UUID.
	Endpoint
	Messages sent by the watch on the BlobDB sync endpoint.
	Protocol
	BlobDB Pebble Protocol definitions.
	Health database
	Health typicals and averages synced from the phone (BlobDBIdHealth).
	iOS notification preferences
	Per-app notification preferences for iOS (BlobDBIdiOSNotifPref).
	Notification database
	BlobDB front end of notification storage (BlobDBIdNotifs).
	Pin database
	Timeline pins (BlobDBIdPins), keyed by pin UUID.
	Preferences database
	System preferences exposed to the phone (BlobDBIdPrefs).
	Reminder database
	Timeline reminders (BlobDBIdReminders), keyed by reminder UUID.
	Settings database
	System and notification settings synced both ways (BlobDBIdSettings).
	Sync
	Write-back of dirty records to the phone.
	Sync helpers
	Settings file iteration helpers for databases that track dirty records.
	Timeline item storage
	Settings file store of timeline items, shared by the pin and reminder databases.
	Utilities
	BlobDB helpers.
	Watch app preferences
	Preferences of system apps set from the phone (BlobDBIdWatchAppPrefs).
	Weather database
	Weather locations (BlobDBIdWeather), keyed by location UUID.

Data Structures
struct	BlobDBDirtyItem
	Node of a list of records that have not been synced to the phone yet. More...

Typedefs
typedef void(*	BlobDBInitImpl) (void)
	Initialize a database.
typedef status_t(*	BlobDBInsertImpl) (const uint8_t *key, int key_len, const uint8_t *val, int val_len)
	Insert or replace a record.
typedef int(*	BlobDBGetLenImpl) (const uint8_t *key, int key_len)
	Get the length of a record's value.
typedef status_t(*	BlobDBReadImpl) (const uint8_t *key, int key_len, uint8_t *val_out, int val_len)
	Read a record's value.
typedef status_t(*	BlobDBDeleteImpl) (const uint8_t *key, int key_len)
	Delete a record.
typedef status_t(*	BlobDBFlushImpl) (void)
	Delete all records.
typedef status_t(*	BlobDBIsDirtyImpl) (bool *is_dirty_out)
	Check whether the database holds records not yet synced to the phone.
typedef BlobDBDirtyItem *(*	BlobDBGetDirtyListImpl) (void)
	Build the list of records not yet synced to the phone.
typedef status_t(*	BlobDBMarkSyncedImpl) (const uint8_t *key, int key_len)
	Mark a record as synced.
typedef status_t(*	BlobDBCompactImpl) (void)
	Reclaim unused space in the backing settings file.

Enumerations
enum	BlobDBId {   BlobDBIdTest = 0x00 , BlobDBIdPins = 0x01 , BlobDBIdApps = 0x02 , BlobDBIdReminders = 0x03 ,   BlobDBIdNotifs = 0x04 , BlobDBIdWeather = 0x05 , BlobDBIdiOSNotifPref = 0x06 , BlobDBIdPrefs = 0x07 ,   BlobDBIdContacts = 0x08 , BlobDBIdWatchAppPrefs = 0x09 , BlobDBIdHealth = 0x0A , BlobDBIdAppGlance = 0x0B ,   BlobDBIdSettings = 0x0C , NumBlobDBs }
	Database identifiers, as sent on the wire. More...
enum	BlobDBEventType { BlobDBEventTypeInsert , BlobDBEventTypeDelete , BlobDBEventTypeFlush }
	Kind of change reported by a PEBBLE_BLOBDB_EVENT. More...

Functions
void	blob_db_event_put (BlobDBEventType type, BlobDBId db_id, const uint8_t *key, int key_len)
	Emit a PEBBLE_BLOBDB_EVENT.
void	blob_db_init_dbs (void)
	Call the init callback of every database.
void	blob_db_compact_growable_dbs (void)
	Compact every database that implements BlobDBCompactImpl.
void	blob_db_get_dirty_dbs (uint8_t *ids, uint8_t *num_ids)
	List the databases that hold records not yet synced to the phone.
status_t	blob_db_insert (BlobDBId db_id, const uint8_t *key, int key_len, const uint8_t *val, int val_len)
	Insert or replace a record in a database.
int	blob_db_get_len (BlobDBId db_id, const uint8_t *key, int key_len)
	Get the length of a record's value.
status_t	blob_db_read (BlobDBId db_id, const uint8_t *key, int key_len, uint8_t *val_out, int val_len)
	Read a record's value.
status_t	blob_db_delete (BlobDBId db_id, const uint8_t *key, int key_len)
	Delete a record.
status_t	blob_db_flush (BlobDBId db_id)
	Delete all records of a database.
BlobDBDirtyItem *	blob_db_get_dirty_list (BlobDBId db_id)
	Get the records of a database that have not been synced to the phone.
status_t	blob_db_mark_synced (BlobDBId db_id, uint8_t *key, int key_len)
	Mark a record as synced.

Detailed Description

Key/value databases the phone synchronizes with the watch.

BlobDB is a single API in front of several key/value stores (pins, apps, reminders, notifications, weather, settings, ...), each identified by a BlobDBId. The phone writes to them over the Pebble Protocol BlobDB endpoints; the wire format, command opcodes and response codes are described in docs/reference/blob-db.md.

Each database implements the BlobDB*Impl callbacks and is registered with its id in the s_blob_dbs table of fw/services/blob_db/api.c. Callbacks are blocking and return once the command has been executed; a database is not guaranteed to persist across reboots. Unimplemented operations return E_INVALID_OPERATION.

Databases that track dirty records (records written on the watch and not yet acknowledged by the phone) can be written back to the phone with the sync API (see Sync).

const Uuid key = ...;
status_t rv = blob_db_insert(BlobDBIdContacts, (const uint8_t *)&key, sizeof(key), val,
                             val_len);
 
int len = blob_db_get_len(BlobDBIdContacts, (const uint8_t *)&key, sizeof(key));
if (len > 0) {
  uint8_t *buf = kernel_malloc_check(len);
  rv = blob_db_read(BlobDBIdContacts, (const uint8_t *)&key, sizeof(key), buf, len);
  ...
  kernel_free(buf);
}

---

Data Structure Documentation

BlobDBDirtyItem

struct BlobDBDirtyItem

Node of a list of records that have not been synced to the phone yet.

Allocated with the key appended; free a whole list with blob_db_util_free_dirty_list().

Data Fields
uint8_t	key[]	Key data.
int	key_len	Length of key in bytes.
time_t	last_updated	Time the record was last modified.
ListNode	node	List node.

Typedef Documentation

BlobDBCompactImpl

typedef status_t(* BlobDBCompactImpl) (void)

Reclaim unused space in the backing settings file.

Blocking. Only databases backed by a settings file implement it.

Returns

S_SUCCESS on success, an error code otherwise.

BlobDBDeleteImpl

typedef status_t(* BlobDBDeleteImpl) (const uint8_t *key, int key_len)

Delete a record.

Blocking.

Parameters

key	Key data.
key_len	Length of key in bytes.

Returns

S_SUCCESS on success, an error code otherwise (see StatusCode).

BlobDBFlushImpl

typedef status_t(* BlobDBFlushImpl) (void)

Delete all records.

Blocking.

Returns

S_SUCCESS on success, an error code otherwise (see StatusCode).

BlobDBGetDirtyListImpl

typedef BlobDBDirtyItem *(* BlobDBGetDirtyListImpl) (void)

Build the list of records not yet synced to the phone.

The list size is unbounded; it may be incomplete when memory runs out.

Returns

Heap-allocated list with one node per dirty record, NULL if there is none.

BlobDBGetLenImpl

typedef int(* BlobDBGetLenImpl) (const uint8_t *key, int key_len)

Get the length of a record's value.

Parameters

key	Key data.
key_len	Length of key in bytes.

Returns

Length of the value in bytes, 0 if the key does not exist, or a negative error code.

BlobDBInitImpl

typedef void(* BlobDBInitImpl) (void)

Initialize a database.

Called once at boot by blob_db_init_dbs().

BlobDBInsertImpl

typedef status_t(* BlobDBInsertImpl) (const uint8_t *key, int key_len, const uint8_t *val, int val_len)

Insert or replace a record.

Blocking.

Parameters

key	Key data.
key_len	Length of key in bytes.
val	Value data.
val_len	Length of val in bytes.

Returns

S_SUCCESS on success, an error code otherwise (see StatusCode).

BlobDBIsDirtyImpl

typedef status_t(* BlobDBIsDirtyImpl) (bool *is_dirty_out)

Check whether the database holds records not yet synced to the phone.

Parameters

[out]

is_dirty_out

Set to true if there is at least one dirty record. Undefined on failure.

Returns

S_SUCCESS if the query succeeded, an error code otherwise.

BlobDBMarkSyncedImpl

typedef status_t(* BlobDBMarkSyncedImpl) (const uint8_t *key, int key_len)

Mark a record as synced.

Parameters

key	Key data.
key_len	Length of key in bytes.

Returns

S_SUCCESS on success, an error code otherwise.

BlobDBReadImpl

typedef status_t(* BlobDBReadImpl) (const uint8_t *key, int key_len, uint8_t *val_out, int val_len)

Read a record's value.

Blocking.

Parameters

	key	Key data.
	key_len	Length of key in bytes.
[out]	val_out	Buffer of val_len bytes.
	val_len	Number of bytes to copy.

Returns

S_SUCCESS on success, an error code otherwise (see StatusCode).

Enumeration Type Documentation

BlobDBEventType

enum BlobDBEventType

Kind of change reported by a PEBBLE_BLOBDB_EVENT.

Enumerator
BlobDBEventTypeInsert	A record was inserted or replaced.
BlobDBEventTypeDelete	A record was deleted.
BlobDBEventTypeFlush	All records of the database were deleted.

BlobDBId

enum BlobDBId

Database identifiers, as sent on the wire.

Enumerator
BlobDBIdTest	Test database, not registered.
BlobDBIdPins	Timeline pins (see Pin database).
BlobDBIdApps	Installed apps (see App database).
BlobDBIdReminders	Reminders (see Reminder database).
BlobDBIdNotifs	Notifications (see Notification database).
BlobDBIdWeather	Weather locations (see Weather database).
BlobDBIdiOSNotifPref	iOS notification preferences (see iOS notification preferences).
BlobDBIdPrefs	System preferences (see Preferences database).
BlobDBIdContacts	Contacts (see Contacts database).
BlobDBIdWatchAppPrefs	Watch app preferences (see Watch app preferences).
BlobDBIdHealth	Health typicals and averages (see Health database).
BlobDBIdAppGlance	App glances (see App glance database).
BlobDBIdSettings	Synced settings (see Settings database).
NumBlobDBs	Number of database ids.

Function Documentation

blob_db_compact_growable_dbs()

void blob_db_compact_growable_dbs

(

void

)

Compact every database that implements BlobDBCompactImpl.

Must be called after blob_db_init_dbs(). Performs flash I/O: call it from a system task callback, not from the kernel main loop.

blob_db_delete()

status_t blob_db_delete	(	BlobDBId	db_id,
		const uint8_t *	key,
		int	key_len
	)

Delete a record.

Emits a BlobDBEventTypeDelete event on success.

Parameters

db_id	Database.
key	Key data.
key_len	Length of key in bytes.

Return values

S_SUCCESS	Deleted.
E_RANGE	Invalid or disabled database.
E_INVALID_OPERATION	Operation not supported by the database.

Returns

Other error codes from BlobDBDeleteImpl.

blob_db_event_put()

void blob_db_event_put	(	BlobDBEventType	type,
		BlobDBId	db_id,
		const uint8_t *	key,
		int	key_len
	)

Emit a PEBBLE_BLOBDB_EVENT.

The key is copied into a kernel heap buffer owned by the event.

Parameters

type	Event type.
db_id	Database the event refers to.
key	Key data, may be NULL when key_len is 0.
key_len	Length of key in bytes.

blob_db_flush()

status_t blob_db_flush

(

BlobDBId

db_id

)

Delete all records of a database.

Emits a BlobDBEventTypeFlush event on success.

Parameters

db_id

Database.

Return values

S_SUCCESS	Flushed.
E_RANGE	Invalid or disabled database.
E_INVALID_OPERATION	Operation not supported by the database.

Returns

Other error codes from BlobDBFlushImpl.

blob_db_get_dirty_dbs()

void blob_db_get_dirty_dbs	(	uint8_t *	ids,
		uint8_t *	num_ids
	)

List the databases that hold records not yet synced to the phone.

Parameters

[out]	ids	Array of at least NumBlobDBs entries, filled with dirty BlobDBId values.
[out]	num_ids	Number of entries written to ids.

blob_db_get_dirty_list()

BlobDBDirtyItem * blob_db_get_dirty_list

(

BlobDBId

db_id

)

Get the records of a database that have not been synced to the phone.

Records written by the phone are always marked as synced. Use the API in Sync to start a sync.

Parameters

db_id

Database.

Returns

Heap-allocated list (free with blob_db_util_free_dirty_list()), or NULL if there are no dirty records or the database does not track them.

blob_db_get_len()

int blob_db_get_len	(	BlobDBId	db_id,
		const uint8_t *	key,
		int	key_len
	)

Get the length of a record's value.

Parameters

db_id	Database.
key	Key data.
key_len	Length of key in bytes.

Returns

Length in bytes, 0 if the key does not exist, or a negative error code (E_RANGE for an invalid database, E_INVALID_OPERATION if unsupported).

blob_db_init_dbs()

void blob_db_init_dbs

(

void

)

Call the init callback of every database.

blob_db_insert()

status_t blob_db_insert	(	BlobDBId	db_id,
		const uint8_t *	key,
		int	key_len,
		const uint8_t *	val,
		int	val_len
	)

Insert or replace a record in a database.

Emits a BlobDBEventTypeInsert event on success.

Parameters

db_id	Database.
key	Key data.
key_len	Length of key in bytes.
val	Value data.
val_len	Length of val in bytes.

Return values

S_SUCCESS	Inserted.
E_RANGE	Invalid or disabled database.
E_INVALID_OPERATION	Operation not supported by the database.

Returns

Other error codes from BlobDBInsertImpl.

blob_db_mark_synced()

status_t blob_db_mark_synced	(	BlobDBId	db_id,
		uint8_t *	key,
		int	key_len
	)

Mark a record as synced.

Used when the phone acknowledges a write during a sync.

Parameters

db_id	Database.
key	Key data.
key_len	Length of key in bytes.

Return values

S_SUCCESS	Marked.
E_RANGE	Invalid or disabled database.
E_INVALID_OPERATION	Operation not supported by the database.

Returns

Other error codes from BlobDBMarkSyncedImpl.

blob_db_read()

status_t blob_db_read	(	BlobDBId	db_id,
		const uint8_t *	key,
		int	key_len,
		uint8_t *	val_out,
		int	val_len
	)

Read a record's value.

Parameters

	db_id	Database.
	key	Key data.
	key_len	Length of key in bytes.
[out]	val_out	Buffer of val_len bytes.
	val_len	Number of bytes to copy, usually from blob_db_get_len().

Return values

S_SUCCESS	Read.
E_RANGE	Invalid or disabled database.
E_INVALID_OPERATION	Operation not supported by the database.

Returns

Other error codes from BlobDBReadImpl.