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]handleFile stream handle to close
Returns
gos_result_t result of API call
Examples:
cloud/dps_demo/main.c, file/file_encrypt/encrypt.c, file/log_file/main.c, file/log_file_encrypted/main.c, hurricane/weatherstation/main.c, utility/json_parser/parse_all_examples.c, utility/json_parser/parse_example1.c, and utility/json_parser/parse_example3.c.

◆ 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:

Note
If the flags member of gos_file_t is set with GOS_FILE_FLAG_CHECKSUM_VALID , then the checksum 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 provided checksum 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 the system.security_key or the device's internal key as it is written. If the owner field is GOS_FILE_OWNER_DEVICE then the file is encrypted with the device's internal key. If the owner field is GOS_FILE_OWNER_USER then the file is encrypted with the system.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_infoInformation amount the file, return to gos_file_t
[out]handle_ptrFile 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_listList 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
handleThe file handle returned by gos_file_open() or gos_file_create()
fd_bufferBuffer 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 and count_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]filenameFilename or handle of file to open for reading
[in]locationThe memory the file resides on, see gos_file_location_t, if a file handle is provided then this is ignored
[in]decryptif true then decrypt the file as it is read (if applicable), else return encrypted file data
[out]handle_ptrPointer to contain file stream handle
Returns
gos_result_t result of API call
Examples:
file/file_encrypt/decrypt.c, hurricane/weatherstation/main.c, utility/json_parser/parse_all_examples.c, utility/json_parser/parse_example1.c, utility/json_parser/parse_example2.c, utility/json_parser/parse_example3.c, and utility/json_parser/parse_example9.c.

◆ 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]handleFile stream handle to close
[out]bytes_availablePointer to hold number of bytes remaining to be read
Returns
gos_result_t result of API call
Examples:
utility/json_parser/parse_all_examples.c, utility/json_parser/parse_example1.c, and utility/json_parser/parse_example3.c.

◆ 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]handleReadable file stream handle
[in]dataBuffer to hold read file data
[in]max_sizeSize of 'data' buffer
[out]bytes_readAmount of data actually read
Returns
gos_result_t result of API call
Examples:
file/file_encrypt/decrypt.c, hurricane/weatherstation/main.c, utility/json_parser/parse_all_examples.c, utility/json_parser/parse_example1.c, utility/json_parser/parse_example2.c, utility/json_parser/parse_example3.c, and utility/json_parser/parse_example9.c.

◆ 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
locationThe flash memory region, GOS_FILE_LOCATION_EXTENDED or GOS_FILE_LOCATION_BULK
statsBuffer 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_intFile version in integer format
[out]str_bufferBuffer 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_strFile version string
[out]version_ptrPointer 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]handleWritable file stream handle
[in]dataBuffer to file data to write
[in]sizeSize of 'data' buffer
Returns
gos_result_t result of API call
Examples:
cloud/dps_demo/main.c, and file/file_encrypt/encrypt.c.