diff options
Diffstat (limited to 'lib/flipper_format/flipper_format.h')
| -rw-r--r-- | lib/flipper_format/flipper_format.h | 471 |
1 files changed, 471 insertions, 0 deletions
diff --git a/lib/flipper_format/flipper_format.h b/lib/flipper_format/flipper_format.h new file mode 100644 index 00000000..c23e02fc --- /dev/null +++ b/lib/flipper_format/flipper_format.h @@ -0,0 +1,471 @@ +/** + * @file flipper_format.h + * Flipper File Format helper library. + * + * Flipper File Format is a fairly simple format for storing data in a file. + * + * Flipper file structure: + * + * ~~~~~~~~~~~~~~~~~~~~~ + * # Commentary + * Field name: field value + * ~~~~~~~~~~~~~~~~~~~~~ + * + * Lines starting with the # character are ignored (considered as comments). The separator between the name of the value and the value itself is the string ": ". + * + * Currently supported types: + * + * ~~~~~~~~~~~~~~~~~~~~~ + * String: text + * Int32: 1 2 -3 4 + * Uint32: 1 2 3 4 + * Float: 1.0 1234.654 + * Hex: A4 B3 C2 D1 12 FF + * ~~~~~~~~~~~~~~~~~~~~~ + * + * End of line is LF when writing, but CR is supported when reading. + * + * The library is designed in such a way that comments and field values are completely ignored when searching for keys, that is, they do not consume memory. + * + * File example: + * + * ~~~~~~~~~~~~~~~~~~~~~ + * Filetype: Flipper Test File + * Version: 1 + * # Just test file + * String: String value + * UINT: 1234 + * Hex: 00 01 FF A3 + * ~~~~~~~~~~~~~~~~~~~~~ + * + * Writing: + * + * ~~~~~~~~~~~~~~~~~~~~~ + * FlipperFormat format = flipper_format_file_alloc(storage); + * + * do { + * const uint32_t version = 1; + * const char* string_value = "String value"; + * const uint32_t uint32_value = 1234; + * const uint16_t array_size = 4; + * const uint8_t* array[array_size] = {0x00, 0x01, 0xFF, 0xA3}; + * + * if(!flipper_format_file_open_new(format, "/ext/flipper_format_test")) break; + * if(!flipper_format_write_header_cstr(format, "Flipper Test File", version)) break; + * if(!flipper_format_write_comment_cstr(format, "Just test file")) break; + * if(!flipper_format_write_string_cstr(format, "String", string_value)) break; + * if(!flipper_format_write_uint32(format, "UINT", &uint32_value, 1)) break; + * if(!flipper_format_write_hex(format, "Hex Array", array, array_size)) break; + * + * // signal that the file was written successfully + * } while(0); + * + * flipper_format_free(file); + * ~~~~~~~~~~~~~~~~~~~~~ + * + * Reading: + * + * ~~~~~~~~~~~~~~~~~~~~~ + * FlipperFormat file = flipper_format_file_alloc(storage); + * + * do { + * uint32_t version = 1; + * string_t file_type; + * string_t string_value; + * uint32_t uint32_value = 1; + * uint16_t array_size = 4; + * uint8_t* array[array_size] = {0}; + * string_init(file_type); + * string_init(string_value); + * + * if(!flipper_format_file_open_existing(file, "/ext/flipper_format_test")) break; + * if(!flipper_format_read_header(file, file_type, &version)) break; + * if(!flipper_format_read_string(file, "String", string_value)) break; + * if(!flipper_format_read_uint32(file, "UINT", &uint32_value, 1)) break; + * if(!flipper_format_read_hex(file, "Hex Array", array, array_size)) break; + * + * // signal that the file was read successfully + * } while(0); + * + * flipper_format_free(file); + * ~~~~~~~~~~~~~~~~~~~~~ + * + */ + +#pragma once +#include <stdint.h> +#include <mlib/m-string.h> +#include <storage/storage.h> + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct FlipperFormat FlipperFormat; + +/** + * Allocate FlipperFormat as string. + * @return FlipperFormat* pointer to a FlipperFormat instance + */ +FlipperFormat* flipper_format_string_alloc(); + +/** + * Allocate FlipperFormat as file. + * @return FlipperFormat* pointer to a FlipperFormat instance + */ +FlipperFormat* flipper_format_file_alloc(Storage* storage); + +/** + * Open existing file. + * Use only if FlipperFormat allocated as a file. + * @param flipper_format Pointer to a FlipperFormat instance + * @param path File path + * @return True on success + */ +bool flipper_format_file_open_existing(FlipperFormat* flipper_format, const char* path); + +/** + * Open existing file for writing and add values to the end of file. + * Use only if FlipperFormat allocated as a file. + * @param flipper_format Pointer to a FlipperFormat instance + * @param path File path + * @return True on success + */ +bool flipper_format_file_open_append(FlipperFormat* flipper_format, const char* path); + +/** + * Open file. Creates a new file, or deletes the contents of the file if it already exists. + * Use only if FlipperFormat allocated as a file. + * @param flipper_format Pointer to a FlipperFormat instance + * @param path File path + * @return True on success + */ +bool flipper_format_file_open_always(FlipperFormat* flipper_format, const char* path); + +/** + * Open file. Creates a new file, fails if file already exists. + * Use only if FlipperFormat allocated as a file. + * @param flipper_format Pointer to a FlipperFormat instance + * @param path File path + * @return True on success + */ +bool flipper_format_file_open_new(FlipperFormat* flipper_format, const char* path); + +/** + * Closes the file, use only if FlipperFormat allocated as a file. + * @param flipper_format + * @return true + * @return false + */ +bool flipper_format_file_close(FlipperFormat* flipper_format); + +/** + * Free FlipperFormat. + * @param flipper_format Pointer to a FlipperFormat instance + */ +void flipper_format_free(FlipperFormat* flipper_format); + +/** + * Set FlipperFormat mode. + * @param flipper_format Pointer to a FlipperFormat instance + * @param strict_mode True obligates not to skip valid fields. False by default. + */ +void flipper_format_set_strict_mode(FlipperFormat* flipper_format, bool strict_mode); + +/** + * Rewind the RW pointer. + * @param flipper_format Pointer to a FlipperFormat instance + * @return True on success + */ +bool flipper_format_rewind(FlipperFormat* flipper_format); + +/** + * Read the header (file type and version). + * @param flipper_format Pointer to a FlipperFormat instance + * @param filetype File type string + * @param version Version Value + * @return True on success + */ +bool flipper_format_read_header( + FlipperFormat* flipper_format, + string_t filetype, + uint32_t* version); + +/** + * Write the header (file type and version). + * @param flipper_format Pointer to a FlipperFormat instance + * @param filetype File type string + * @param version Version Value + * @return True on success + */ +bool flipper_format_write_header( + FlipperFormat* flipper_format, + string_t filetype, + const uint32_t version); + +/** + * Write the header (file type and version). Plain C string version. + * @param flipper_format Pointer to a FlipperFormat instance + * @param filetype File type string + * @param version Version Value + * @return True on success + */ +bool flipper_format_write_header_cstr( + FlipperFormat* flipper_format, + const char* filetype, + const uint32_t version); + +/** + * Get the count of values by key + * @param flipper_format Pointer to a FlipperFormat instance + * @param key + * @param count + * @return bool + */ +bool flipper_format_get_value_count( + FlipperFormat* flipper_format, + const char* key, + uint32_t* count); + +/** + * Read a string by key + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @return True on success + */ +bool flipper_format_read_string(FlipperFormat* flipper_format, const char* key, string_t data); + +/** + * Write key and string + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @return True on success + */ +bool flipper_format_write_string(FlipperFormat* flipper_format, const char* key, string_t data); + +/** + * Write key and string. Plain C string version. + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @return True on success + */ +bool flipper_format_write_string_cstr( + FlipperFormat* flipper_format, + const char* key, + const char* data); + +/** + * Read array of uint32 by key + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @param data_size Values count + * @return True on success + */ +bool flipper_format_read_uint32( + FlipperFormat* flipper_format, + const char* key, + uint32_t* data, + const uint16_t data_size); + +/** + * Write key and array of uint32 + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @param data_size Values count + * @return True on success + */ +bool flipper_format_write_uint32( + FlipperFormat* flipper_format, + const char* key, + const uint32_t* data, + const uint16_t data_size); + +/** + * Read array of int32 by key + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @param data_size Values count + * @return True on success + */ +bool flipper_format_read_int32( + FlipperFormat* flipper_format, + const char* key, + int32_t* data, + const uint16_t data_size); + +/** + * Write key and array of int32 + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @param data_size Values count + * @return True on success + */ +bool flipper_format_write_int32( + FlipperFormat* flipper_format, + const char* key, + const int32_t* data, + const uint16_t data_size); + +/** + * Read array of float by key + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @param data_size Values count + * @return True on success + */ +bool flipper_format_read_float( + FlipperFormat* flipper_format, + const char* key, + float* data, + const uint16_t data_size); + +/** + * Write key and array of float + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @param data_size Values count + * @return True on success + */ +bool flipper_format_write_float( + FlipperFormat* flipper_format, + const char* key, + const float* data, + const uint16_t data_size); + +/** + * Read array of hex-formatted bytes by key + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @param data_size Values count + * @return True on success + */ +bool flipper_format_read_hex( + FlipperFormat* flipper_format, + const char* key, + uint8_t* data, + const uint16_t data_size); + +/** + * Write key and array of hex-formatted bytes + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @param data_size Values count + * @return True on success + */ +bool flipper_format_write_hex( + FlipperFormat* flipper_format, + const char* key, + const uint8_t* data, + const uint16_t data_size); + +/** + * Write comment + * @param flipper_format Pointer to a FlipperFormat instance + * @param data Comment text + * @return True on success + */ +bool flipper_format_write_comment(FlipperFormat* flipper_format, string_t data); + +/** + * Write comment. Plain C string version. + * @param flipper_format Pointer to a FlipperFormat instance + * @param data Comment text + * @return True on success + */ +bool flipper_format_write_comment_cstr(FlipperFormat* flipper_format, const char* data); + +/** + * Removes the first matching key and its value. Sets the RW pointer to a position of deleted data. + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @return True on success + */ +bool flipper_format_delete_key(FlipperFormat* flipper_format, const char* key); + +/** + * Updates the value of the first matching key to a string value. Sets the RW pointer to a position at the end of inserted data. + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @return True on success + */ +bool flipper_format_update_string(FlipperFormat* flipper_format, const char* key, string_t data); + +/** + * Updates the value of the first matching key to a string value. Plain C version. Sets the RW pointer to a position at the end of inserted data. + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @return True on success + */ +bool flipper_format_update_string_cstr( + FlipperFormat* flipper_format, + const char* key, + const char* data); + +/** + * Updates the value of the first matching key to a uint32 array value. Sets the RW pointer to a position at the end of inserted data. + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @return True on success + */ +bool flipper_format_update_uint32( + FlipperFormat* flipper_format, + const char* key, + const uint32_t* data, + const uint16_t data_size); + +/** + * Updates the value of the first matching key to a int32 array value. Sets the RW pointer to a position at the end of inserted data. + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @return True on success + */ +bool flipper_format_update_int32( + FlipperFormat* flipper_format, + const char* key, + const int32_t* data, + const uint16_t data_size); + +/** + * Updates the value of the first matching key to a float array value. Sets the RW pointer to a position at the end of inserted data. + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @return True on success + */ +bool flipper_format_update_float( + FlipperFormat* flipper_format, + const char* key, + const float* data, + const uint16_t data_size); + +/** + * Updates the value of the first matching key to an array of hex-formatted bytes. Sets the RW pointer to a position at the end of inserted data. + * @param flipper_format Pointer to a FlipperFormat instance + * @param key Key + * @param data Value + * @return True on success + */ +bool flipper_format_update_hex( + FlipperFormat* flipper_format, + const char* key, + const uint8_t* data, + const uint16_t data_size); + +#ifdef __cplusplus +} +#endif
\ No newline at end of file |