Storage

A mechanism to store persistent application data and state. More...

Collaboration diagram for Storage:

Macros
#define	PERSIST_DATA_MAX_LENGTH   256
	The maximum size of a persist value in bytes.
#define	PERSIST_STRING_MAX_LENGTH   PERSIST_DATA_MAX_LENGTH
	The maximum size of a persist string in bytes including the NULL terminator.
#define	PERSIST_DATA_MAX_LENGTH   256
	The maximum size of a persist value in bytes.
#define	PERSIST_STRING_MAX_LENGTH   PERSIST_DATA_MAX_LENGTH
	The maximum size of a persist string in bytes including the NULL terminator.

Typedefs
typedef enum StatusCode	StatusCode
	Status codes. See status_t.
typedef int32_t	status_t
	Return value for system operations. See StatusCode for possible values.
typedef enum StatusCode	StatusCode
	Status codes. See status_t.
typedef int32_t	status_t
	Return value for system operations. See StatusCode for possible values.

Enumerations
enum	StatusCode {   S_SUCCESS = 0, E_ERROR = -1, E_UNKNOWN = -2, E_INTERNAL = -3,   E_INVALID_ARGUMENT = -4, E_OUT_OF_MEMORY = -5, E_OUT_OF_STORAGE = -6, E_OUT_OF_RESOURCES = -7,   E_RANGE = -8, E_DOES_NOT_EXIST = -9, E_INVALID_OPERATION = -10, E_BUSY = -11,   E_AGAIN = -12, S_TRUE = 1, S_FALSE = 0, S_NO_MORE_ITEMS = 2,   S_NO_ACTION_REQUIRED = 3, S_SUCCESS = 0, E_ERROR = -1, E_UNKNOWN = -2,   E_INTERNAL = -3, E_INVALID_ARGUMENT = -4, E_OUT_OF_MEMORY = -5, E_OUT_OF_STORAGE = -6,   E_OUT_OF_RESOURCES = -7, E_RANGE = -8, E_DOES_NOT_EXIST = -9, E_INVALID_OPERATION = -10,   E_BUSY = -11, E_AGAIN = -12, S_TRUE = 1, S_FALSE = 0,   S_NO_MORE_ITEMS = 2, S_NO_ACTION_REQUIRED = 3 }
	Status codes. See status_t. More...
enum	StatusCode {   S_SUCCESS = 0, E_ERROR = -1, E_UNKNOWN = -2, E_INTERNAL = -3,   E_INVALID_ARGUMENT = -4, E_OUT_OF_MEMORY = -5, E_OUT_OF_STORAGE = -6, E_OUT_OF_RESOURCES = -7,   E_RANGE = -8, E_DOES_NOT_EXIST = -9, E_INVALID_OPERATION = -10, E_BUSY = -11,   E_AGAIN = -12, S_TRUE = 1, S_FALSE = 0, S_NO_MORE_ITEMS = 2,   S_NO_ACTION_REQUIRED = 3, S_SUCCESS = 0, E_ERROR = -1, E_UNKNOWN = -2,   E_INTERNAL = -3, E_INVALID_ARGUMENT = -4, E_OUT_OF_MEMORY = -5, E_OUT_OF_STORAGE = -6,   E_OUT_OF_RESOURCES = -7, E_RANGE = -8, E_DOES_NOT_EXIST = -9, E_INVALID_OPERATION = -10,   E_BUSY = -11, E_AGAIN = -12, S_TRUE = 1, S_FALSE = 0,   S_NO_MORE_ITEMS = 2, S_NO_ACTION_REQUIRED = 3 }
	Status codes. See status_t. More...

Functions
bool	persist_exists (const uint32_t key)
int	persist_get_size (const uint32_t key)
bool	persist_read_bool (const uint32_t key)
int32_t	persist_read_int (const uint32_t key)
int	persist_read_data (const uint32_t key, void *buffer, const size_t buffer_size)
int	persist_read_string (const uint32_t key, char *buffer, const size_t buffer_size)
status_t	persist_write_bool (const uint32_t key, const bool value)
status_t	persist_write_int (const uint32_t key, const int32_t value)
int	persist_write_data (const uint32_t key, const void *data, const size_t size)
int	persist_write_string (const uint32_t key, const char *cstring)
status_t	persist_delete (const uint32_t key)

Detailed Description

A mechanism to store persistent application data and state.

