Kodi Documentation 22.0
Kodi is an open source media player and entertainment hub.
Loading...
Searching...
No Matches
4. class CFile

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:

...
/* 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]typeOption type to set, see CURLOptiontype
[in]nameName of the option
[in]valueValue 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]urlThe 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]typeThe type of the file property to retrieve the value for
[in]nameThe 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]typeThe type of the file property values to retrieve the value for
[in]nameThe 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]statusInformation 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]rateCache 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]retryTo 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]filenameThe 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]filenameThe filename to open.
[in]overwriteTrue 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]ptrThe buffer to store the data in.
[in]sizeThe 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]lineThe buffer to store the data in.
Returns
True when a line was read, false otherwise.

Example:

...
/* 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]positionthe 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]sizeThe 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]ptrPointer to the data to write, converted to a const void*.
[in]sizeSize 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.