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 ()
	Get the currently used skin identification name from Kodi More...

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.: version.compile_name = Kodi version.major = 18 version.minor = 0 version.revision = 20170706-c6b22fe217-di version.tag = alpha version.tag_revision = 1 . 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

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.

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

Modules

Functions

Get the currently used skin identification name from Kodi

Detailed Description

Function Documentation

§ GetAddonInfo()

§ GetCurrentSkinId()

Get the currently used skin identification name from Kodi

§ GetFreeMem()

§ GetGlobalIdleTime()

§ GetInterface()

§ GetLanguage()

§ GetLocalizedString()

§ GetMD5()

§ GetRegion()

§ GetTempAddonPath()

§ KodiVersion()

§ OpenSettings()

§ QueueFormattedNotification()

§ QueueNotification()

§ UnknownToUTF8()