Interface - kodi

General addon interface functions More...

Modules
	Definitions, structures and enumerators
	General definition values

Functions
void *	kodi::GetInterface (const std::string &name, const std::string &version)
	Returns a function table to a named interface. More...
std::string	kodi::GetAddonInfo (const std::string &id)
	Returns the value of an addon property as a string. More...
bool	kodi::OpenSettings ()
	Opens this Add-Ons settings dialog. More...
std::string	kodi::GetLocalizedString (uint32_t labelId, const std::string &defaultStr="")
	Returns an addon's localized 'unicode string'. More...
bool	kodi::UnknownToUTF8 (const std::string &stringSrc, std::string &utf8StringDst, bool failOnBadChar=false)
	Translate a string with an unknown encoding to UTF8. More...
std::string	kodi::GetLanguage (LangFormats format=LANG_FMT_ENGLISH_NAME, bool region=false)
	Returns the active language as a string. More...
void	kodi::QueueFormattedNotification (QueueMsg type, const char *format,...)
	Writes the C string pointed by format in the GUI. If format includes format specifiers (subsequences beginning with %), the additional arguments following format are formatted and inserted in the resulting string replacing their respective specifiers. More...
void	kodi::QueueNotification (QueueMsg type, const std::string &header, const std::string &message, const std::string &imageFile="", unsigned int displayTime=5000, bool withSound=true, unsigned int messageTime=1000)
	Queue a notification in the GUI. More...
std::string	kodi::GetMD5 (const std::string &text)
	Get the MD5 digest of the given text. More...
std::string	kodi::GetTempAddonPath (const std::string &append="")
	To get a temporary path for the addon. More...
std::string	kodi::GetRegion (const std::string &id)
	Returns your regions setting as a string for the specified id. More...
void	kodi::GetFreeMem (long &free, long &total, bool asBytes=false)
	Returns the amount of free memory in MByte (or as bytes) as an long integer. More...
int	kodi::GetGlobalIdleTime ()
	Returns the elapsed idle time in seconds as an integer. More...
std::string	kodi::GetCurrentSkinId ()
void	kodi::KodiVersion (kodi_version_t &version)
	Get current Kodi informations and versions, returned data from the following kodi_version_t version; kodi::KodiVersion(version); is e.g.: More...

Detailed Description

General addon interface functions

Function Documentation

GetAddonInfo()

std::string kodi::GetAddonInfo ( const std::string &  id )

inline

Returns the value of an addon property as a string.

Parameters

[in]

id

id of the property that the module needs to access Choices are author icon stars changelog id summary description name type disclaimer path version fanart profile

Returns

AddOn property as a string

---

Example:

#include <kodi/General.h>
...
std::string addonName = kodi::GetAddonInfo("name");
...

GetCurrentSkinId()

std::string kodi::GetCurrentSkinId ( )

inline

@brief Get the currently used skin identification name from Kodi

Returns

The active skin id name as a string

Note

This is not the full path like 'special://home/addons/MediaCenter', but only 'MediaCenter'.

---

Example:

#include <kodi/General.h>
..
std::string skinid = kodi::GetCurrentSkinId();
..

GetFreeMem()

void kodi::GetFreeMem ( long &  free, long &  total, bool  asBytes = false  )

inline

Returns the amount of free memory in MByte (or as bytes) as an long integer.

Parameters

[out]	free	free memory
[out]	total	total memory
[in]	asBytes	[opt] if set to true becomes returned as bytes, otherwise as mega bytes

---

Example:

#include <kodi/General.h>
...
long freeMem;
long totalMem;
kodi::GetFreeMem(freeMem, totalMem);
...

GetGlobalIdleTime()

int kodi::GetGlobalIdleTime ( )

inline

Returns the elapsed idle time in seconds as an integer.

Returns

idle time

---

Example:

#include <kodi/General.h>
...
int time = kodi::GetGlobalIdleTime();
...

GetInterface()

void * kodi::GetInterface ( const std::string &  name, const std::string &  version  )

inline

Returns a function table to a named interface.

Returns

pointer to struct containing interface functions

---

Example:

#include <kodi/General.h>
#include <kodi/platform/foo.h>
...
FuncTable_foo *table = kodi::GetPlatformInfo(foo_name, foo_version);
...

GetLanguage()

std::string kodi::GetLanguage ( LangFormats  format = LANG_FMT_ENGLISH_NAME, bool  region = false  )

inline

