Kodi Development  20.0
for Binary and Script based Add-Ons
Interface - kodi

Detailed Description

General addon interface functions

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.
 

Function Documentation

◆ GetKodiTypeVersion()

std::string ATTRIBUTE_HIDDEN 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]typeThe wanted type of ADDON_TYPE to ask
Returns
The version string about type in MAJOR.MINOR.PATCH style.

◆ GetAddonPath()

std::string ATTRIBUTE_HIDDEN 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 ATTRIBUTE_HIDDEN 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

◆ GetLibPath()

std::string ATTRIBUTE_HIDDEN 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 sytem library path where related addons are installed.

◆ Log()

void ATTRIBUTE_HIDDEN kodi::Log ( const AddonLog  loglevel,
const char *  format,
  ... 
)
inline

Add a message to Kodi's log.

Parameters
[in]loglevelThe log level of the message.
[in]formatThe 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__);
@ ADDON_LOG_ERROR
3 : To report error messages in the log file.
Definition: addon_base.h:183
void ATTRIBUTE_HIDDEN Log(const AddonLog loglevel, const char *format,...)
Add a message to Kodi's log.
Definition: AddonBase.h:749

◆ TranslateAddonStatus()

std::string ATTRIBUTE_HIDDEN kodi::TranslateAddonStatus ( ADDON_STATUS  status)
inline

Get to related ADDON_STATUS a human readable text.

Parameters
[in]statusStatus value to get name for
Returns
Wanted name, as "Unknown" if status not known

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

◆ GetAddonInfo()

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

Returns the value of an addon property as a string.

Parameters
[in]idid 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");
...
std::string ATTRIBUTE_HIDDEN GetAddonInfo(const std::string &id)
Returns the value of an addon property as a string.
Definition: General.h:67

◆ OpenSettings()

bool ATTRIBUTE_HIDDEN 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>
..
..
bool ATTRIBUTE_HIDDEN OpenSettings()
Opens this Add-Ons settings dialog.
Definition: General.h:102

◆ GetLocalizedString()

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

Returns an addon's localized 'unicode string'.

Parameters
[in]labelIdstring 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");
...
std::string ATTRIBUTE_HIDDEN GetLocalizedString(uint32_t labelId, const std::string &defaultStr="")
Returns an addon's localized 'unicode string'.
Definition: General.h:137

◆ UnknownToUTF8()

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

Translate a string with an unknown encoding to UTF8.

Parameters
[in]stringSrcThe string to translate.
[out]utf8StringDstThe 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");
...
bool ATTRIBUTE_HIDDEN UnknownToUTF8(const std::string &stringSrc, std::string &utf8StringDst, bool failOnBadChar=false)
Translate a string with an unknown encoding to UTF8.
Definition: General.h:177

◆ GetLanguage()

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

Returns the active language as a string.

Parameters
[in]formatUsed 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);
...
@ LANG_FMT_ISO_639_1
two letter code as defined in ISO 639-1
Definition: general.h:64
std::string ATTRIBUTE_HIDDEN GetLanguage(LangFormats format=LANG_FMT_ENGLISH_NAME, bool region=false)
Returns the active language as a string.
Definition: General.h:221

◆ QueueFormattedNotification()

void ATTRIBUTE_HIDDEN 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]typeThe message type.
enum code: Description:
QUEUE_INFO Show info notification message
QUEUE_WARNING Show warning notification message
QUEUE_ERROR Show error notification message
[in]formatThe 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");
...
@ QUEUE_WARNING
Show warning notification message.
Definition: general.h:47

◆ QueueNotification()

void ATTRIBUTE_HIDDEN 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]typeThe 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]headerHeader Name (if leaved empty becomes addon name used)
[in]messageMessage 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);
...
@ QUEUE_OWN_STYLE
Show with own given image and parts if set on values.
Definition: general.h:51

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

◆ GetMD5()

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

Get the MD5 digest of the given text.

Parameters
[in]texttext 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());
...
std::string ATTRIBUTE_HIDDEN GetMD5(const std::string &text)
Get the MD5 digest of the given text.
Definition: General.h:409

◆ GetTempAddonPath()

std::string ATTRIBUTE_HIDDEN 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]appendA string to append to returned temporary path
Returns
Individual path for the addon

◆ GetRegion()

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

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

Parameters
[in]idid 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");
...
std::string ATTRIBUTE_HIDDEN GetRegion(const std::string &id)
Returns your regions setting as a string for the specified id.
Definition: General.h:478

◆ GetFreeMem()

void ATTRIBUTE_HIDDEN 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]freefree memory
[out]totaltotal 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);
...
void ATTRIBUTE_HIDDEN GetFreeMem(long &free, long &total, bool asBytes=false)
Returns the amount of free memory in MByte (or as bytes) as an long integer.
Definition: General.h:519

◆ GetGlobalIdleTime()

int ATTRIBUTE_HIDDEN kodi::GetGlobalIdleTime ( )
inline

Returns the elapsed idle time in seconds as an integer.

Returns
idle time

Example:

#include <kodi/General.h>
...
...
int ATTRIBUTE_HIDDEN GetGlobalIdleTime()
Returns the elapsed idle time in seconds as an integer.
Definition: General.h:547

◆ GetCurrentSkinId()

std::string ATTRIBUTE_HIDDEN 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();
..
std::string ATTRIBUTE_HIDDEN GetCurrentSkinId()
Get the currently used skin identification name from Kodi.
Definition: General.h:577

◆ KodiVersion()

void ATTRIBUTE_HIDDEN 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]versionstructure to store data from kodi

Example:

#include <kodi/General.h>
...
kodi_version_t 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());
...
void ATTRIBUTE_HIDDEN KodiVersion(kodi_version_t &version)
Get current Kodi informations and versions, returned data from the following kodi_version_t version; ...
Definition: General.h:675

◆ GetKeyboardLayout()

bool ATTRIBUTE_HIDDEN 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]modifierKeythe key to define the needed layout (uppercase, symbols...)
[out]layout_namename of used layout
[out]layoutlist 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;
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());
}
}
...
@ STD_KB_BUTTONS_PER_ROW
The quantity of buttons per row on Kodi's standard keyboard.
Definition: general.h:26
@ STD_KB_BUTTONS_MAX_ROWS
The quantity of rows on Kodi's standard keyboard.
Definition: general.h:28
@ STD_KB_MODIFIER_KEY_SHIFT
Keyboard layout type, this for shift controled layout (uppercase)
Definition: general.h:32
@ STD_KB_MODIFIER_KEY_SYMBOL
Keyboard layout type, this to show symbols.
Definition: general.h:34
bool ATTRIBUTE_HIDDEN GetKeyboardLayout(int modifierKey, std::string &layout_name, std::vector< std::vector< std::string >> &layout)
To get keyboard layout characters.
Definition: General.h:743

◆ ChangeKeyboardLayout()

bool ATTRIBUTE_HIDDEN 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_namenew 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;
std::vector<std::vector<std::string>> 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());
}
}
...
bool ATTRIBUTE_HIDDEN ChangeKeyboardLayout(std::string &layout_name)
To change keyboard layout characters.
Definition: General.h:815