/* * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #pragma once #include "util/uuid.h" #include "system/status_codes.h" #include #include #include //! @file persist.h //! @addtogroup Foundation //! @{ //! @addtogroup Storage //! \brief 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 \ref 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. //! @{ //! The maximum size of a persist value in bytes #define PERSIST_DATA_MAX_LENGTH 256 //! The maximum size of a persist string in bytes including the NULL terminator #define PERSIST_STRING_MAX_LENGTH PERSIST_DATA_MAX_LENGTH struct PersistStore; //! Checks whether a value has been set for a given key in persistent storage. //! @param key The key of the field to check. //! @return true if a value exists, otherwise false. bool persist_exists(const uint32_t key); //! Gets the size of a value for a given key in persistent storage. //! @param key The key of the field to lookup the data size. //! @return The size of the value in bytes or \ref E_DOES_NOT_EXIST //! if there is no field matching the given key. int persist_get_size(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. //! @param key The key of the field to read from. //! @return The bool value of the key to read from. bool persist_read_bool(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. //! @param key The key of the field to read from. //! @return The int value of the key to read from. int32_t persist_read_int(const uint32_t key); //! 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. //! @param key The key of the field to read from. //! @param buffer The pointer to a buffer to be written to. //! @param buffer_size The maximum size of the given buffer. //! @return The number of bytes written into the buffer or \ref E_DOES_NOT_EXIST //! if there is no field matching the given key. int persist_read_data(const uint32_t key, void *buffer, const size_t buffer_size); // Legacy version to prevent previous app breakage, __deprecated preserves order int persist_read_data__deprecated(const uint32_t key, const size_t buffer_size, void *buffer); //! 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. //! @param key The key of the field to read from. //! @param buffer The pointer to a buffer to be written to. //! @param buffer_size The maximum size of the given buffer. This includes the null character. //! @return The number of bytes written into the buffer or \ref E_DOES_NOT_EXIST //! if there is no field matching the given key. int persist_read_string(const uint32_t key, char *buffer, const size_t buffer_size); // Legacy version to prevent previous app breakage, __deprecated preserves order int persist_read_string__deprecated(const uint32_t key, const size_t buffer_size, char *buffer); //! Writes a bool value flag for a given key into persistent storage. //! @param key The key of the field to write to. //! @param value The boolean value to write. //! @return The number of bytes written if successful, a value from \ref StatusCode otherwise. status_t persist_write_bool(const uint32_t key, const bool value); //! Writes an int value for a given key into persistent storage. //! @note The int is a signed 32-bit integer. //! @param key The key of the field to write to. //! @param value The int value to write. //! @return The number of bytes written if successful, a value from \ref StatusCode otherwise. status_t persist_write_int(const uint32_t key, const int32_t value); //! Writes a blob of data of a specified size in bytes for a given key into persistent storage. //! The maximum size is \ref PERSIST_DATA_MAX_LENGTH //! @param key The key of the field to write to. //! @param data The pointer to the blob of data. //! @param size The size in bytes. //! @return The number of bytes written if successful, a value from \ref StatusCode otherwise. int persist_write_data(const uint32_t key, const void *data, const size_t size); // Legacy version to prevent previous app breakage, __deprecated preserves order int persist_write_data__deprecated(const uint32_t key, const size_t size, const void *data); //! Writes a string a given key into persistent storage. //! The maximum size is \ref PERSIST_STRING_MAX_LENGTH including the null terminator. //! @param key The key of the field to write to. //! @param cstring The pointer to null terminated string. //! @return The number of bytes written if successful, a value from \ref StatusCode otherwise. int persist_write_string(const uint32_t key, const char *cstring); //! Deletes the value of a key from persistent storage. //! @param key The key of the field to delete from. status_t persist_delete(const uint32_t key); //! @} // end addtogroup Storage //! @} // end addtogroup Foundation