Interface - kodi

General addon interface functions More...

Topics
	Definitions, structures and enumerators
	General definition values

Functions
void ATTR_DLL_LOCAL	kodi::Log (const ADDON_LOG loglevel, const char *format,...)
	Add a message to Kodi's log.
bool ATTR_DLL_LOCAL	kodi::UnknownToUTF8 (const std::string &stringSrc, std::string &utf8StringDst, bool failOnBadChar=false)
	Translate a string with an unknown encoding to UTF8.
std::string ATTR_DLL_LOCAL	kodi::GetLanguage (LangFormats format=LANG_FMT_ENGLISH_NAME, bool region=false)
	Returns the active language as a string.
void ATTR_DLL_LOCAL	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.
void ATTR_DLL_LOCAL	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.
std::string ATTR_DLL_LOCAL	kodi::GetMD5 (const std::string &text)
	Get the MD5 digest of the given text.
std::string ATTR_DLL_LOCAL	kodi::GetRegion (const std::string &id)
	Returns your regions setting as a string for the specified id.
void ATTR_DLL_LOCAL	kodi::GetFreeMem (long &free, long &total, bool asBytes=false)
	Returns the amount of free memory in MByte (or as bytes) as an long integer.
int ATTR_DLL_LOCAL	kodi::GetGlobalIdleTime ()
	Returns the elapsed idle time in seconds as an integer.
std::string ATTR_DLL_LOCAL	kodi::GetCurrentSkinId ()
	Get the currently used skin identification name from Kodi.
bool ATTR_DLL_LOCAL	kodi::IsAddonAvailable (const std::string &id, std::string &version, bool &enabled)
	To check another addon is available and usable inside Kodi.
void ATTR_DLL_LOCAL	kodi::KodiVersion (kodi_version_t &version)
	Get current Kodi information and versions, returned data from the following kodi_version_t version; kodi::KodiVersion(version); is e.g.:
bool ATTR_DLL_LOCAL	kodi::GetKeyboardLayout (int modifierKey, std::string &layout_name, std::vector< std::vector< std::string > > &layout)
	To get keyboard layout characters.
bool ATTR_DLL_LOCAL	kodi::ChangeKeyboardLayout (std::string &layout_name)
	To change keyboard layout characters.

Detailed Description

General addon interface functions

Function Documentation

ChangeKeyboardLayout()

bool ATTR_DLL_LOCAL kodi::ChangeKeyboardLayout ( std::string & layout_name )

inline

To change keyboard layout characters.

This is used to change the keyboard layout currently used from Kodi

Parameters

[out]

layout_name

new name of used layout (input string not used!)

Returns

true if request successed

Note

GetKeyboardLayout must be called afterwards.

---

Example:

#include <kodi/General.h>
...
std::string layout_name;
kodi::ChangeKeyboardLayout(layout_name);
 
std::vector<std::vector<std::string>> layout;
kodi::GetKeyboardLayout(STD_KB_MODIFIER_KEY_SHIFT | STD_KB_MODIFIER_KEY_SYMBOL, layout_name, layout);
fprintf(stderr, "Layout: '%s'\n", layout_name.c_str());
for (unsigned int row = 0; row < STD_KB_BUTTONS_MAX_ROWS; row++)
{
  for (unsigned int column = 0; column < STD_KB_BUTTONS_PER_ROW; column++)
  {
    fprintf(stderr, " - Row: '%02i'; Column: '%02i'; Text: '%s'\n", row, column, layout[row][column].c_str());
  }
}
...

GetCurrentSkinId()

std::string ATTR_DLL_LOCAL kodi::GetCurrentSkinId ( )

inline

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

GetKeyboardLayout()

bool ATTR_DLL_LOCAL kodi::GetKeyboardLayout ( int modifierKey, std::string & layout_name, std::vector< std::vector< std::string > > & layout )

inline

To get keyboard layout characters.

This is used to get the keyboard layout currently used from Kodi by the there set language.

Parameters

[in]	modifierKey	the key to define the needed layout (uppercase, symbols...)
[out]	layout_name	name of used layout
[out]	layout	list of selected keyboard layout

Returns

true if request successed

---

Example:

#include <kodi/General.h>
...
std::string layout_name;
std::vector<std::vector<std::string>> layout;
kodi::GetKeyboardLayout(STD_KB_MODIFIER_KEY_SHIFT | STD_KB_MODIFIER_KEY_SYMBOL, layout_name, layout);
fprintf(stderr, "Layout: '%s'\n", layout_name.c_str());
for (unsigned int row = 0; row < STD_KB_BUTTONS_MAX_ROWS; row++)
{
  for (unsigned int column = 0; column < STD_KB_BUTTONS_PER_ROW; column++)
  {
    fprintf(stderr, " - Row: '%02i'; Column: '%02i'; Text: '%s'\n", row, column, layout[row][column].c_str());
  }
}
...

GetLanguage()

std::string ATTR_DLL_LOCAL 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);
...

GetMD5()

std::string ATTR_DLL_LOCAL 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 ATTR_DLL_LOCAL 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");
...

IsAddonAvailable()

bool ATTR_DLL_LOCAL kodi::IsAddonAvailable ( const std::string & id, std::string & version, bool & enabled )

inline

To check another addon is available and usable inside Kodi.

Parameters

[in]	id	The wanted addon identification string to check
[out]	version	Version string of addon if installed inside Kodi
[out]	enabled	Set to true true* </b> if addon is enabled @return Returns <b>true* if addon is installed

---

Example:

#include <kodi/General.h>
 
bool enabled = false;
std::string version;
bool ret = kodi::IsAddonAvailable("inputstream.adaptive", version, enabled);
fprintf(stderr, "Available inputstream.adaptive version '%s' and enabled '%s'\n",
           ret ? version.c_str() : "not installed", enabled ? "yes" : "no");

KodiVersion()

void ATTR_DLL_LOCAL kodi::KodiVersion ( kodi_version_t & version )

inline

Get current Kodi information 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());
...

Log()

void ATTR_DLL_LOCAL kodi::Log ( const ADDON_LOG loglevel, const char * format, ... )

inline

Add a message to Kodi's log.

Parameters

[in]	loglevel	The log level of the message.
[in]	format	The format of the message to pass to Kodi.
[in]	...	Additional text to insert in format text

Note

This method uses limited buffer (16k) for the formatted output. So data, which will not fit into it, will be silently discarded.

---

Example:

#include <kodi/General.h>
 
kodi::Log(ADDON_LOG_ERROR, "%s: There is an error occurred!", __func__);

QueueFormattedNotification()

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