Creatable class for virtual file server control
To perform file read/write with Kodi's filesystem parts. More...

Classes
class	kodi::vfs::CFile

Functions
	kodi::vfs::CFile::CFile ()=default
	Construct a new, unopened file.

virtual	kodi::vfs::CFile::~CFile ()
	`Close()` is called from the destructor, so explicitly closing the file isn't required.

bool	kodi::vfs::CFile::OpenFile (const std::string &filename, unsigned int flags=0)
	Open the file with filename via Kodi's CFile. Needs to be closed by calling Close() when done.

bool	kodi::vfs::CFile::OpenFileForWrite (const std::string &filename, bool overwrite=false)
	Open the file with filename via Kodi's CFile in write mode. Needs to be closed by calling Close() when done.

bool	kodi::vfs::CFile::IsOpen () const
	Check file is opened.

void	kodi::vfs::CFile::Close ()
	Close an open file.

bool	kodi::vfs::CFile::CURLCreate (const std::string &url)
	Create a Curl representation.

bool	kodi::vfs::CFile::CURLAddOption (CURLOptiontype type, const std::string &name, const std::string &value)
	Add options to the curl file created with CURLCreate.

bool	kodi::vfs::CFile::CURLOpen (unsigned int flags=0)
	Open the curl file created with CURLCreate.

ssize_t	kodi::vfs::CFile::Read (void *ptr, size_t size)
	Read from an open file.

bool	kodi::vfs::CFile::ReadLine (std::string &line)
	Read a string from an open file.

ssize_t	kodi::vfs::CFile::Write (const void *ptr, size_t size)
	Write to a file opened in write mode.

void	kodi::vfs::CFile::Flush ()
	Flush buffered data.

int64_t	kodi::vfs::CFile::Seek (int64_t position, int whence=SEEK_SET)
	Set the file's current position.

int	kodi::vfs::CFile::Truncate (int64_t size)
	Truncate a file to the requested size.

int64_t	kodi::vfs::CFile::GetPosition () const
	The current offset in an open file.

int64_t	kodi::vfs::CFile::GetLength () const
	Get the file size of an open file.

bool	kodi::vfs::CFile::AtEnd () const
	Checks the file access is on end position.

int	kodi::vfs::CFile::GetChunkSize () const
	Get the chunk size for an open file.

bool	kodi::vfs::CFile::IoControlGetSeekPossible () const
	To check seek possible on current stream by file.

bool	kodi::vfs::CFile::IoControlGetCacheStatus (CacheStatus &status) const
	To check a running stream on file for state of his cache.

bool	kodi::vfs::CFile::IoControlSetCacheRate (uint32_t rate)
	Unsigned int with speed limit for caching in bytes per second.

bool	kodi::vfs::CFile::IoControlSetRetry (bool retry)
	Enable/disable retry within the protocol handler (if supported).

const std::string	kodi::vfs::CFile::GetPropertyValue (FilePropertyTypes type, const std::string &name) const
	Retrieve a file property.

const std::vector< std::string >	kodi::vfs::CFile::GetPropertyValues (FilePropertyTypes type, const std::string &name) const
	Retrieve file property values.

double	kodi::vfs::CFile::GetFileDownloadSpeed () const
	Get the current download speed of file if loaded from web.

Detailed Description

Creatable class for virtual file server control
To perform file read/write with Kodi's filesystem parts.

CFile is the class used for handling Files in Kodi. This class can be used for creating, reading, writing and modifying files. It directly provides unbuffered, binary disk input/output services

It has the header #include <kodi/Filesystem.h> be included to enjoy it.

Example:

#include <kodi/Filesystem.h>
 
...
 
