Pin database

Timeline pins (BlobDBIdPins), keyed by pin UUID. More...

Functions
status_t	pin_db_get (const TimelineItemId *id, TimelineItem *pin)
	Read and deserialize a pin.
status_t	pin_db_insert_item (TimelineItem *item)
	Serialize and insert a pin, emitting a BlobDB insert event.
status_t	pin_db_insert_item_without_event (TimelineItem *item)
	pin_db_insert_item() without the BlobDB event.
status_t	pin_db_set_status_bits (const TimelineItemId *id, uint8_t status)
	Overwrite the status bits of a pin.
status_t	pin_db_each (TimelineItemStorageEachCallback each, void *data)
	Call a function for every record in the pin database.
status_t	pin_db_delete_with_parent (const TimelineItemId *parent_id)
	Delete the pins of a parent (app or data source).
bool	pin_db_exists_with_parent (const TimelineItemId *parent_id)
	Check whether a parent has pins.
status_t	pin_db_read_item_header (TimelineItem *item_out, TimelineItemId *id)
	Read the header of a pin.
status_t	pin_db_next_item_header (TimelineItem *next_item_out, TimelineItemStorageFilterCallback filter)
	Read the header of the earliest pin within the maximum age.
bool	pin_db_has_entry_expired (time_t pin_end_timestamp)
	Check whether a pin is older than the pin database keeps.
void	pin_db_init (void)
	Initialize the pin database.
void	pin_db_deinit (void)
	Close the settings file backing the pin database.
status_t	pin_db_insert (const uint8_t *key, int key_len, const uint8_t *val, int val_len)
	Insert or replace a record in the pin database.
int	pin_db_get_len (const uint8_t *key, int key_len)
	Get the length of a record in the pin database.
status_t	pin_db_read (const uint8_t *key, int key_len, uint8_t *val_out, int val_out_len)
	Read a record from the pin database.
status_t	pin_db_delete (const uint8_t *key, int key_len)
	Delete a record from the pin database.
status_t	pin_db_flush (void)
	Delete all records of the pin database.
status_t	pin_db_compact (void)
	Compact the settings file backing the pin database.
status_t	pin_db_is_dirty (bool *is_dirty_out)
	Check whether the pin database holds records not yet synced to the phone.
BlobDBDirtyItem *	pin_db_get_dirty_list (void)
	Build the list of records of the pin database not yet synced to the phone.
status_t	pin_db_mark_synced (const uint8_t *key, int key_len)
	Mark a record of the pin database as synced.

Detailed Description

Timeline pins (BlobDBIdPins), keyed by pin UUID.

Backed by Timeline item storage; pins older than three days are rejected.

Function Documentation

pin_db_compact()

status_t pin_db_compact

(

void

)

Compact the settings file backing the pin database.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_deinit()

void pin_db_deinit

(

void

)

Close the settings file backing the pin database.

pin_db_delete()

status_t pin_db_delete	(	const uint8_t *	key,
		int	key_len
	)

Delete a record from the pin database.

The key is the pin UUID. Also deletes the reminders of the pin.

Parameters

key	Key data.
key_len	Length of key in bytes.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_delete_with_parent()

status_t pin_db_delete_with_parent

(

const TimelineItemId *

parent_id

)

Delete the pins of a parent (app or data source).

Parameters

parent_id

Parent UUID.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_each()

status_t pin_db_each	(	TimelineItemStorageEachCallback	each,
		void *	data
	)

Call a function for every record in the pin database.

Warning

flags and status of the stored CommonTimelineItemHeader are inverted and are not restored for the callback.

Parameters

each	Callback.
data	User data passed to each.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_exists_with_parent()

bool pin_db_exists_with_parent

(

const TimelineItemId *

parent_id

)

Check whether a parent has pins.

Parameters

parent_id

Parent UUID.

Returns

true if at least one pin has this parent.

pin_db_flush()

status_t pin_db_flush

(

void

)

Delete all records of the pin database.

