Timeline item storage

Settings file store of timeline items, shared by the pin and reminder databases. More...

Data Structures
struct	TimelineItemStorage
	Timeline item store backed by a settings file. More...

Typedefs
typedef bool(*	TimelineItemStorageFilterCallback) (SerializedTimelineItemHeader *hdr, void *context)
	Filter for timeline_item_storage_next_item().
typedef SettingsFileEachCallback	TimelineItemStorageEachCallback
	Callback for timeline_item_storage_each().
typedef void(*	TimelineItemStorageChildDeleteCallback) (const Uuid *id)
	Callback of timeline_item_storage_delete_with_parent().

Functions
void	timeline_item_storage_init (TimelineItemStorage *storage, char *filename, uint32_t max_size, uint32_t max_age)
	Initialize a storage and open its settings file.
void	timeline_item_storage_deinit (TimelineItemStorage *storage)
	Close the settings file of a storage.
status_t	timeline_item_storage_compact (TimelineItemStorage *storage)
	Compact and shrink the backing settings file.
bool	timeline_item_storage_exists_with_parent (TimelineItemStorage *storage, const Uuid *parent_id)
	Check whether any item has a given parent.
status_t	timeline_item_storage_flush (TimelineItemStorage *storage)
	Delete all items except those created on the watch.
status_t	timeline_item_storage_delete (TimelineItemStorage *storage, const uint8_t *key, int key_len)
	Delete an item.
status_t	timeline_item_storage_read (TimelineItemStorage *storage, const uint8_t *key, int key_len, uint8_t *val_out, int val_len)
	Read a serialized item.
status_t	timeline_item_storage_get_from_settings_record (SettingsFile *file, SettingsRecordInfo *info, TimelineItem *item)
	Deserialize the item of a settings file record, from an each callback.
status_t	timeline_item_storage_set_status_bits (TimelineItemStorage *storage, const uint8_t *key, int key_len, uint8_t status)
	Overwrite the status bits of an item in place.
int	timeline_item_storage_get_len (TimelineItemStorage *storage, const uint8_t *key, int key_len)
	Get the length of a serialized item.
status_t	timeline_item_storage_insert (TimelineItemStorage *storage, const uint8_t *key, int key_len, const uint8_t *val, int val_len, bool mark_as_synced)
	Insert or replace a serialized item.
status_t	timeline_item_storage_each (TimelineItemStorage *storage, TimelineItemStorageEachCallback each, void *data)
	Call a function for every record, with the storage locked.
status_t	timeline_item_storage_mark_synced (TimelineItemStorage *storage, const uint8_t *key, int key_len)
	Mark an item as synced.
status_t	timeline_item_storage_delete_with_parent (TimelineItemStorage *storage, const Uuid *parent_id, TimelineItemStorageChildDeleteCallback child_delete_cb)
	Delete the children of a parent.
status_t	timeline_item_storage_next_item (TimelineItemStorage *storage, Uuid *id_out, TimelineItemStorageFilterCallback filter_cb)
	Find the earliest item that is not older than the maximum age.
bool	timeline_item_storage_is_empty (TimelineItemStorage *storage)
	Check whether the storage holds no valid item.

Detailed Description

Settings file store of timeline items, shared by the pin and reminder databases.

Items are keyed by UUID. The flags and status bytes of the item header are stored inverted; the read API restores them.

---

Data Structure Documentation

TimelineItemStorage

struct TimelineItemStorage

Timeline item store backed by a settings file.

Data Fields
SettingsFile	file	Backing settings file, kept open between init and deinit.
uint32_t	max_item_age	Age in seconds past which items are rejected or skipped.
size_t	max_size	Maximum settings file size in bytes.
struct pbl_mutex	mutex	Serializes access to file.
char *	name	Settings file name.

Typedef Documentation

TimelineItemStorageChildDeleteCallback

typedef void(* TimelineItemStorageChildDeleteCallback) (const Uuid *id)

Callback of timeline_item_storage_delete_with_parent().

Parameters

id	UUID of the deleted child.

TimelineItemStorageEachCallback

typedef SettingsFileEachCallback TimelineItemStorageEachCallback

Callback for timeline_item_storage_each().

Warning

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

TimelineItemStorageFilterCallback

typedef bool(* TimelineItemStorageFilterCallback) (SerializedTimelineItemHeader *hdr, void *context)

Filter for timeline_item_storage_next_item().

Parameters

hdr	Item header, with flags and status restored.
context	Iteration context of the caller, not user data.

Returns

true to consider the item, false to skip it.

Function Documentation

timeline_item_storage_compact()

status_t timeline_item_storage_compact

(

TimelineItemStorage *

storage

)

Compact and shrink the backing settings file.

Parameters

storage

Storage.

Returns

S_SUCCESS on success, an error code otherwise.

timeline_item_storage_deinit()

void timeline_item_storage_deinit

(

TimelineItemStorage *

storage

)

Close the settings file of a storage.

Parameters

storage

Storage.

timeline_item_storage_delete()

status_t timeline_item_storage_delete	(	TimelineItemStorage *	storage,
		const uint8_t *	key,
		int	key_len
	)

Delete an item.

Parameters

storage	Storage.
key	Item UUID.
key_len	Length of key, must be UUID_SIZE.

Returns

S_SUCCESS on success, an error code otherwise.

timeline_item_storage_delete_with_parent()

