3. General functions

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

Functions
std::string ATTR_DLL_LOCAL	kodi::vfs::GetFileMD5 (const std::string &path)
	Retrieve MD5sum of a file.
std::string ATTR_DLL_LOCAL	kodi::vfs::GetCacheThumbName (const std::string &filename)
	Returns a thumb cache filename.
std::string ATTR_DLL_LOCAL	kodi::vfs::MakeLegalFileName (const std::string &filename)
	Make filename valid.
std::string ATTR_DLL_LOCAL	kodi::vfs::MakeLegalPath (const std::string &path)
	Make directory name valid.
std::string ATTR_DLL_LOCAL	kodi::vfs::TranslateSpecialProtocol (const std::string &source)
	Returns the translated path.
bool ATTR_DLL_LOCAL	kodi::vfs::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.
std::string ATTR_DLL_LOCAL	kodi::vfs::GetFileName (const std::string &path)
	Return the file name from given complete path string.
std::string ATTR_DLL_LOCAL	kodi::vfs::GetDirectoryName (const std::string &path)
	Return the directory name from given complete path string.
void ATTR_DLL_LOCAL	kodi::vfs::RemoveSlashAtEnd (std::string &path)
	Remove the slash on given path name.
unsigned int ATTR_DLL_LOCAL	kodi::vfs::GetChunkSize (unsigned int chunk, unsigned int minimum)
	Return a size aligned to the chunk size at least as large as the chunk size.
bool ATTR_DLL_LOCAL	kodi::vfs::IsInternetStream (const std::string &path, bool strictCheck=false)
	Checks the given path contains a known internet protocol.
bool ATTR_DLL_LOCAL	kodi::vfs::IsOnLAN (const std::string &path)
	Checks whether the specified path refers to a local network.
bool ATTR_DLL_LOCAL	kodi::vfs::IsRemote (const std::string &path)
	Checks specified path for external network.
bool ATTR_DLL_LOCAL	kodi::vfs::IsLocal (const std::string &path)
	Checks whether the given path refers to the own system.
bool ATTR_DLL_LOCAL	kodi::vfs::IsURL (const std::string &path)
	Checks specified path is a regular URL, e.g. "someprotocol://path/to/file".
bool ATTR_DLL_LOCAL	kodi::vfs::GetHttpHeader (const std::string &url, HttpHeader &header)
	To get HTTP header information.
bool ATTR_DLL_LOCAL	kodi::vfs::GetMimeType (const std::string &url, std::string &mimeType, const std::string &useragent="")
	Get file mime type.
bool ATTR_DLL_LOCAL	kodi::vfs::GetContentType (const std::string &url, std::string &content, const std::string &useragent="")
	Get file content-type.
bool ATTR_DLL_LOCAL	kodi::vfs::GetCookies (const std::string &url, std::string &cookies)
	Get cookies stored by CURL in RFC 2109 format.

Detailed Description

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

Function Documentation

GetCacheThumbName()

std::string ATTR_DLL_LOCAL kodi::vfs::GetCacheThumbName ( const std::string & filename )

inline

Returns a thumb cache filename.

Parameters

[in]

filename

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

GetChunkSize()

unsigned int ATTR_DLL_LOCAL 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]	chunk	The chunk size
[in]	minimum	The minimum size (or maybe the minimum number of chunks?)

Returns

The aligned size

GetContentType()

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

inline

Get file content-type.

Parameters

[in]	url	URL source of the data
[out]	content	The returned type
[in]	useragent	to 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 ATTR_DLL_LOCAL kodi::vfs::GetCookies ( const std::string & url, std::string & cookies )

inline

Get cookies stored by CURL in RFC 2109 format.

Parameters

[in]	url	URL source of the data
[out]	cookies	The 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");
...

GetDirectoryName()

std::string ATTR_DLL_LOCAL kodi::vfs::GetDirectoryName ( const std::string & path )

inline

Return the directory name from given complete path string.

Parameters

[in]

path

The 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());

GetDiskSpace()

bool ATTR_DLL_LOCAL 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]	path	Path for where to check
[out]	capacity	The total number of bytes in the file system
[out]	free	The total number of free bytes in the file system
[out]	available	The 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);

GetFileMD5()

std::string ATTR_DLL_LOCAL kodi::vfs::GetFileMD5 ( const std::string & path )

inline

Retrieve MD5sum of a file.

Parameters

[in]

path

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

GetFileName()

std::string ATTR_DLL_LOCAL kodi::vfs::GetFileName ( const std::string & path )

inline

Return the file name from given complete path string.

Parameters

[in]

path

The 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());

GetHttpHeader()

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

inline

To get HTTP header information.

Parameters

[in]	url	URL source of the data
[out]	header	The 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 ATTR_DLL_LOCAL kodi::vfs::GetMimeType ( const std::string & url, std::string & mimeType, const std::string & useragent = "" )

inline

Get file mime type.

Parameters

[in]	url	URL source of the data
[out]	mimeType	the mime type of the URL
[in]	useragent	to 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());
...

IsInternetStream()

bool ATTR_DLL_LOCAL 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]	path	To 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);

IsLocal()

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

inline

Checks whether the given path refers to the own system.

Parameters

[in]

path

To checked path

Returns

True if path is local, false otherwise

IsOnLAN()

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

path

To 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 ATTR_DLL_LOCAL kodi::vfs::IsRemote ( const std::string & path )

inline

Checks specified path for external network.

Parameters

[in]

path

To 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");

IsURL()

bool ATTR_DLL_LOCAL 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");

MakeLegalFileName()

std::string ATTR_DLL_LOCAL 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]

filename

Filename 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 ATTR_DLL_LOCAL 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]

path

Directory 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;/

RemoveSlashAtEnd()

void ATTR_DLL_LOCAL kodi::vfs::RemoveSlashAtEnd ( std::string & path )

inline

Remove the slash on given path name.

Parameters

[in,out]

path

The 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());

TranslateSpecialProtocol()

std::string ATTR_DLL_LOCAL kodi::vfs::TranslateSpecialProtocol ( const std::string & source )

inline

Returns the translated path.

Parameters

[in]

source

String 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());
...