Kodi Development  19.0
for Binary and Script based Add-Ons
3. General functions
C++ » Interface - kodi::vfs

Detailed Description

Other globally available functions
Used to perform typical operations with it.

Function Documentation

◆ GetFileMD5()

std::string ATTRIBUTE_HIDDEN kodi::vfs::GetFileMD5 ( const std::string &  path)
inline

Retrieve MD5sum of a file.

Parameters
[in]pathPath to the file to MD5sum
Returns
MD5 sum of the file

Example:

#include <kodi/Filesystem.h>
#include <kodi/gui/DialogFileBrowser.h>
...
std::string md5;
std::string filename;
if (kodi::gui::DialogFileBrowser::ShowAndGetFile("local", "*.avi|*.mpg|*.mp4",
"Test File selection to get MD5",
filename))
{
md5 = kodi::vfs::GetFileMD5(filename);
fprintf(stderr, "MD5 of file '%s' is %s\n", md5.c_str(), filename.c_str());
}

◆ GetCacheThumbName()

std::string ATTRIBUTE_HIDDEN kodi::vfs::GetCacheThumbName ( const std::string &  filename)
inline

Returns a thumb cache filename.

Parameters
[in]filenamePath to file
Returns
Cache filename

Example:

#include <kodi/Filesystem.h>
#include <kodi/gui/DialogFileBrowser.h>
...
std::string thumb;
std::string filename;
if (kodi::gui::DialogFileBrowser::ShowAndGetFile("local", "*.avi|*.mpg|*.mp4",
"Test File selection to get Thumnail",
filename))
{
thumb = kodi::vfs::GetCacheThumbName(filename);
fprintf(stderr, "Thumb name of file '%s' is %s\n", thumb.c_str(), filename.c_str());
}

◆ MakeLegalFileName()

std::string ATTRIBUTE_HIDDEN kodi::vfs::MakeLegalFileName ( const std::string &  filename)
inline

Make filename valid.

Function to replace not valid characters with '_'. It can be also compared with original before in a own loop until it is equal (no invalid characters).

Parameters
[in]filenameFilename to check and fix
Returns
The legal filename

Example:

#include <kodi/Filesystem.h>
...
std::string fileName = "///\\jk???lj????.mpg";
std::string legalName = kodi::vfs::MakeLegalFileName(fileName);
fprintf(stderr, "Legal name of '%s' is '%s'\n", fileName.c_str(), legalName.c_str());
/* Returns as legal: 'jk___lj____.mpg' *&zwj;/

◆ MakeLegalPath()

std::string ATTRIBUTE_HIDDEN kodi::vfs::MakeLegalPath ( const std::string &  path)
inline

Make directory name valid.

Function to replace not valid characters with '_'. It can be also compared with original before in a own loop until it is equal (no invalid characters).

Parameters
[in]pathDirectory name to check and fix
Returns
The legal directory name

Example:

#include <kodi/Filesystem.h>
...
std::string path = "///\\jk???lj????\\hgjkg";
std::string legalPath = kodi::vfs::MakeLegalPath(path);
fprintf(stderr, "Legal name of '%s' is '%s'\n", path.c_str(), legalPath.c_str());
/* Returns as legal: '/jk___lj____/hgjkg' *&zwj;/

◆ TranslateSpecialProtocol()

std::string ATTRIBUTE_HIDDEN kodi::vfs::TranslateSpecialProtocol ( const std::string &  source)
inline

Returns the translated path.

Parameters
[in]sourceString or unicode - Path to format
Returns
A human-readable string suitable for logging
Note
Only useful if you are coding for both Linux and Windows. e.g. Converts 'special://masterprofile/script_data' -> '/home/user/.kodi/UserData/script_data' on Linux.

Example:

#include <kodi/Filesystem.h>
...
std::string path = kodi::vfs::TranslateSpecialProtocol("special://masterprofile/script_data");
fprintf(stderr, "Translated path is: %s\n", path.c_str());
...

or

#include <kodi/Filesystem.h>
...
fprintf(stderr, "Directory 'special://temp' is '%s'\n", kodi::vfs::TranslateSpecialProtocol("special://temp").c_str());
...

◆ GetDiskSpace()

bool ATTRIBUTE_HIDDEN kodi::vfs::GetDiskSpace ( const std::string &  path,
uint64_t &  capacity,
uint64_t &  free,
uint64_t &  available 
)
inline

Retrieves information about the amount of space that is available on a disk volume.

Path can be also with Kodi's special protocol.

Parameters
[in]pathPath for where to check
[out]capacityThe total number of bytes in the file system
[out]freeThe total number of free bytes in the file system
[out]availableThe total number of free bytes available to a non-privileged process
Returns
true if successfully done and set
Warning
This only works with paths belonging to OS. If "special://" is used, it must point to a place on your own OS.

Example:

#include <climits> // for ULLONG_MAX
#include <kodi/Filesystem.h>
...
std::string path = "special://temp";
uint64_t capacity = ULLONG_MAX;
uint64_t free = ULLONG_MAX;
uint64_t available = ULLONG_MAX;
kodi::vfs::GetDiskSpace(path, capacity, free, available);
fprintf(stderr, "Path '%s' sizes:\n", path.c_str());
fprintf(stderr, " - capacity: %lu MByte\n", capacity / 1024 / 1024);
fprintf(stderr, " - free: %lu MByte\n", free / 1024 / 1024);
fprintf(stderr, " - available: %lu MByte\n", available / 1024 / 1024);

◆ GetFileName()

std::string ATTRIBUTE_HIDDEN kodi::vfs::GetFileName ( const std::string &  path)
inline

Return the file name from given complate path string.

Parameters
[in]pathThe complete path include file and directory
Returns
Filename from path

Example:

#include <kodi/Filesystem.h>
...
std::string fileName = kodi::vfs::GetFileName("special://temp/kodi.log");
fprintf(stderr, "File name is '%s'\n", fileName.c_str());

◆ GetDirectoryName()

std::string ATTRIBUTE_HIDDEN kodi::vfs::GetDirectoryName ( const std::string &  path)
inline

Return the directory name from given complate path string.

Parameters
[in]pathThe complete path include file and directory
Returns
Directory name from path

Example:

#include <kodi/Filesystem.h>
...
std::string dirName = kodi::vfs::GetDirectoryName("special://temp/kodi.log");
fprintf(stderr, "Directory name is '%s'\n", dirName.c_str());

◆ RemoveSlashAtEnd()

void ATTRIBUTE_HIDDEN kodi::vfs::RemoveSlashAtEnd ( std::string &  path)
inline

Remove the slash on given path name.

Parameters
[in,out]pathThe complete path

Example:

#include <kodi/Filesystem.h>
...
std::string dirName = "special://temp/";
kodi::vfs::RemoveSlashAtEnd(dirName);
fprintf(stderr, "Directory name is '%s'\n", dirName.c_str());

◆ GetChunkSize()

unsigned int ATTRIBUTE_HIDDEN kodi::vfs::GetChunkSize ( unsigned int  chunk,
unsigned int  minimum 
)
inline

Return a size aligned to the chunk size at least as large as the chunk size.

Parameters
[in]chunkThe chunk size
[in]minimumThe minimum size (or maybe the minimum number of chunks?)
Returns
The aligned size

◆ IsInternetStream()

bool ATTRIBUTE_HIDDEN kodi::vfs::IsInternetStream ( const std::string &  path,
bool  strictCheck = false 
)
inline

Checks the given path contains a known internet protocol.

About following protocols are the path checked:

Protocol Return true condition Protocol Return true condition
dav strictCheck = true rtmps always
davs strictCheck = true rtmpt always
ftp strictCheck = true rtmpte always
ftps strictCheck = true rtp always
http always rtsp always
https always sdp always
mms always sftp strictCheck = true
mmsh always stack always
mmst always tcp always
rtmp always udp always
rtmpe always
Parameters
[in]pathTo checked path/URL
[in]strictCheck[opt] If True the set of protocols used will be extended to include ftp, ftps, dav, davs and sftp.
Returns
True if path is to a internet stream, false otherwise

Example:

#include <kodi/Filesystem.h>
...
// Check should return false
fprintf(stderr, "File name 1 is internet stream '%s' (should no)\n",
kodi::vfs::IsInternetStream("D:/my-file.mkv") ? "yes" : "no");
// Check should return true
fprintf(stderr, "File name 2 is internet stream '%s' (should yes)\n",
kodi::vfs::IsInternetStream("http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4") ? "yes" : "no");
// Check should return false
fprintf(stderr, "File name 1 is internet stream '%s' (should no)\n",
kodi::vfs::IsInternetStream("ftp://do-somewhere.com/the-file.mkv") ? "yes" : "no", false);
// Check should return true
fprintf(stderr, "File name 1 is internet stream '%s' (should yes)\n",
kodi::vfs::IsInternetStream("ftp://do-somewhere.com/the-file.mkv") ? "yes" : "no", true);

◆ IsOnLAN()

bool ATTRIBUTE_HIDDEN kodi::vfs::IsOnLAN ( const std::string &  path)
inline

Checks whether the specified path refers to a local network.

In difference to IsHostOnLAN() include this more deeper checks where also handle Kodi's special protocol and stacks.

Parameters
[in]pathTo checked path
Returns
True if path is on LAN, false otherwise
Note
Check includes IsHostOnLAN() too.

Example:

#include <kodi/Filesystem.h>
...
// Check should return true
bool lan = kodi::vfs::IsOnLAN("smb://path/to/file");

◆ IsRemote()

bool ATTRIBUTE_HIDDEN kodi::vfs::IsRemote ( const std::string &  path)
inline

Checks specified path for external network.

Parameters
[in]pathTo checked path
Returns
True if path is remote, false otherwise
Note
This does not apply to the local network.

Example:

#include <kodi/Filesystem.h>
...
// Check should return true
bool remote = kodi::vfs::IsRemote("http://path/to/file");

◆ IsLocal()

bool ATTRIBUTE_HIDDEN kodi::vfs::IsLocal ( const std::string &  path)
inline

Checks whether the given path refers to the own system.

Parameters
[in]pathTo checked path
Returns
True if path is local, false otherwise

◆ IsURL()

bool ATTRIBUTE_HIDDEN kodi::vfs::IsURL ( const std::string &  path)
inline

Checks specified path is a regular URL, e.g. "someprotocol://path/to/file".

Returns
True if file item is URL, false otherwise

Example:

#include <kodi/Filesystem.h>
...
bool isURL;
// Check should return true
isURL = kodi::vfs::IsURL("someprotocol://path/to/file");
// Check should return false
isURL = kodi::vfs::IsURL("/path/to/file");

◆ GetHttpHeader()

bool ATTRIBUTE_HIDDEN kodi::vfs::GetHttpHeader ( const std::string &  url,
HttpHeader &  header 
)
inline

To get HTTP header information.

Parameters
[in]urlURL source of the data
[out]headerThe class HttpHeader
Returns
true if successfully done, otherwise false

The following table contains values that can be get with class HttpHeader :

Description Type Get call
Get the value associated with this parameter of these HTTP headers std::string GetValue
Get the values as list associated with this parameter of these HTTP headers std::vector<std::string> GetValues
Get the full header string associated with these HTTP headers std::string GetHeader
Get the mime type associated with these HTTP headers std::string GetMimeType
Get the charset associated with these HTTP headers std::string GetCharset
The protocol line associated with these HTTP headers std::string GetProtoLine

Example:

#include <kodi/Filesystem.h>
...
kodi::vfs::HttpHeader header;
bool ret = kodi::vfs::GetHttpHeader(url, header);
...

◆ GetMimeType()

bool ATTRIBUTE_HIDDEN kodi::vfs::GetMimeType ( const std::string &  url,
std::string &  mimeType,
const std::string &  useragent = "" 
)
inline

Get file mime type.

Parameters
[in]urlURL source of the data
[out]mimeTypethe mime type of the URL
[in]useragentto be used when retrieving the MimeType [opt]
Returns
true if successfully done, otherwise false

Example:

#include <kodi/Filesystem.h>
...
std::string mimeType;.
if (kodi::vfs::GetMimeType(url, mimeType))
fprintf(stderr, "The mime type is '%s'\n", mimeType.c_str());
...

◆ GetContentType()

bool ATTRIBUTE_HIDDEN kodi::vfs::GetContentType ( const std::string &  url,
std::string &  content,
const std::string &  useragent = "" 
)
inline

Get file content-type.

Parameters
[in]urlURL source of the data
[out]contentThe returned type
[in]useragentto be used when retrieving the MimeType [opt]
Returns
true if successfully done, otherwise false

Example:

#include <kodi/Filesystem.h>
...
std::string content;.
if (kodi::vfs::GetContentType(url, content))
fprintf(stderr, "The content type is '%s'\n", content.c_str());
...

◆ GetCookies()

bool ATTRIBUTE_HIDDEN kodi::vfs::GetCookies ( const std::string &  url,
std::string &  cookies 
)
inline

Get cookies stored by CURL in RFC 2109 format.

Parameters
[in]urlURL source of the data
[out]cookiesThe text list of available cookies
Returns
true if successfully done, otherwise false

Example:

#include <kodi/Filesystem.h>
...
std::string url = "";
std::string cookies;
bool ret = kodi::vfs::GetCookies(url, cookies);
fprintf(stderr, "Cookies from URL '%s' are '%s' (return was %s)\n",
url.c_str(), cookies.c_str(), ret ? "true" : "false");
...
kodi::vfs::GetCookies
bool ATTRIBUTE_HIDDEN GetCookies(const std::string &url, std::string &cookies)
Get cookies stored by CURL in RFC 2109 format.
Definition: Filesystem.h:1763
kodi::vfs::RemoveSlashAtEnd
void ATTRIBUTE_HIDDEN RemoveSlashAtEnd(std::string &path)
Remove the slash on given path name.
Definition: Filesystem.h:1431
kodi::vfs::GetHttpHeader
bool ATTRIBUTE_HIDDEN GetHttpHeader(const std::string &url, HttpHeader &header)
To get HTTP header information.
Definition: Filesystem.h:1649
kodi::vfs::GetMimeType
bool ATTRIBUTE_HIDDEN GetMimeType(const std::string &url, std::string &mimeType, const std::string &useragent="")
Get file mime type.
Definition: Filesystem.h:1680
kodi::vfs::GetFileName
std::string ATTRIBUTE_HIDDEN GetFileName(const std::string &path)
Return the file name from given complate path string.
Definition: Filesystem.h:1370
kodi::vfs::GetContentType
bool ATTRIBUTE_HIDDEN GetContentType(const std::string &url, std::string &content, const std::string &useragent="")
Get file content-type.
Definition: Filesystem.h:1721
kodi::vfs::GetDiskSpace
bool ATTRIBUTE_HIDDEN GetDiskSpace(const std::string &path, uint64_t &capacity, uint64_t &free, uint64_t &available)
Retrieves information about the amount of space that is available on a disk volume.
Definition: Filesystem.h:1340
kodi::vfs::TranslateSpecialProtocol
std::string ATTRIBUTE_HIDDEN TranslateSpecialProtocol(const std::string &source)
Returns the translated path.
Definition: Filesystem.h:1286
kodi::vfs::GetCacheThumbName
std::string ATTRIBUTE_HIDDEN GetCacheThumbName(const std::string &filename)
Returns a thumb cache filename.
Definition: Filesystem.h:1152
kodi::gui::dialogs::FileBrowser::ShowAndGetFile
bool ATTRIBUTE_HIDDEN ShowAndGetFile(const std::string &shares, const std::string &mask, const std::string &heading, std::string &path, bool useThumbs=false, bool useFileDirectories=false)
File selection dialog.
Definition: FileBrowser.h:105
kodi::vfs::IsRemote
bool ATTRIBUTE_HIDDEN IsRemote(const std::string &path)
Checks specified path for external network.
Definition: Filesystem.h:1569
kodi::vfs::GetDirectoryName
std::string ATTRIBUTE_HIDDEN GetDirectoryName(const std::string &path)
Return the directory name from given complate path string.
Definition: Filesystem.h:1396
kodi::vfs::IsURL
bool ATTRIBUTE_HIDDEN IsURL(const std::string &path)
Checks specified path is a regular URL, e.g. "someprotocol://path/to/file".
Definition: Filesystem.h:1616
kodi::vfs::GetFileMD5
std::string ATTRIBUTE_HIDDEN GetFileMD5(const std::string &path)
Retrieve MD5sum of a file.
Definition: Filesystem.h:1109
kodi::vfs::IsInternetStream
bool ATTRIBUTE_HIDDEN IsInternetStream(const std::string &path, bool strictCheck=false)
Checks the given path contains a known internet protocol.
Definition: Filesystem.h:1508
kodi::vfs::MakeLegalFileName
std::string ATTRIBUTE_HIDDEN MakeLegalFileName(const std::string &filename)
Make filename valid.
Definition: Filesystem.h:1195
kodi::vfs::IsOnLAN
bool ATTRIBUTE_HIDDEN IsOnLAN(const std::string &path)
Checks whether the specified path refers to a local network.
Definition: Filesystem.h:1540
kodi::vfs::MakeLegalPath
std::string ATTRIBUTE_HIDDEN MakeLegalPath(const std::string &path)
Make directory name valid.
Definition: Filesystem.h:1238