Pins created on the watch are kept.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_get()

status_t pin_db_get	(	const TimelineItemId *	id,
		TimelineItem *	pin
	)

Read and deserialize a pin.

Parameters

	id	Pin UUID.
[out]	pin	Pin; free its buffer with timeline_item_free_allocated_buffer().

Return values

S_SUCCESS	Read.
E_DOES_NOT_EXIST	No such pin.

Returns

Other error codes on failure.

pin_db_get_dirty_list()

BlobDBDirtyItem * pin_db_get_dirty_list

(

void

)

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

Returns

Heap-allocated list (free with blob_db_util_free_dirty_list()), NULL if none.

pin_db_get_len()

int pin_db_get_len	(	const uint8_t *	key,
		int	key_len
	)

Get the length of a record in the pin database.

The key is the pin UUID.

Parameters

key	Key data.
key_len	Length of key in bytes.

Returns

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

pin_db_has_entry_expired()

bool pin_db_has_entry_expired

(

time_t

pin_end_timestamp

)

Check whether a pin is older than the pin database keeps.

Parameters

pin_end_timestamp

End time of the pin.

Returns

true if the pin has expired.

pin_db_init()

void pin_db_init

(

void

)

Initialize the pin database.

pin_db_insert()

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

Insert or replace a record in the pin database.

The key is the pin UUID and the value a serialized timeline item. Records from the phone are stored as synced. Notification and reminder layouts are rejected. Triggers a fetch of the parent app when it is installed but not cached.

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.

pin_db_insert_item()

status_t pin_db_insert_item

(

TimelineItem *

item

)

Serialize and insert a pin, emitting a BlobDB insert event.

Pins from the reminders app data source are marked dirty and synced to the phone.

Parameters

item	Pin, of type TimelineItemTypePin.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_insert_item_without_event()

status_t pin_db_insert_item_without_event

(

TimelineItem *

item

)

pin_db_insert_item() without the BlobDB event.

Meant for tests inserting many generated pins, which would otherwise flood the event queue.

Parameters

item	Pin, of type TimelineItemTypePin.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_is_dirty()

status_t pin_db_is_dirty

(

bool *

is_dirty_out

)

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

Parameters

[out]

is_dirty_out

Set to true if at least one record is dirty.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_mark_synced()

status_t pin_db_mark_synced	(	const uint8_t *	key,
		int	key_len
	)

Mark a record of the pin database as synced.

The key is the pin UUID.

Parameters

key	Key data.
key_len	Length of key in bytes.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_next_item_header()

status_t pin_db_next_item_header	(	TimelineItem *	next_item_out,
		TimelineItemStorageFilterCallback	filter
	)

Read the header of the earliest pin within the maximum age.

Parameters

[out]	next_item_out	Item with only the header filled in.
	filter	Optional filter, returns false to skip an item.

Return values

S_SUCCESS	Found.
S_NO_MORE_ITEMS	No matching pin.

Returns

Other error codes on failure.

pin_db_read()

status_t pin_db_read	(	const uint8_t *	key,
		int	key_len,
		uint8_t *	val_out,
		int	val_out_len
	)

Read a record from the pin database.

The key is the pin UUID.

Parameters

	key	Key data.
	key_len	Length of key in bytes.
[out]	val_out	Buffer for the value.
	val_out_len	Size of val_out in bytes.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_read_item_header()

status_t pin_db_read_item_header	(	TimelineItem *	item_out,
		TimelineItemId *	id
	)

Read the header of a pin.

Parameters

[out]	item_out	Item with only the header filled in.
	id	Pin UUID.

Returns

S_SUCCESS on success, an error code otherwise.

pin_db_set_status_bits()

status_t pin_db_set_status_bits	(	const TimelineItemId *	id,
		uint8_t	status
	)

Overwrite the status bits of a pin.

Parameters

id	Pin UUID.
status	New status bits.

Returns

S_SUCCESS on success, an error code otherwise.