The Persistent Storage API provides you with a mechanism for performing a variety of tasks, like saving user settings, caching data from the phone app, or counting high scores for Pebble watchapp games.

In Pebble OS, storage is defined by a collection of fields that you can create, modify or delete. In the API, a field is specified as a key with a corresponding value.

Using the Storage API, every app is able to get its own persistent storage space. Each value in that space is associated with a uint32_t key.

Storage supports saving integers, strings and byte arrays. The maximum size of byte arrays and strings is defined by PERSIST_DATA_MAX_LENGTH (currently set to 256 bytes). You call the function persist_exists(key), which returns a boolean indicating if the key exists or not. The Storage API enables your app to save its state, and when compared to using AppMessage to retrieve values from the phone, it provides you with a much faster way to restore state. In addition, it draws less power from the battery.

Note that the size of all persisted values cannot exceed 4K per app.

Enumeration Type Documentation

StatusCode [1/2]

enum StatusCode

Status codes. See status_t.

Enumerator
S_SUCCESS	Operation completed successfully.
E_ERROR	An error occurred (no description).
E_UNKNOWN	No idea what went wrong.
E_INTERNAL	There was a generic internal logic error.
E_INVALID_ARGUMENT	The function was not called correctly.
E_OUT_OF_MEMORY	Insufficient allocatable memory available.
E_OUT_OF_STORAGE	Insufficient long-term storage available.
E_OUT_OF_RESOURCES	Insufficient resources available.
E_RANGE	Argument out of range (may be dynamic).
E_DOES_NOT_EXIST	Target of operation does not exist.
E_INVALID_OPERATION	Operation not allowed (may depend on state).
E_BUSY	Another operation prevented this one.
E_AGAIN	Operation not completed; try again.
S_TRUE	Equivalent of boolean true.
S_FALSE	Equivalent of boolean false.
S_NO_MORE_ITEMS	For list-style requests. At end of list.
S_NO_ACTION_REQUIRED	No action was taken as none was required.
S_SUCCESS	Operation completed successfully.
E_ERROR	An error occurred (no description).
E_UNKNOWN	No idea what went wrong.
E_INTERNAL	There was a generic internal logic error.
E_INVALID_ARGUMENT	The function was not called correctly.
E_OUT_OF_MEMORY	Insufficient allocatable memory available.
E_OUT_OF_STORAGE	Insufficient long-term storage available.
E_OUT_OF_RESOURCES	Insufficient resources available.
E_RANGE	Argument out of range (may be dynamic).
E_DOES_NOT_EXIST	Target of operation does not exist.
E_INVALID_OPERATION	Operation not allowed (may depend on state).
E_BUSY	Another operation prevented this one.
E_AGAIN	Operation not completed; try again.
S_TRUE	Equivalent of boolean true.
S_FALSE	Equivalent of boolean false.
S_NO_MORE_ITEMS	For list-style requests. At end of list.
S_NO_ACTION_REQUIRED	No action was taken as none was required.

StatusCode [2/2]

enum StatusCode

Status codes. See status_t.

Enumerator
S_SUCCESS	Operation completed successfully.
E_ERROR	An error occurred (no description).
E_UNKNOWN	No idea what went wrong.
E_INTERNAL	There was a generic internal logic error.
E_INVALID_ARGUMENT	The function was not called correctly.
E_OUT_OF_MEMORY	Insufficient allocatable memory available.
E_OUT_OF_STORAGE	Insufficient long-term storage available.
E_OUT_OF_RESOURCES	Insufficient resources available.
E_RANGE	Argument out of range (may be dynamic).
E_DOES_NOT_EXIST	Target of operation does not exist.
E_INVALID_OPERATION	Operation not allowed (may depend on state).
E_BUSY	Another operation prevented this one.
E_AGAIN	Operation not completed; try again.
S_TRUE	Equivalent of boolean true.
S_FALSE	Equivalent of boolean false.
S_NO_MORE_ITEMS	For list-style requests. At end of list.
S_NO_ACTION_REQUIRED	No action was taken as none was required.
S_SUCCESS	Operation completed successfully.
E_ERROR	An error occurred (no description).
E_UNKNOWN	No idea what went wrong.
E_INTERNAL	There was a generic internal logic error.
E_INVALID_ARGUMENT	The function was not called correctly.
E_OUT_OF_MEMORY	Insufficient allocatable memory available.
E_OUT_OF_STORAGE	Insufficient long-term storage available.
E_OUT_OF_RESOURCES	Insufficient resources available.
E_RANGE	Argument out of range (may be dynamic).
E_DOES_NOT_EXIST	Target of operation does not exist.
E_INVALID_OPERATION	Operation not allowed (may depend on state).
E_BUSY	Another operation prevented this one.
E_AGAIN	Operation not completed; try again.
S_TRUE	Equivalent of boolean true.
S_FALSE	Equivalent of boolean false.
S_NO_MORE_ITEMS	For list-style requests. At end of list.
S_NO_ACTION_REQUIRED	No action was taken as none was required.