Returns the active language as a string.

Parameters

[in]	format	Used format of the returned language string enum code: Description: LANG_FMT_ENGLISH_NAME full language name in English (Default) LANG_FMT_ISO_639_1 two letter code as defined in ISO 639-1 LANG_FMT_ISO_639_2 three letter code as defined in ISO 639-2/T or ISO 639-2/B
[in]	region	[opt] append the region delimited by "-" of the language (setting) to the returned language string (default is false)

Returns

active language

---

Example:

#include <kodi/General.h>
...
std::string language = kodi::GetLanguage(LANG_FMT_ISO_639_1, false);
...

GetLocalizedString()

std::string kodi::GetLocalizedString ( uint32_t  labelId, const std::string &  defaultStr = ""  )

inline

Returns an addon's localized 'unicode string'.

Parameters

[in]	labelId	string you want to localize
[in]	defaultStr	[opt] The default message, also helps to identify the code that is used (default is empty)

Returns

The localized message, or default if the add-on helper fails to return a message

Note

Label id's 30000 to 30999 and 32000 to 32999 are related to the add-on's own included strings from ./resources/language/resource.language.??_??/strings.po All other strings are from Kodi core language files.

---

Example:

#include <kodi/General.h>
...
std::string str = kodi::GetLocalizedString(30005, "Use me as default");
...

GetMD5()

std::string kodi::GetMD5 ( const std::string &  text )

inline

Get the MD5 digest of the given text.

Parameters

[in]

text

text to compute the MD5 for

Returns

Returned MD5 digest

---

Example:

#include <kodi/General.h>
...
std::string md5 = kodi::GetMD5("Make me as md5");
fprintf(stderr, "My md5 digest is: '%s'\n", md5.c_str());
...

GetRegion()

std::string kodi::GetRegion ( const std::string &  id )

inline

Returns your regions setting as a string for the specified id.

Parameters

[in]

id

id of setting to return Choices are dateshort time tempunit datelong meridiem speedunit

Returns

settings string

---

Example:

#include <kodi/General.h>
...
std::string timeFormat = kodi::GetRegion("time");
...

GetTempAddonPath()

std::string kodi::GetTempAddonPath ( const std::string &  append = "" )

inline

To get a temporary path for the addon.

This gives a temporary path which the addon can use individually for its things.

The content of this folder will be deleted when Kodi is finished!

Parameters

[in]

append

A string to append to returned temporary path

Returns

Individual path for the addon

KodiVersion()

void kodi::KodiVersion ( kodi_version_t &  version )

inline

Get current Kodi informations and versions, returned data from the following kodi_version_t version; kodi::KodiVersion(version); is e.g.:

version.compile_name = Kodi
version.major        = 18
version.minor        = 0
version.revision     = 20170706-c6b22fe217-di
version.tag          = alpha
version.tag_revision = 1

Parameters

[out]

version

structure to store data from kodi

---

Example:

#include <kodi/General.h>
...
kodi_version_t version;
kodi::KodiVersion(version);
fprintf(stderr,
    "kodi_version_t version;\n"
    "kodi::KodiVersion(version);\n"
    " - version.compile_name = %s\n"
    " - version.major        = %i\n"
    " - version.minor        = %i\n"
    " - version.revision     = %s\n"
    " - version.tag          = %s\n"
    " - version.tag_revision = %s\n",
            version.compile_name.c_str(), version.major, version.minor,
            version.revision.c_str(), version.tag.c_str(), version.tag_revision.c_str());
...

OpenSettings()

bool kodi::OpenSettings ( )

inline

Opens this Add-Ons settings dialog.

Returns

true if settings were changed and the dialog confirmed, false otherwise.

---

Example:

#include <kodi/General.h>
..
kodi::OpenSettings();
..

QueueFormattedNotification()

void kodi::QueueFormattedNotification ( QueueMsg  type, const char *  format,   ...  )

inline

Writes the C string pointed by format in the GUI. If format includes format specifiers (subsequences beginning with %), the additional arguments following format are formatted and inserted in the resulting string replacing their respective specifiers.

After the format parameter, the function expects at least as many additional arguments as specified by format.

Parameters

