Interface - kodi

General addon interface functions More...

Modules
	Definitions, structures and enumerators
	General definition values
	1. Setting control
	Functions to handle settings access This can be used to get and set the addon related values inside his settings.xml.

Functions
std::string ATTR_DLL_LOCAL	kodi::GetKodiTypeVersion (int type)
	To get used version inside Kodi itself about asked type. More...
std::string ATTR_DLL_LOCAL	kodi::GetAddonPath (const std::string &append="")
	To get the addon system installation folder. More...
std::string ATTR_DLL_LOCAL	kodi::GetBaseUserPath (const std::string &append="")
	To get the user-related folder of the addon. More...
std::string ATTR_DLL_LOCAL	kodi::GetLibPath ()
	This function gives OS associated executable binary path of the addon. More...
void ATTR_DLL_LOCAL	kodi::Log (const AddonLog loglevel, const char *format,...)
	Add a message to Kodi's log. More...
std::string ATTR_DLL_LOCAL	kodi::TranslateAddonStatus (ADDON_STATUS status)
	Get to related ADDON_STATUS a human readable text. More...
void *	kodi::GetInterface (const std::string &name, const std::string &version)
	Returns a function table to a named interface. More...
std::string ATTR_DLL_LOCAL	kodi::GetAddonInfo (const std::string &id)
	Returns the value of an addon property as a string. More...
bool ATTR_DLL_LOCAL	kodi::OpenSettings ()
	Opens this Add-Ons settings dialog. More...
std::string ATTR_DLL_LOCAL	kodi::GetLocalizedString (uint32_t labelId, const std::string &defaultStr="")
	Returns an addon's localized 'unicode string'. More...
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. More...
std::string ATTR_DLL_LOCAL	kodi::GetLanguage (LangFormats format=LANG_FMT_ENGLISH_NAME, bool region=false)
	Returns the active language as a string. More...
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. More...
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. More...
std::string ATTR_DLL_LOCAL	kodi::GetMD5 (const std::string &text)
	Get the MD5 digest of the given text. More...
std::string ATTR_DLL_LOCAL	kodi::GetTempAddonPath (const std::string &append="")
	To get a temporary path for the addon. More...
std::string ATTR_DLL_LOCAL	kodi::GetRegion (const std::string &id)
	Returns your regions setting as a string for the specified id. More...
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. More...
int ATTR_DLL_LOCAL	kodi::GetGlobalIdleTime ()
	Returns the elapsed idle time in seconds as an integer. More...
std::string ATTR_DLL_LOCAL	kodi::GetCurrentSkinId ()
	Get the currently used skin identification name from Kodi. More...
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.: More...
bool ATTR_DLL_LOCAL	kodi::GetKeyboardLayout (int modifierKey, std::string &layout_name, std::vector< std::vector< std::string > > &layout)
	To get keyboard layout characters. More...
bool ATTR_DLL_LOCAL	kodi::ChangeKeyboardLayout (std::string &layout_name)
	To change keyboard layout characters. More...

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

GetAddonInfo()

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

GetAddonPath()

std::string ATTR_DLL_LOCAL kodi::GetAddonPath ( const std::string &  append = "" )

inline

To get the addon system installation folder.

Parameters

[in]

append

[optional] Path to append to given string

Returns

Path where addon is installed

GetBaseUserPath()

std::string ATTR_DLL_LOCAL kodi::GetBaseUserPath ( const std::string &  append = "" )

inline

To get the user-related folder of the addon.

Note

This folder is not created automatically and has to be created by the addon the first time.

Parameters

[in]

append

[optional] Path to append to given string

Returns

User path of addon

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

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

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

GetKodiTypeVersion()

std::string ATTR_DLL_LOCAL kodi::GetKodiTypeVersion ( int  type )

inline

To get used version inside Kodi itself about asked type.

This thought to allow a addon a handling of newer addon versions within older Kodi until the type min version not changed.

Parameters

[in]

type

The wanted type of ADDON_TYPE to ask

Returns

The version string about type in MAJOR.MINOR.PATCH style.

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

GetLibPath()

std::string ATTR_DLL_LOCAL kodi::GetLibPath ( )

inline

This function gives OS associated executable binary path of the addon.

With some systems this can differ from the addon path at GetAddonPath.

As an example on Linux:

• Addon path is at /usr/share/kodi/addons/YOUR_ADDON_ID
• Library path is at /usr/lib/kodi/addons/YOUR_ADDON_ID

Note

In addition, in this function, for a given folder, the add-on path itself, but its parent.

Returns

Kodi's system library path where related addons are installed.

GetLocalizedString()

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

GetTempAddonPath()

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

OpenSettings()

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

TranslateAddonStatus()

std::string ATTR_DLL_LOCAL kodi::TranslateAddonStatus ( ADDON_STATUS  status )

inline

Get to related ADDON_STATUS a human readable text.

Parameters

[in]

status

Status value to get name for

Returns

Wanted name, as "Unknown" if status not known

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