Function Documentation

persist_delete()

status_t persist_delete

(

const uint32_t

key

)

Deletes the value of a key from persistent storage.

Parameters

key	The key of the field to delete from.

persist_exists()

bool persist_exists

(

const uint32_t

key

)

Checks whether a value has been set for a given key in persistent storage.

Parameters

key	The key of the field to check.

Returns

true if a value exists, otherwise false.

persist_get_size()

int persist_get_size

(

const uint32_t

key

)

Gets the size of a value for a given key in persistent storage.

Parameters

key	The key of the field to lookup the data size.

Returns

The size of the value in bytes or E_DOES_NOT_EXIST if there is no field matching the given key.

persist_read_bool()

bool persist_read_bool

(

const uint32_t

key

)

Reads a bool value for a given key from persistent storage. If the value has not yet been set, this will return false.

Parameters

key	The key of the field to read from.

Returns

The bool value of the key to read from.

persist_read_data()

int persist_read_data	(	const uint32_t	key,
		void *	buffer,
		const size_t	buffer_size
	)

Reads a blob of data for a given key from persistent storage into a given buffer. If the value has not yet been set, the given buffer is left unchanged.

Parameters

key	The key of the field to read from.
buffer	The pointer to a buffer to be written to.
buffer_size	The maximum size of the given buffer.

Returns

The number of bytes written into the buffer or E_DOES_NOT_EXIST if there is no field matching the given key.

persist_read_int()

int32_t persist_read_int

(

const uint32_t

key

)

Reads an int value for a given key from persistent storage.

Note

The int is a signed 32-bit integer. If the value has not yet been set, this will return 0.

Parameters

key	The key of the field to read from.

Returns

The int value of the key to read from.

persist_read_string()

int persist_read_string	(	const uint32_t	key,
		char *	buffer,
		const size_t	buffer_size
	)

Reads a string for a given key from persistent storage into a given buffer. The string will be null terminated. If the value has not yet been set, the given buffer is left unchanged.

Parameters

key	The key of the field to read from.
buffer	The pointer to a buffer to be written to.
buffer_size	The maximum size of the given buffer. This includes the null character.

Returns

The number of bytes written into the buffer or E_DOES_NOT_EXIST if there is no field matching the given key.

persist_write_bool()

status_t persist_write_bool	(	const uint32_t	key,
		const bool	value
	)

Writes a bool value flag for a given key into persistent storage.

Parameters

key	The key of the field to write to.
value	The boolean value to write.

Returns

The number of bytes written if successful, a value from StatusCode otherwise.

persist_write_data()

int persist_write_data	(	const uint32_t	key,
		const void *	data,
		const size_t	size
	)

Writes a blob of data of a specified size in bytes for a given key into persistent storage. The maximum size is PERSIST_DATA_MAX_LENGTH

Parameters

key	The key of the field to write to.
data	The pointer to the blob of data.
size	The size in bytes.

Returns

The number of bytes written if successful, a value from StatusCode otherwise.

persist_write_int()

status_t persist_write_int	(	const uint32_t	key,
		const int32_t	value
	)

Writes an int value for a given key into persistent storage.

Note

The int is a signed 32-bit integer.

Parameters

key	The key of the field to write to.
value	The int value to write.

Returns

The number of bytes written if successful, a value from StatusCode otherwise.

persist_write_string()

int persist_write_string	(	const uint32_t	key,
		const char *	cstring
	)

Writes a string a given key into persistent storage. The maximum size is PERSIST_STRING_MAX_LENGTH including the null terminator.

Parameters

key	The key of the field to write to.
cstring	The pointer to null terminated string.

Returns

The number of bytes written if successful, a value from StatusCode otherwise.