[in]	type	The message type. enum code: Description: QUEUE_INFO Show info notification message QUEUE_WARNING Show warning notification message QUEUE_ERROR Show error notification message
[in]	format	The format of the message to pass to display in Kodi. C string that contains the text to be written to the stream. It can optionally contain embedded format specifiers that are replaced by the values specified in subsequent additional arguments and formatted as requested. specifier Output Example d or i Signed decimal integer 392 u Unsigned decimal integer 7235 o Unsigned octal 610 x Unsigned hexadecimal integer 7fa X Unsigned hexadecimal integer (uppercase) 7FA f Decimal floating point, lowercase 392.65 F Decimal floating point, uppercase 392.65 e Scientific notation (mantissa/exponent), lowercase 3.9265e+2 E Scientific notation (mantissa/exponent), uppercase 3.9265E+2 g Use the shortest representation: e or f 392.65 G Use the shortest representation: E or F 392.65 a Hexadecimal floating point, lowercase -0xc.90fep-2 A Hexadecimal floating point, uppercase -0XC.90FEP-2 c Character a s String of characters sample p Pointer address b8000000 % A % followed by another % character will write a single % to the stream. %

The length sub-specifier modifies the length of the data type. This is a chart showing the types used to interpret the corresponding arguments with and without length specifier (if a different type is used, the proper type promotion or conversion is performed, if allowed):

length	d i	u o x X	f F e E g G a A	c	s	p	n
(none)	int	unsigned int	double	int	char*	void*	int*
hh	signed char	unsigned char					signed char*
h	short int	unsigned short int					short int*
l	long int	unsigned long int		wint_t	wchar_t*		long int*
ll	long long int	unsigned long long int					long long int*
j	intmax_t	uintmax_t					intmax_t*
z	size_t	size_t					size_t*
t	ptrdiff_t	ptrdiff_t					ptrdiff_t*
L			long double

Note: that the c specifier takes an int (or wint_t) as argument, but performs the proper conversion to a char value (or a wchar_t) before formatting it for output.

Parameters

[in]

...

(additional arguments) Depending on the format string, the function may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string (or a pointer to a storage location, for n). There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the function.

---

Example:

#include <kodi/General.h>
...
kodi::QueueFormattedNotification(QUEUE_WARNING, "I'm want to inform you, here with a test call to show '%s'", "this");
...

QueueNotification()

void kodi::QueueNotification ( QueueMsg  type, const std::string &  header, const std::string &  message, const std::string &  imageFile = "", unsigned int  displayTime = 5000, bool  withSound = true, unsigned int  messageTime = 1000  )

inline

Queue a notification in the GUI.

Parameters

[in]	type	The message type. enum code: Description: QUEUE_INFO Show info notification message QUEUE_WARNING Show warning notification message QUEUE_ERROR Show error notification message QUEUE_OWN_STYLE If used can be with imageFile the wanted image set or if leaved empty shown as info, also are the other optional values available then
[in]	header	Header Name (if leaved empty becomes addon name used)
[in]	message	Message to display on Kodi
[in]	imageFile	[opt] The image file to show on message (to use must be type set to QUEUE_OWN_STYLE)
[in]	displayTime	[opt] The time how long message is displayed (default 5 sec) (to use must be type set to QUEUE_OWN_STYLE)
[in]	withSound	[opt] if true also warning sound becomes played (default with sound) (to use must be type set to QUEUE_OWN_STYLE)
[in]	messageTime	[opt] how many milli seconds start show of notification (default 1 sec) (to use must be type set to QUEUE_OWN_STYLE)

---

Example:

#include <kodi/General.h>
...
kodi::QueueNotification(QUEUE_OWN_STYLE, "I'm want to inform you", "Here with a test call", "", 3000, false, 1000);
...

Example:

#include <kodi/General.h>
...
kodi::QueueNotification(QUEUE_WARNING, "I'm want to inform you", "Here with a test call");
...

Example:

#include <kodi/General.h>
...
kodi::QueueNotification(QUEUE_OWN_STYLE, "", "Here with a test call", "./myImage.png");
...

UnknownToUTF8()

bool kodi::UnknownToUTF8 ( const std::string &  stringSrc, std::string &  utf8StringDst, bool  failOnBadChar = false  )

inline

Translate a string with an unknown encoding to UTF8.

Parameters

[in]	stringSrc	The string to translate.
[out]	utf8StringDst	The translated string.
[in]	failOnBadChar	[opt] returns failed if bad character is inside (default is false)

Returns

true if OK

---

Example:

#include <kodi/General.h>
...
std::string ret;
if (!kodi::UnknownToUTF8("test string", ret, true))
  fprintf(stderr, "Translation to UTF8 failed!\n");
...