mount/flipperzero-firmware
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
flipperzero-firmware/lib/flipper_format/flipper_format.h
Georgii Surkov 806428efeb
[FL-3070] iButton system and app refactoring (#2388) 
* Add 1-wire thermometer example app stub
* Working 1-wire thermometer app
* Refactor app to use threads
* Clean up code, add comments
* Add CRC checking
* Increase update period
* Fix error in fbt
* Revert the old update period
* Use settable pin in onewire_host
* Use settable pin for onewire_slave
* Clear EXTI flag after callback, make private methods static in onewire_slave
* Do not hardcode GPIO pin number
* Remove iButton hal from furi_hal_rfid
* Remove most of furi_hal_ibutton
* Add some of furi_hal_ibutton back
* Slightly neater code
* Update CODEOWNERS
* Add furi_hal_gpio_get_ext_pin_number
* Create README.md
* Temporary get Metakom and Cyfral keys out of the way
* Better enum name
* Syncing work, does not compile
* Syncing work, now compiles
* Working read impl for DS1990 and DS1992
* Add the ability to display extended key data
* Get rid of DialogEx
* Add save and load API
* Better iButtonKey encapsulation
* Fix crash
* Load key code boilerplate
* More load key code boilerplate
* Minor code cleanup
* Implement loading and saving DS1990 keys
* Implement the Info scene
* Implement loading & saving for DS1992
* Implement read error scene stub
* Implement delete confirmation screen
* Better error messages (protocol-dependent)
* Minor old code cleanup
* Remove iButtonDevice, add command callback to iButtonSlave
* Implement draft emulation for DS1990
* Better emulation for DS1990
* Initial emulation implementation for DS1992
* Better common command definitions
* Use common submenu callback, add protocol list
* Improve ViewData screen
* Improve scene_add_type
* Add stubs for write functionality
* Improve naming consistency
* Implement writing a DS1992 onto another one
* Improve DS1992 write code
* Improve DS1992 write code once more
* Prepare write_blank for DS1990, delete ibutton_writer
* Implement writing DS1990 onto blanks
* Fix reading DS1990
* Partially implement writing DS1992 onto blanks
* Implement GUI for writing keys
* Implement GUI for emulating keys
* Reduce memory usage for pretty_format
* Automatically truncate data more than 256 bytes
* Initial implementation of DS1996 (not tested)
* Fix crash due to missing virtual function
* Improve emulation code
* Improve DS1992 emulation code
* Correct return value for onewire_slave_send
* Correct return value for onewire_slave_receive
* Implement emulation for DS1992 & DS1996
* Better constant names
* Simplify & optimise the emulation code
* Remove duplicate code
* Add skip rom command emulation
* Show loading animation for large keys
* Implement manual adding & editing of keys
* Use buffered file streams to speed up saving & loading
* Reset key name before adding a new one
* Sync a buffered file stream before saving
* Use the DSGeneric protocol as a fallback option
* Implement emulation via RPC
* Refactor iButton code in preparation for comparator keys
* Refactor iButton code in preparation for comparator keys once more
* Make some functions static
* Make protocols not rely on one_wire classes
* Improve ProtocolDict usage
* Improve ProtocolDict usage more
* Implement reading Metakom & Cyfral keys
* Rename some files
* Better file structure
* Implement a unified interface for misc protocols
* Implement a unified interface for dallas protocols
* Concrete types for Dallas protocols
* Implement a unified interface for all key types
* Improved type naming
* Improved private types
* Proper types in protocol definitions
* Implement emulation for Cyfral & Metakom keys
* Implement save&load for Metakom & Cyfral keys
* Better type names
* Rename files, better names
* Allocate iButtonProtocols like a normal class
* Reset the key each time the start scene is selected
* Improve comments and constants
* Add ibutton_protocols to SDK headers
* Add ibutton_key to SDK headers
* Add ibutton_key to SDK headers
* Implement reading via cli
* Implement emulation via cli
* Implement writing Dallas blanks via cli
* Correctly revert the editing if cancelled by the user
* Correct committing mishap
* Elide the long text on the info screen
* Change key name for data in Misc keys
* Update iButtonFileFormat.md
* Remember the key's folder
* Save menu position in ReadKeyMenu and SavedKeyMenu
* Correct use of preselected path in file browser

Co-authored-by: Aleksandr Kutuzov <alleteam@gmail.com>
2023-03-02 22:23:33 +09:00

685 lines
20 KiB
C
Raw Blame History

/**
* @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_PATH("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;
* FuriString* file_type;
* FuriString* string_value;
* uint32_t uint32_value = 1;
* uint16_t array_size = 4;
* uint8_t* array[array_size] = {0};
* file_type = furi_string_alloc();
* string_value = furi_string_alloc();
*
* if(!flipper_format_file_open_existing(file, EXT_PATH("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 <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);
/**
* Allocate FlipperFormat as file, buffered mode.
* @return FlipperFormat* pointer to a FlipperFormat instance
*/
FlipperFormat* flipper_format_buffered_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, buffered mode.
* Use only if FlipperFormat allocated as a buffered file.
* @param flipper_format Pointer to a FlipperFormat instance
* @param path File path
* @return True on success
*/
bool flipper_format_buffered_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, or deletes the contents of the file if it already exists, buffered mode.
* Use only if FlipperFormat allocated as a buffered file.
* @param flipper_format Pointer to a FlipperFormat instance
* @param path File path
* @return True on success
*/
bool flipper_format_buffered_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);
/**
* Closes the file, use only if FlipperFormat allocated as a buffered file.
* @param flipper_format
* @return true
* @return false
*/
bool flipper_format_buffered_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);
/**
* Move the RW pointer at the end. Can be useful if you want to add some data after reading.
* @param flipper_format Pointer to a FlipperFormat instance
* @return True on success
*/
bool flipper_format_seek_to_end(FlipperFormat* flipper_format);
/**
* Check if the key exists.
* @param flipper_format Pointer to a FlipperFormat instance
* @param key Key
* @return true key exists
* @return false key is not exists
*/
bool flipper_format_key_exist(FlipperFormat* flipper_format, const char* key);
/**
* 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,
FuriString* 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,
FuriString* 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, FuriString* 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, FuriString* 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 uint64 in hex format 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_uint64(
FlipperFormat* flipper_format,
const char* key,
uint64_t* data,
const uint16_t data_size);
/**
* Write key and array of uint64 in hex format
* @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_uint64(
FlipperFormat* flipper_format,
const char* key,
const uint64_t* data,
const uint16_t data_size);
/**
* 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 bool 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_bool(
FlipperFormat* flipper_format,
const char* key,
bool* data,
const uint16_t data_size);
/**
* Write key and array of bool
* @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_bool(
FlipperFormat* flipper_format,
const char* key,
const bool* 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, FuriString* 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, FuriString* 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 bool 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_bool(
FlipperFormat* flipper_format,
const char* key,
const bool* 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);
/**
* Updates the value of the first matching key to a string value, or adds the key and value if the key did not exist.
* 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_insert_or_update_string(
FlipperFormat* flipper_format,
const char* key,
FuriString* data);
/**
* Updates the value of the first matching key to a string value, or adds the key and value if the key did not exist.
* 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_insert_or_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, or adds the key and value if the key did not exist.
* 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_insert_or_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, or adds the key and value if the key did not exist.
* 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_insert_or_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 bool array value, or adds the key and value if the key did not exist.
* 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_insert_or_update_bool(
FlipperFormat* flipper_format,
const char* key,
const bool* data,
const uint16_t data_size);
/**
* Updates the value of the first matching key to a float array value, or adds the key and value if the key did not exist.
* 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_insert_or_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, or adds the key and value if the key did not exist.
*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_insert_or_update_hex(
FlipperFormat* flipper_format,
const char* key,
const uint8_t* data,
const uint16_t data_size);
#ifdef __cplusplus
}
#endif
Reference in New Issue View Git Blame Copy Permalink