/* Create the needed file handle class *&zwj;/
kodi::vfs::CFile myFile();
 
/* In this example we use the user path for the add-on *&zwj;/
std::string file = kodi::GetUserPath() + "/myFile.txt";
 
/* Now create and open the file or overwrite if present *&zwj;/
myFile.OpenFileForWrite(file, true);
 
const char* str = "I love Kodi!";
 
/* write string *&zwj;/
myFile.Write(str, sizeof(str));
 
/* On this way the Close() is not needed to call, becomes done from destructor *&zwj;/

Function Documentation

◆ AtEnd()

bool kodi::vfs::CFile::AtEnd ( ) const

inline

Checks the file access is on end position.

Returns: If you've reached the end of the file, AtEnd() returns true.

◆ CFile()

kodi::vfs::CFile::CFile ( )

default

Construct a new, unopened file.

◆ Close()

void kodi::vfs::CFile::Close ( )

inline

Close an open file.

◆ CURLAddOption()

bool kodi::vfs::CFile::CURLAddOption	(	CURLOptiontype	type,
		const std::string &	name,
		const std::string &	value )

inline

Add options to the curl file created with CURLCreate.

Parameters

[in]	type	Option type to set, see CURLOptiontype
[in]	name	Name of the option
[in]	value	Value of the option

Returns: True on success or false on failure

◆ CURLCreate()

bool kodi::vfs::CFile::CURLCreate ( const std::string & url )

inline

Create a Curl representation.

Parameters

[in] url The URL of the Type.

Returns: True on success or false on failure

◆ CURLOpen()

bool kodi::vfs::CFile::CURLOpen ( unsigned int flags = 0 )

inline

Open the curl file created with CURLCreate.

Parameters

[in] flags [opt] The flags to pass, see OpenFileFlags

Returns: True on success or false on failure

◆ Flush()

void kodi::vfs::CFile::Flush ( )

inline

Flush buffered data.

If the given stream was open for writing (or if it was open for updating and the last i/o operation was an output operation) any unwritten data in its output buffer is written to the file.

The stream remains open after this call.

When a file is closed, either because of a call to close or because the class is destructed, all the buffers associated with it are automatically flushed.

◆ GetChunkSize()

int kodi::vfs::CFile::GetChunkSize ( ) const

inline

Get the chunk size for an open file.

Returns: The requested size. On error, the value -1 is returned.

◆ GetFileDownloadSpeed()

double kodi::vfs::CFile::GetFileDownloadSpeed ( ) const

inline

Get the current download speed of file if loaded from web.

Returns: The current download speed.

◆ GetLength()

int64_t kodi::vfs::CFile::GetLength ( ) const

inline

Get the file size of an open file.

Returns: The requested size. On error, the value -1 is returned.

◆ GetPosition()

int64_t kodi::vfs::CFile::GetPosition ( ) const

inline

The current offset in an open file.

Returns: The requested offset. On error, the value -1 is returned.

◆ GetPropertyValue()

const std::string kodi::vfs::CFile::GetPropertyValue	(	FilePropertyTypes	type,
		const std::string &	name ) const

inline

Retrieve a file property.

Parameters

[in]	type	The type of the file property to retrieve the value for
[in]	name	The name of a named property value (e.g. Header)

Returns: value of requested property, empty on failure / non-existance

◆ GetPropertyValues()

const std::vector< std::string > kodi::vfs::CFile::GetPropertyValues	(	FilePropertyTypes	type,
		const std::string &	name ) const

inline

Retrieve file property values.

Parameters

[in]	type	The type of the file property values to retrieve the value for
[in]	name	The name of the named property (e.g. Header)

Returns: values of requested property, empty vector on failure / non-existance

◆ IoControlGetCacheStatus()

bool kodi::vfs::CFile::IoControlGetCacheStatus ( CacheStatus & status ) const

inline

To check a running stream on file for state of his cache.

Parameters

[in] status Information about current cache status

Returns: true if successfully done, false otherwise

@ingroup cpp_kodi_vfs_Defs_CacheStatus

The following table contains values that can be set with class CacheStatus :

Name	Type	Set call	Get call
Number of bytes cached	`uint64_t`	SetForward	GetForward
Maximum number of bytes per second	`uint32_t`	SetMaxRate	GetMaxRate
Average read rate from source file	`uint32_t`	SetCurrentRate	GetCurrentRate
Cache low speed rate detected	`uint32_t`	SetLowRate	GetLowRate

◆ IoControlGetSeekPossible()

bool kodi::vfs::CFile::IoControlGetSeekPossible ( ) const

inline

To check seek possible on current stream by file.

Returns: true if seek possible, false if not

◆ IoControlSetCacheRate()

bool kodi::vfs::CFile::IoControlSetCacheRate ( uint32_t rate )

inline

Unsigned int with speed limit for caching in bytes per second.

Parameters

[in] rate Cache rate size to use

Returns: true if successfully done, false otherwise

◆ IoControlSetRetry()

bool kodi::vfs::CFile::IoControlSetRetry ( bool retry )

inline

Enable/disable retry within the protocol handler (if supported).

Parameters

[in] retry To set the retry, true for use, false for not

Returns: true if successfully done, false otherwise

◆ IsOpen()

bool kodi::vfs::CFile::IsOpen ( ) const

inline

Check file is opened.

Returns: True on open or false on closed or failure

◆ OpenFile()

bool kodi::vfs::CFile::OpenFile	(	const std::string &	filename,
		unsigned int	flags = 0 )

inline

Open the file with filename via Kodi's CFile. Needs to be closed by calling Close() when done.

Parameters

[in]	filename	The filename to open.
[in]	flags	[opt] The flags to pass, see OpenFileFlags

Returns: True on success or false on failure

◆ OpenFileForWrite()

bool kodi::vfs::CFile::OpenFileForWrite	(	const std::string &	filename,
		bool	overwrite = false )

inline

Open the file with filename via Kodi's CFile in write mode. Needs to be closed by calling Close() when done.

Note: Related folders becomes created if not present.

Parameters

[in]	filename	The filename to open.
[in]	overwrite	True to overwrite, false otherwise.

Returns: True on success or false on failure

◆ Read()

ssize_t kodi::vfs::CFile::Read	(	void *	ptr,
		size_t	size )

inline

Read from an open file.

Parameters

[in]	ptr	The buffer to store the data in.
[in]	size	The size of the buffer.

Returns: number of successfully read bytes if any bytes were read and stored in buffer, zero if no bytes are available to read (end of file was reached) or undetectable error occur, -1 in case of any explicit error

◆ ReadLine()

bool kodi::vfs::CFile::ReadLine ( std::string & line )

inline

Read a string from an open file.

Parameters

[out] line The buffer to store the data in.

Returns: True when a line was read, false otherwise.

Example:

#include <kodi/Filesystem.h>
 
...
 
/* Create the needed file handle class *&zwj;/
kodi::vfs::CFile myFile;
 
/* Open the wanted file *&zwj;/
if (myFile.OpenFile(kodi::addon::GetUserPath("/myFile.txt")))
{
  /* Read all lines inside file *&zwj;/
  while (1)
  {
    std::string line;
    if (!myFile.ReadLine(line))
      break;
    fprintf(stderr, "%s\n", line.c_str());
  }
}

◆ Seek()

int64_t kodi::vfs::CFile::Seek	(	int64_t	position,
		int	whence = SEEK_SET )

inline

Set the file's current position.

The whence argument is optional and defaults to SEEK_SET (0)

Parameters

[in] position the position that you want to seek to

[in]

whence

[optional] offset relative to You can set the value of whence to one of three things:

Value	int	Description
SEEK_SET	0	position is relative to the beginning of the file. This is probably what you had in mind anyway, and is the most commonly used value for whence.
SEEK_CUR	1	position is relative to the current file pointer position. So, in effect, you can say, "Move to my current position plus 30 bytes," or, "move to my current position minus 20 bytes."
SEEK_END	2	position is relative to the end of the file. Just like SEEK_SET except from the other end of the file. Be sure to use negative values for offset if you want to back up from the end of the file, instead of going past the end into oblivion.

Returns: Returns the resulting offset location as measured in bytes from the beginning of the file. On error, the value -1 is returned.

◆ Truncate()

int kodi::vfs::CFile::Truncate ( int64_t size )

inline

Truncate a file to the requested size.

Parameters

[in] size The new max size.

Returns: New size? On error, the value -1 is returned.

◆ Write()

ssize_t kodi::vfs::CFile::Write	(	const void *	ptr,
		size_t	size )

inline

Write to a file opened in write mode.

Parameters

[in]	ptr	Pointer to the data to write, converted to a *`const void`**.
[in]	size	Size of the data to write.

Returns: number of successfully written bytes if any bytes were written, zero if no bytes were written and no detectable error occur,-1 in case of any explicit error

◆ ~CFile()

virtual kodi::vfs::CFile::~CFile ( )

inlinevirtual

Close() is called from the destructor, so explicitly closing the file isn't required.

Classes

Functions

Detailed Description

Function Documentation

◆ AtEnd()

◆ CFile()

◆ Close()

◆ CURLAddOption()

◆ CURLCreate()

◆ CURLOpen()

◆ Flush()

◆ GetChunkSize()

◆ GetFileDownloadSpeed()

◆ GetLength()

◆ GetPosition()

◆ GetPropertyValue()

◆ GetPropertyValues()

◆ IoControlGetCacheStatus()

@ingroup cpp_kodi_vfs_Defs_CacheStatus

◆ IoControlGetSeekPossible()

◆ IoControlSetCacheRate()

◆ IoControlSetRetry()

◆ IsOpen()

◆ OpenFile()

◆ OpenFileForWrite()

◆ Read()

◆ ReadLine()

◆ Seek()

◆ Truncate()

◆ Write()

◆ ~CFile()