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

Examples:: file/file_encrypt/encrypt.c , file/log_file/main.c , file/log_file_encrypted/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:

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 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_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:: 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:: 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 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]	`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

Examples:: file/file_encrypt/decrypt.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]	`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

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]	`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

Examples:: file/file_encrypt/decrypt.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:: 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:: file/file_encrypt/encrypt.c .

File System

Modules

Functions

Detailed Description

Function Documentation

◆ gos_file_close()

◆ gos_file_create()

◆ gos_file_delete()

◆ gos_file_destroy_list()

◆ gos_file_get_descriptor()

◆ gos_file_list()

◆ gos_file_open()

◆ gos_file_poll()

◆ gos_file_read()

◆ gos_file_stat()

◆ gos_file_system_get_stats()

◆ gos_file_version_str()

◆ gos_file_version_uint32()

◆ gos_file_write()