File System
This contains all file system related functionality. More...
Modules |
|
Types | |
File types.
|
|
Macros | |
File specific macros.
|
|
Log Files | |
This contains functional for reading/writing log files.
|
|
Functions |
|
gos_result_t | gos_file_list (const gos_file_list_parameters_t *params, gos_file_t **list_ptr, uint32_t *count_ptr, void *user) |
List files in file system. See Gecko OS Command API documentation:
ls
.
More...
|
|
void | gos_file_destroy_list ( gos_file_t * gos_file_list ) |
Destroy list of files returned by
gos_file_list()
More...
|
|
gos_result_t | gos_file_create (const gos_file_t *file_info, gos_handle_t *handle_ptr) |
Create file on file system. See Gecko OS Command API documentation:
file_create
.
More...
|
|
gos_result_t | gos_file_open (const char *filename, gos_file_location_t location, bool decrypt, gos_handle_t *handle_ptr) |
Open file stream for reading. See Gecko OS Command API documentation:
file_open
.
More...
|
|
gos_result_t | gos_file_stat (const char *filename, gos_file_location_t location, gos_file_t *file_info, uint8_t *hash) |
Get information about file. See Gecko OS Command API documentation:
file_stat
.
More...
|
|
gos_result_t | gos_file_delete (const char *filename, gos_file_location_t location) |
Delete file from file system. See Gecko OS Command API documentation:
file_delete
.
More...
|
|
gos_result_t | gos_file_write ( gos_handle_t handle, const void *data, uint32_t size) |
Write file data. See Gecko OS Command API documentation:
stream_write
.
More...
|
|
gos_result_t | gos_file_read ( gos_handle_t handle, void *data, uint32_t max_size, uint32_t *bytes_read) |
Read file data. See Gecko OS Command API documentation:
stream_read
.
More...
|
|
gos_result_t | gos_file_close ( gos_handle_t handle) |
Close file stream. See Gecko OS Command API documentation:
stream_close
.
More...
|
|
gos_result_t | gos_file_poll ( gos_handle_t handle, uint32_t *bytes_available) |
Poll file opened for reading to see if there's more data to be read.
More...
|
|
const char * | gos_file_version_str (uint32_t version_int, char *str_buffer) |
Convert file version from integer to string representation.
More...
|
|
gos_result_t | gos_file_version_uint32 (const char *version_str, uint32_t *version_ptr) |
Convert file version from string to integer representation.
More...
|
|
gos_result_t | gos_file_get_descriptor ( gos_handle_t handle, gos_file_descriptor_t *fd_buffer) |
Return a file descriptor about a file currently opened for reading or writing.
More...
|
|
gos_result_t | gos_file_system_get_stats ( gos_file_location_t location, gos_file_system_stats_t *stats) |
Return statics about the file system.
More...
|
|
Detailed Description
This contains all file system related functionality.
Function Documentation
◆ gos_file_close()
gos_result_t gos_file_close | ( | gos_handle_t |
handle
|
) |
Close file stream. See Gecko OS Command API documentation: stream_close .
If the stream was opened for writing (i.e. gos_file_create() was used) and not all of the specified file size was written then all written data will be lost.
- Note
- Stream handles start at 1, max handle value is GOS_MAX_STREAMS
- Parameters
-
[in] handle
File stream handle to close
- Returns
- gos_result_t result of API call
◆ gos_file_create()
gos_result_t gos_file_create | ( | const gos_file_t * |
file_info,
|
gos_handle_t * |
handle_ptr
|
||
) |
Create file on file system. See Gecko OS Command API documentation: file_create .
This will open a file stream handle for writing. The file will be created with the given information in the gos_file_t file_info. Once this API returns, gos_file_write() must be used to write the specified amount of data in the 'size' member of the gos_file_t argument.
Once the specified amount of file data is written the file is created and the file stream will automatically close.
The following fields in gos_file_t are used for creating the file:
- type - The file's type, see gos_file_type_t
- owner - The file's owner, see gos_file_owner_t
- location - The file's location, see gos_file_location_t
- flags - The file's flags, see gos_file_flag_t
- permissions - The file's permissions, see gos_file_permission_t
- size - The size of the file in bytes
- version - The version of the file as a uint32
- checksum - The file checksum, used ONLY if the GOS_FILE_FLAG_CHECKSUM_VALID flag is also set
- name - The file's name
- Note
-
If the
flags
member of gos_file_t is set with GOS_FILE_FLAG_CHECKSUM_VALID , then thechecksum
member of the gos_file_t MUST have a valid CRC32 checksum of the written file data. If the GOS_FILE_FLAG_CHECKSUM_VALID flag is set, then after all file data is written, Gecko OS reads back the written file data and calculates a CRC32 checksum. If the providedchecksum
does not match the calculated checksum then all written data is dropped. In this way, the written file is verified before it appears in the file system. -
If the
flags
member of gos_file_t is set with GOS_FILE_FLAG_ENCRYPTED , then the file will be encrypted with either thesystem.security_key
or the device's internal key as it is written. If theowner
field is GOS_FILE_OWNER_DEVICE then the file is encrypted with the device's internal key. If theowner
field is GOS_FILE_OWNER_USER then the file is encrypted with thesystem.security_key
. If the GOS_FILE_FLAG_PRE_ENCRYPTED flag is also set then the file is not encrypted as it is written.
- Parameters
-
[in] file_info
Information amount the file, return to gos_file_t [out] handle_ptr
File stream handle to write
- Returns
- gos_result_t result of API call
- Examples:
- cloud/dps_demo/main.c , and file/file_encrypt/encrypt.c .
◆ gos_file_delete()
gos_result_t gos_file_delete | ( | const char * |
filename,
|
gos_file_location_t |
location
|
||
) |
Delete file from file system. See Gecko OS Command API documentation: file_delete .
The filename argument must either be the name of the file on the filesystem or the
memory-handle
of the file. For instance, if a file is on the extended flash memory at handle 45, the the filename argument would be 'e-45'.
- Parameters
-
[in] filename
- Filename or handle of file to delete [in] location
- Memory location where file resides, gos_file_location_t , if a file handle is provided then this is ignored
- Returns
- gos_result_t result of API call
- Examples:
- cloud/dps_demo/main.c , and file/file_encrypt/encrypt.c .
◆ gos_file_destroy_list()
void gos_file_destroy_list | ( | gos_file_t * |
gos_file_list
|
) |
Destroy list of files returned by gos_file_list()
- Parameters
-
gos_file_list
List of files to cleanup
- Examples:
- file/file_list/main.c , and utility/json_parser/parse_all_examples.c .
◆ gos_file_get_descriptor()
gos_result_t gos_file_get_descriptor | ( | gos_handle_t |
handle,
|
gos_file_descriptor_t * |
fd_buffer
|
||
) |
Return a file descriptor about a file currently opened for reading or writing.
A file must have been previously opened using gos_file_open() or gos_file_create()
- Note
- Stream handles start at 1, max handle value is GOS_MAX_STREAMS
- Parameters
-
handle
The file handle returned by gos_file_open() or gos_file_create() fd_buffer
Buffer to hold snapshot of file descriptor. gos_file_descriptor_t
- Returns
- gos_result_t result of API call
- Examples:
- utility/json_parser/parse_example2.c , and utility/json_parser/parse_example9.c .
◆ gos_file_list()
gos_result_t gos_file_list | ( | const gos_file_list_parameters_t * |
params,
|
gos_file_t ** |
list_ptr,
|
||
uint32_t * |
count_ptr,
|
||
void * |
user
|
||
) |
List files in file system. See Gecko OS Command API documentation: ls .
This will return a linked list of files in the file system with optional search parameters.
Refer to gos_file_list_parameters_t for possible filtering and paging options.
- Note
- gos_file_list_destroy() MUST be called to cleanup the returned file list.
- Files are listed by their file 'handle' (i.e. the file's first sector) in increasing order
-
This API will return
GOS_SUCCESS
even if no files are returned. In this case
list_ptr
will be NULL andcount_ptr
will be zero.
- Parameters
-
[in] params
[Optional] filtering and paging options. See gos_file_list_parameters_t , leave NULL to return all possible files (excluding 'internal' flash system files) [in] list_ptr
[Optional] Pointer to hold the head of a linked list of files, leave NULL if unused [in] count_ptr
[Optional] Holds number of returned files, leave NULL if unused [in] user
[Optional] Argument to pass to callback specified in gos_file_list_parameters_t , leave NULL if unused
- Returns
- gos_result_t result of API call
- Examples:
- file/file_list/main.c , and utility/json_parser/parse_all_examples.c .
◆ gos_file_open()
gos_result_t gos_file_open | ( | const char * |
filename,
|
gos_file_location_t |
location,
|
||
bool |
decrypt,
|
||
gos_handle_t * |
handle_ptr
|
||
) |
Open file stream for reading. See Gecko OS Command API documentation: file_open .
This will open the specified filename or filename handle for reading. If the file is found, the handle pointer will contain the file stream handle. gos_file_read() should be used to read the file information.
The filename argument must either be the name of the file on the filesystem or the
memory-handle
of the file. For instance, if a file is on the extended flash memory at handle 45, the the filename argument would be 'e-45'.
- Note
-
If the
decrypt
argument is true AND the file has the GOS_FILE_FLAG_ENCRYPTED flag set then the file will be decrypted as it is read.
- Parameters
-
[in] filename
Filename or handle of file to open for reading [in] location
The memory the file resides on, see gos_file_location_t , if a file handle is provided then this is ignored [in] decrypt
if true then decrypt the file as it is read (if applicable), else return encrypted file data [out] handle_ptr
Pointer to contain file stream handle
- Returns
- gos_result_t result of API call
◆ gos_file_poll()
gos_result_t gos_file_poll | ( | gos_handle_t |
handle,
|
uint32_t * |
bytes_available
|
||
) |
Poll file opened for reading to see if there's more data to be read.
The stream must first be opened with gos_file_open()
- Note
- Stream handles start at 1, max handle value is GOS_MAX_STREAMS
- Parameters
-
[in] handle
File stream handle to close [out] bytes_available
Pointer to hold number of bytes remaining to be read
- Returns
- gos_result_t result of API call
◆ gos_file_read()
gos_result_t gos_file_read | ( | gos_handle_t |
handle,
|
void * |
data,
|
||
uint32_t |
max_size,
|
||
uint32_t * |
bytes_read
|
||
) |
Read file data. See Gecko OS Command API documentation: stream_read .
gos_file_open() must be called before using this API.
- Note
- Once all file data has been read the file stream will automatically close.
- Stream handles start at 1, max handle value is GOS_MAX_STREAMS
- Parameters
-
[in] handle
Readable file stream handle [in] data
Buffer to hold read file data [in] max_size
Size of 'data' buffer [out] bytes_read
Amount of data actually read
- Returns
- gos_result_t result of API call
◆ gos_file_stat()
gos_result_t gos_file_stat | ( | const char * |
filename,
|
gos_file_location_t |
location,
|
||
gos_file_t * |
file_info,
|
||
uint8_t * |
hash
|
||
) |
Get information about file. See Gecko OS Command API documentation: file_stat .
This populates the supplied gos_file_t with information about a file.
The filename argument must either be the name of the file on the filesystem or the
memory-handle
of the file. For instance, if a file is on the extended flash memory at handle 45, the the filename argument would be 'e-45'.
- Parameters
-
[in] filename
- Filename or handle of file to open for reading [in] location
- Memory location where file resides, gos_file_location_t , if a file handle is provided then this is ignored [out] file_info
- gos_file_t to be populated with file information [out] hash
- Lower 8 bytes of SHA256(<version string><file data>), leave NULL if not used
- Returns
- gos_result_t result of API call
- Examples:
- cloud/dps_demo/main.c , and file/file_encrypt/decrypt.c .
◆ gos_file_system_get_stats()
gos_result_t gos_file_system_get_stats | ( | gos_file_location_t |
location,
|
gos_file_system_stats_t * |
stats
|
||
) |
Return statics about the file system.
This returns statics about a specific file system memory region:
The statistics account for internal file headers, etc.
- Parameters
-
location
The flash memory region, GOS_FILE_LOCATION_EXTENDED or GOS_FILE_LOCATION_BULK stats
Buffer to hold the file system stats, see gos_file_system_stats_t
- Returns
- gos_result_t result of API call
- Examples:
- file/file_list/main.c .
◆ gos_file_version_str()
const char* gos_file_version_str | ( | uint32_t |
version_int,
|
char * |
str_buffer
|
||
) |
Convert file version from integer to string representation.
- Parameters
-
[in] version_int
File version in integer format [out] str_buffer
Buffer to hold file version string
- Returns
- Version string (same pointer as 'buffer' argument)
◆ gos_file_version_uint32()
gos_result_t gos_file_version_uint32 | ( | const char * |
version_str,
|
uint32_t * |
version_ptr
|
||
) |
Convert file version from string to integer representation.
- Parameters
-
[in] version_str
File version string [out] version_ptr
Pointer to hold file version integer
- Returns
- Result of conversion
◆ gos_file_write()
gos_result_t gos_file_write | ( | gos_handle_t |
handle,
|
const void * |
data,
|
||
uint32_t |
size
|
||
) |
Write file data. See Gecko OS Command API documentation: stream_write .
gos_file_create() must be called before using this API.
- Note
- Stream handles start at 1, max handle value is GOS_MAX_STREAMS
- Parameters
-
[in] handle
Writable file stream handle [in] data
Buffer to file data to write [in] size
Size of 'data' buffer
- Returns
- gos_result_t result of API call
- Examples:
- cloud/dps_demo/main.c , and file/file_encrypt/encrypt.c .