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

◆ CFile()

CFile ( )

default

Construct a new, unopened file.

◆ ~CFile()

virtual ~CFile ( )

inlinevirtual

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

◆ OpenFile()

bool 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 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

◆ IsOpen()

bool IsOpen ( ) const

inline

Check file is opened.

Returns: True on open or false on closed or failure

◆ Close()

void Close ( )

inline

Close an open file.

◆ CURLCreate()

bool 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

◆ CURLAddOption()

bool 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

◆ CURLOpen()

bool 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

◆ Read()

ssize_t 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 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());
  }
}

◆ Write()

ssize_t 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

◆ Flush()

void 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.

◆ Seek()

int64_t 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 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.

◆ GetPosition()

int64_t GetPosition ( ) const

inline

The current offset in an open file.

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

◆ GetLength()

int64_t GetLength ( ) const

inline

Get the file size of an open file.

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

◆ AtEnd()

bool AtEnd ( ) const

inline

Checks the file access is on end position.

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

◆ GetChunkSize()

int GetChunkSize ( ) const

inline

Get the chunk size for an open file.

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

◆ IoControlGetSeekPossible()

bool IoControlGetSeekPossible ( ) const

inline

To check seek possible on current stream by file.

Returns: true if seek possible, false if not

◆ IoControlGetCacheStatus()

bool 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

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

◆ IoControlSetCacheRate()

bool 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 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

◆ GetPropertyValue()

const std::string 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 > 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

Detailed Description

Function Documentation

◆ CFile()

◆ ~CFile()

◆ OpenFile()

◆ OpenFileForWrite()

◆ IsOpen()

◆ Close()

◆ CURLCreate()

◆ CURLAddOption()

◆ CURLOpen()

◆ Read()

◆ ReadLine()

◆ Write()

◆ Flush()

◆ Seek()

◆ Truncate()

◆ GetPosition()

◆ GetLength()

◆ AtEnd()

◆ GetChunkSize()

◆ IoControlGetSeekPossible()

◆ IoControlGetCacheStatus()

◆ IoControlSetCacheRate()

◆ IoControlSetRetry()

◆ GetPropertyValue()

◆ GetPropertyValues()

◆ GetFileDownloadSpeed()