status_t timeline_item_storage_delete_with_parent	(	TimelineItemStorage *	storage,
		const Uuid *	parent_id,
		TimelineItemStorageChildDeleteCallback	child_delete_cb
	)

Delete the children of a parent.

At most three children are deleted per call.

Parameters

storage	Storage.
parent_id	Parent UUID.
child_delete_cb	Optional callback invoked for each deleted child.

Returns

S_SUCCESS on success, an error code otherwise.

timeline_item_storage_each()

status_t timeline_item_storage_each	(	TimelineItemStorage *	storage,
		TimelineItemStorageEachCallback	each,
		void *	data
	)

Call a function for every record, with the storage locked.

Warning

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

Parameters

storage	Storage.
each	Callback.
data	User data passed to each.

Returns

S_SUCCESS on success, an error code otherwise.

timeline_item_storage_exists_with_parent()

bool timeline_item_storage_exists_with_parent	(	TimelineItemStorage *	storage,
		const Uuid *	parent_id
	)

Check whether any item has a given parent.

Parameters

storage	Storage.
parent_id	Parent UUID.

Returns

true if at least one item has this parent.

timeline_item_storage_flush()

status_t timeline_item_storage_flush

(

TimelineItemStorage *

storage

)

Delete all items except those created on the watch.

Parameters

storage

Storage.

Returns

S_SUCCESS on success, an error code otherwise.

timeline_item_storage_get_from_settings_record()

status_t timeline_item_storage_get_from_settings_record	(	SettingsFile *	file,
		SettingsRecordInfo *	info,
		TimelineItem *	item
	)

Deserialize the item of a settings file record, from an each callback.

Temporarily allocates the whole record on the kernel heap; use sparingly.

Parameters

	file	Settings file being iterated.
	info	Current record.
[out]	item	Item; free its buffer with timeline_item_free_allocated_buffer().

Returns

S_SUCCESS on success, E_INTERNAL if the record cannot be deserialized.

timeline_item_storage_get_len()

int timeline_item_storage_get_len	(	TimelineItemStorage *	storage,
		const uint8_t *	key,
		int	key_len
	)

Get the length of a serialized item.

Parameters

storage	Storage.
key	Item UUID.
key_len	Length of key in bytes.

Returns

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

timeline_item_storage_init()

void timeline_item_storage_init	(	TimelineItemStorage *	storage,
		char *	filename,
		uint32_t	max_size,
		uint32_t	max_age
	)

Initialize a storage and open its settings file.

Parameters

[out]	storage	Storage.
	filename	Settings file name; must outlive the storage.
	max_size	Maximum file size in bytes.
	max_age	Age in seconds past which items are rejected or skipped.

timeline_item_storage_insert()

status_t timeline_item_storage_insert	(	TimelineItemStorage *	storage,
		const uint8_t *	key,
		int	key_len,
		const uint8_t *	val,
		int	val_len,
		bool	mark_as_synced
	)

Insert or replace a serialized item.

The item layout is validated, and items whose end time is older than the maximum age are rejected.

Parameters

storage	Storage.
key	Item UUID.
key_len	Length of key, must be UUID_SIZE.
val	Serialized item. Modified during the call and restored before returning.
val_len	Length of val in bytes.
mark_as_synced	Store the record as synced, i.e. not to be written back to the phone.

Return values

S_SUCCESS	Inserted.
E_INVALID_ARGUMENT	Malformed key or item.
E_INVALID_OPERATION	Item too old.

Returns

Other error codes on failure.

timeline_item_storage_is_empty()

bool timeline_item_storage_is_empty

(

TimelineItemStorage *

storage

)

Check whether the storage holds no valid item.

Parameters

storage

Storage.

Returns

true if empty.

timeline_item_storage_mark_synced()

status_t timeline_item_storage_mark_synced	(	TimelineItemStorage *	storage,
		const uint8_t *	key,
		int	key_len
	)

Mark an item as synced.

Parameters

storage	Storage.
key	Item UUID.
key_len	Length of key in bytes.

Returns

S_SUCCESS on success, an error code otherwise.

timeline_item_storage_next_item()

status_t timeline_item_storage_next_item	(	TimelineItemStorage *	storage,
		Uuid *	id_out,
		TimelineItemStorageFilterCallback	filter_cb
	)

Find the earliest item that is not older than the maximum age.

Parameters

	storage	Storage.
[out]	id_out	UUID of the item.
	filter_cb	Optional filter.

Return values

S_SUCCESS	Found.
S_NO_MORE_ITEMS	No matching item.

Returns

Other error codes on failure.

timeline_item_storage_read()

status_t timeline_item_storage_read	(	TimelineItemStorage *	storage,
		const uint8_t *	key,
		int	key_len,
		uint8_t *	val_out,
		int	val_len
	)

Read a serialized item.

Flags and status of the header are restored.

Parameters

	storage	Storage.
	key	Item UUID.
	key_len	Length of key, must be UUID_SIZE.
[out]	val_out	Buffer for the serialized item.
	val_len	Size of val_out in bytes.

Returns

S_SUCCESS on success, an error code otherwise.

timeline_item_storage_set_status_bits()

status_t timeline_item_storage_set_status_bits	(	TimelineItemStorage *	storage,
		const uint8_t *	key,
		int	key_len,
		uint8_t	status
	)

Overwrite the status bits of an item in place.

Parameters

storage	Storage.
key	Item UUID.
key_len	Length of key, must be UUID_SIZE.
status	New status bits.

Returns

S_SUCCESS on success, an error code otherwise.