summaryrefslogtreecommitdiffstats
path: root/xbmc/addons/kodi-addon-dev-kit/include/kodi/AddonBase.h
diff options
context:
space:
mode:
Diffstat (limited to 'xbmc/addons/kodi-addon-dev-kit/include/kodi/AddonBase.h')
-rw-r--r--xbmc/addons/kodi-addon-dev-kit/include/kodi/AddonBase.h1288
1 files changed, 0 insertions, 1288 deletions
diff --git a/xbmc/addons/kodi-addon-dev-kit/include/kodi/AddonBase.h b/xbmc/addons/kodi-addon-dev-kit/include/kodi/AddonBase.h
deleted file mode 100644
index b0fddda..0000000
--- a/xbmc/addons/kodi-addon-dev-kit/include/kodi/AddonBase.h
+++ /dev/null
@@ -1,1288 +0,0 @@
1/*
2 * Copyright (C) 2005-2018 Team Kodi
3 * This file is part of Kodi - https://kodi.tv
4 *
5 * SPDX-License-Identifier: GPL-2.0-or-later
6 * See LICENSES/README.md for more information.
7 */
8
9#pragma once
10
11#include "c-api/addon_base.h"
12#include "versions.h"
13
14#include <assert.h> /* assert */
15#include <cstdlib>
16#include <cstring>
17#include <ctime>
18#include <memory>
19#include <stdarg.h> /* va_list, va_start, va_arg, va_end */
20#include <stdexcept>
21#include <string>
22#include <vector>
23
24namespace kodi
25{
26
27namespace gui
28{
29struct IRenderHelper;
30} // namespace gui
31
32//==============================================================================
33/// @ingroup cpp_kodi_addon_addonbase_Defs
34/// @defgroup cpp_kodi_addon_addonbase_Defs_CSettingValue class CSettingValue
35/// @brief Inside addon main instance used helper class to give settings value.
36///
37/// This is used on @ref addon::CAddonBase::SetSetting() to inform addon about
38/// settings change by used. This becomes then used to give the related value
39/// name.
40///
41/// ----------------------------------------------------------------------------
42///
43/// @copydetails cpp_kodi_addon_addonbase_Defs_CSettingValue_Help
44///
45/// ----------------------------------------------------------------------------
46///
47/// **Here is a code example how this is used:**
48///
49/// ~~~~~~~~~~~~~{.cpp}
50/// #include <kodi/AddonBase.h>
51///
52/// enum myEnumValue
53/// {
54/// valueA,
55/// valueB,
56/// valueC
57/// };
58///
59/// std::string m_myStringValue;
60/// int m_myIntegerValue;
61/// bool m_myBooleanValue;
62/// float m_myFloatingPointValue;
63/// myEnumValue m_myEnumValue;
64///
65///
66/// ADDON_STATUS CMyAddon::SetSetting(const std::string& settingName, const kodi::CSettingValue& settingValue)
67/// {
68/// if (settingName == "my_string_value")
69/// m_myStringValue = settingValue.GetString();
70/// else if (settingName == "my_integer_value")
71/// m_myIntegerValue = settingValue.GetInt();
72/// else if (settingName == "my_boolean_value")
73/// m_myBooleanValue = settingValue.GetBoolean();
74/// else if (settingName == "my_float_value")
75/// m_myFloatingPointValue = settingValue.GetFloat();
76/// else if (settingName == "my_enum_value")
77/// m_myEnumValue = settingValue.GetEnum<myEnumValue>();
78/// }
79/// ~~~~~~~~~~~~~
80///
81/// @note The asked type should match the type used on settings.xml.
82///
83///@{
84class ATTRIBUTE_HIDDEN CSettingValue
85{
86public:
87 explicit CSettingValue(const void* settingValue) : m_settingValue(settingValue) {}
88
89 bool empty() const { return (m_settingValue == nullptr) ? true : false; }
90
91 /// @defgroup cpp_kodi_addon_addonbase_Defs_CSettingValue_Help Value Help
92 /// @ingroup cpp_kodi_addon_addonbase_Defs_CSettingValue
93 ///
94 /// <b>The following table contains values that can be set with @ref cpp_kodi_addon_addonbase_Defs_CSettingValue :</b>
95 /// | Name | Type | Get call
96 /// |------|------|----------
97 /// | **Settings value as string** | `std::string` | @ref CSettingValue::GetString "GetString"
98 /// | **Settings value as integer** | `int` | @ref CSettingValue::GetInt "GetInt"
99 /// | **Settings value as unsigned integer** | `unsigned int` | @ref CSettingValue::GetUInt "GetUInt"
100 /// | **Settings value as boolean** | `bool` | @ref CSettingValue::GetBoolean "GetBoolean"
101 /// | **Settings value as floating point** | `float` | @ref CSettingValue::GetFloat "GetFloat"
102 /// | **Settings value as enum** | `enum` | @ref CSettingValue::GetEnum "GetEnum"
103
104 /// @addtogroup cpp_kodi_addon_addonbase_Defs_CSettingValue
105 ///@{
106
107 /// @brief To get settings value as string.
108 std::string GetString() const { return (const char*)m_settingValue; }
109
110 /// @brief To get settings value as integer.
111 int GetInt() const { return *(const int*)m_settingValue; }
112
113 /// @brief To get settings value as unsigned integer.
114 unsigned int GetUInt() const { return *(const unsigned int*)m_settingValue; }
115
116 /// @brief To get settings value as boolean.
117 bool GetBoolean() const { return *(const bool*)m_settingValue; }
118
119 /// @brief To get settings value as floating point.
120 float GetFloat() const { return *(const float*)m_settingValue; }
121
122 /// @brief To get settings value as enum.
123 /// @note Inside settings.xml them stored as integer.
124 template<typename enumType>
125 enumType GetEnum() const
126 {
127 return static_cast<enumType>(*(const int*)m_settingValue);
128 }
129
130 ///@}
131
132private:
133 const void* m_settingValue;
134};
135///@}
136//------------------------------------------------------------------------------
137
138namespace addon
139{
140
141//==============================================================================
142/*
143 * Internal class to control various instance types with general parts defined
144 * here.
145 *
146 * Mainly is this currently used to identify requested instance types.
147 *
148 * @note This class is not need to know during add-on development thats why
149 * commented with "*".
150 */
151class ATTRIBUTE_HIDDEN IAddonInstance
152{
153public:
154 explicit IAddonInstance(ADDON_TYPE type, const std::string& version)
155 : m_type(type), m_kodiVersion(version)
156 {
157 }
158 virtual ~IAddonInstance() = default;
159
160 virtual ADDON_STATUS CreateInstance(int instanceType,
161 const std::string& instanceID,
162 KODI_HANDLE instance,
163 const std::string& version,
164 KODI_HANDLE& addonInstance)
165 {
166 return ADDON_STATUS_NOT_IMPLEMENTED;
167 }
168
169 const ADDON_TYPE m_type;
170 const std::string m_kodiVersion;
171 std::string m_id;
172};
173
174/*
175 * Internally used helper class to manage processing of a "C" structure in "CPP"
176 * class.
177 *
178 * At constant, the "C" structure is copied, otherwise the given pointer is
179 * superseded and is changeable.
180 *
181 * -----------------------------------------------------------------------------
182 *
183 * Example:
184 *
185 * ~~~~~~~~~~~~~{.cpp}
186 * extern "C" typedef struct C_SAMPLE_DATA
187 * {
188 * unsigned int iUniqueId;
189 * } C_SAMPLE_DATA;
190 *
191 * class CPPSampleData : public CStructHdl<CPPSampleData, C_SAMPLE_DATA>
192 * {
193 * public:
194 * CPPSampleData() = default;
195 * CPPSampleData(const CPPSampleData& sample) : CStructHdl(sample) { }
196 * CPPSampleData(const C_SAMPLE_DATA* sample) : CStructHdl(sample) { }
197 * CPPSampleData(C_SAMPLE_DATA* sample) : CStructHdl(sample) { }
198 *
199 * void SetUniqueId(unsigned int uniqueId) { m_cStructure->iUniqueId = uniqueId; }
200 * unsigned int GetUniqueId() const { return m_cStructure->iUniqueId; }
201 * };
202 *
203 * ~~~~~~~~~~~~~
204 *
205 * It also works with the following example:
206 *
207 * ~~~~~~~~~~~~~{.cpp}
208 * CPPSampleData test;
209 * // Some work
210 * C_SAMPLE_DATA* data = test;
211 * // Give "data" to Kodi
212 * ~~~~~~~~~~~~~
213 */
214template<class CPP_CLASS, typename C_STRUCT>
215class CStructHdl
216{
217public:
218 CStructHdl() : m_cStructure(new C_STRUCT()), m_owner(true) {}
219
220 CStructHdl(const CPP_CLASS& cppClass)
221 : m_cStructure(new C_STRUCT(*cppClass.m_cStructure)), m_owner(true)
222 {
223 }
224
225 CStructHdl(const C_STRUCT* cStructure) : m_cStructure(new C_STRUCT(*cStructure)), m_owner(true) {}
226
227 CStructHdl(C_STRUCT* cStructure) : m_cStructure(cStructure) { assert(cStructure); }
228
229 const CStructHdl& operator=(const CStructHdl& right)
230 {
231 assert(&right.m_cStructure);
232 if (m_cStructure && !m_owner)
233 {
234 memcpy(m_cStructure, right.m_cStructure, sizeof(C_STRUCT));
235 }
236 else
237 {
238 if (m_owner)
239 delete m_cStructure;
240 m_owner = true;
241 m_cStructure = new C_STRUCT(*right.m_cStructure);
242 }
243 return *this;
244 }
245
246 const CStructHdl& operator=(const C_STRUCT& right)
247 {
248 assert(&right);
249 if (m_cStructure && !m_owner)
250 {
251 memcpy(m_cStructure, &right, sizeof(C_STRUCT));
252 }
253 else
254 {
255 if (m_owner)
256 delete m_cStructure;
257 m_owner = true;
258 m_cStructure = new C_STRUCT(*right);
259 }
260 return *this;
261 }
262
263 virtual ~CStructHdl()
264 {
265 if (m_owner)
266 delete m_cStructure;
267 }
268
269 operator C_STRUCT*() { return m_cStructure; }
270 operator const C_STRUCT*() const { return m_cStructure; }
271
272 const C_STRUCT* GetCStructure() const { return m_cStructure; }
273
274protected:
275 C_STRUCT* m_cStructure = nullptr;
276
277private:
278 bool m_owner = false;
279};
280
281/// Add-on main instance class.
282class ATTRIBUTE_HIDDEN CAddonBase
283{
284public:
285 CAddonBase()
286 {
287 m_interface->toAddon->destroy = ADDONBASE_Destroy;
288 m_interface->toAddon->get_status = ADDONBASE_GetStatus;
289 m_interface->toAddon->create_instance = ADDONBASE_CreateInstance;
290 m_interface->toAddon->destroy_instance = ADDONBASE_DestroyInstance;
291 m_interface->toAddon->set_setting = ADDONBASE_SetSetting;
292 }
293
294 virtual ~CAddonBase() = default;
295
296 virtual ADDON_STATUS Create() { return ADDON_STATUS_OK; }
297
298 virtual ADDON_STATUS GetStatus() { return ADDON_STATUS_OK; }
299
300 //============================================================================
301 /// @ingroup cpp_kodi_addon_addonbase
302 /// @brief To inform addon about changed settings values.
303 ///
304 /// This becomes called for every entry defined inside his settings.xml and
305 /// as **last** call the one where last in xml (to identify end of calls).
306 ///
307 /// --------------------------------------------------------------------------
308 ///
309 /// @copydetails cpp_kodi_addon_addonbase_Defs_CSettingValue_Help
310 ///
311 ///
312 /// --------------------------------------------------------------------------
313 ///
314 /// **Here is a code example how this is used:**
315 ///
316 /// ~~~~~~~~~~~~~{.cpp}
317 /// #include <kodi/AddonBase.h>
318 ///
319 /// enum myEnumValue
320 /// {
321 /// valueA,
322 /// valueB,
323 /// valueC
324 /// };
325 ///
326 /// std::string m_myStringValue;
327 /// int m_myIntegerValue;
328 /// bool m_myBooleanValue;
329 /// float m_myFloatingPointValue;
330 /// myEnumValue m_myEnumValue;
331 ///
332 ///
333 /// ADDON_STATUS CMyAddon::SetSetting(const std::string& settingName, const kodi::CSettingValue& settingValue)
334 /// {
335 /// if (settingName == "my_string_value")
336 /// m_myStringValue = settingValue.GetString();
337 /// else if (settingName == "my_integer_value")
338 /// m_myIntegerValue = settingValue.GetInt();
339 /// else if (settingName == "my_boolean_value")
340 /// m_myBooleanValue = settingValue.GetBoolean();
341 /// else if (settingName == "my_float_value")
342 /// m_myFloatingPointValue = settingValue.GetFloat();
343 /// else if (settingName == "my_enum_value")
344 /// m_myEnumValue = settingValue.GetEnum<myEnumValue>();
345 /// }
346 /// ~~~~~~~~~~~~~
347 ///
348 /// @note The asked type should match the type used on settings.xml.
349 ///
350 virtual ADDON_STATUS SetSetting(const std::string& settingName,
351 const kodi::CSettingValue& settingValue)
352 {
353 return ADDON_STATUS_UNKNOWN;
354 }
355 //----------------------------------------------------------------------------
356
357 //==========================================================================
358 /// @ingroup cpp_kodi_addon_addonbase
359 /// @brief Instance created
360 ///
361 /// @param[in] instanceType The requested type of required instance, see \ref ADDON_TYPE.
362 /// @param[in] instanceID An individual identification key string given by Kodi.
363 /// @param[in] instance The instance handler used by Kodi must be passed to
364 /// the classes created here. See in the example.
365 /// @param[in] version The from Kodi used version of instance. This can be
366 /// used to allow compatibility to older versions of
367 /// them. Further is this given to the parent instance
368 /// that it can handle differences.
369 /// @param[out] addonInstance The pointer to instance class created in addon.
370 /// Needed to be able to identify them on calls.
371 /// @return \ref ADDON_STATUS_OK if correct, for possible errors
372 /// see \ref ADDON_STATUS
373 ///
374 ///
375 /// --------------------------------------------------------------------------
376 ///
377 /// **Here is a code example how this is used:**
378 ///
379 /// ~~~~~~~~~~~~~{.cpp}
380 /// #include <kodi/AddonBase.h>
381 ///
382 /// ...
383 ///
384 /// /* If you use only one instance in your add-on, can be instanceType and
385 /// * instanceID ignored */
386 /// ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
387 /// const std::string& instanceID,
388 /// KODI_HANDLE instance,
389 /// const std::string& version,
390 /// KODI_HANDLE& addonInstance)
391 /// {
392 /// if (instanceType == ADDON_INSTANCE_SCREENSAVER)
393 /// {
394 /// kodi::Log(ADDON_LOG_NOTICE, "Creating my Screensaver");
395 /// addonInstance = new CMyScreensaver(instance);
396 /// return ADDON_STATUS_OK;
397 /// }
398 /// else if (instanceType == ADDON_INSTANCE_VISUALIZATION)
399 /// {
400 /// kodi::Log(ADDON_LOG_NOTICE, "Creating my Visualization");
401 /// addonInstance = new CMyVisualization(instance);
402 /// return ADDON_STATUS_OK;
403 /// }
404 /// else if (...)
405 /// {
406 /// ...
407 /// }
408 /// return ADDON_STATUS_UNKNOWN;
409 /// }
410 ///
411 /// ...
412 ///
413 /// ~~~~~~~~~~~~~
414 ///
415 virtual ADDON_STATUS CreateInstance(int instanceType,
416 const std::string& instanceID,
417 KODI_HANDLE instance,
418 const std::string& version,
419 KODI_HANDLE& addonInstance)
420 {
421 return ADDON_STATUS_NOT_IMPLEMENTED;
422 }
423 //--------------------------------------------------------------------------
424
425 //==========================================================================
426 /// @ingroup cpp_kodi_addon_addonbase
427 /// @brief Instance destroy
428 ///
429 /// This function is optional and intended to notify addon that the instance
430 /// is terminating.
431 ///
432 /// @param[in] instanceType The requested type of required instance, see \ref ADDON_TYPE.
433 /// @param[in] instanceID An individual identification key string given by Kodi.
434 /// @param[in] addonInstance The pointer to instance class created in addon.
435 ///
436 /// @warning This call is only used to inform that the associated instance
437 /// is terminated. The deletion is carried out in the background.
438 ///
439 virtual void DestroyInstance(int instanceType,
440 const std::string& instanceID,
441 KODI_HANDLE addonInstance)
442 {
443 }
444 //--------------------------------------------------------------------------
445
446 /* Background helper for GUI render systems, e.g. Screensaver or Visualization */
447 std::shared_ptr<kodi::gui::IRenderHelper> m_renderHelper;
448
449 /* Global variables of class */
450 static AddonGlobalInterface*
451 m_interface; // Interface function table to hold addresses on add-on and from kodi
452
453 /*private:*/ /* Needed public as long the old call functions becomes used! */
454 static inline void ADDONBASE_Destroy()
455 {
456 delete static_cast<CAddonBase*>(m_interface->addonBase);
457 m_interface->addonBase = nullptr;
458 }
459
460 static inline ADDON_STATUS ADDONBASE_GetStatus()
461 {
462 return static_cast<CAddonBase*>(m_interface->addonBase)->GetStatus();
463 }
464
465 static inline ADDON_STATUS ADDONBASE_SetSetting(const char* settingName, const void* settingValue)
466 {
467 return static_cast<CAddonBase*>(m_interface->addonBase)
468 ->SetSetting(settingName, CSettingValue(settingValue));
469 }
470
471private:
472 static inline ADDON_STATUS ADDONBASE_CreateInstance(int instanceType,
473 const char* instanceID,
474 KODI_HANDLE instance,
475 const char* version,
476 KODI_HANDLE* addonInstance,
477 KODI_HANDLE parent)
478 {
479 CAddonBase* base = static_cast<CAddonBase*>(m_interface->addonBase);
480
481 ADDON_STATUS status = ADDON_STATUS_NOT_IMPLEMENTED;
482
483 /* Check about single instance usage:
484 * 1. The kodi side instance pointer must be equal to first one
485 * 2. The addon side instance pointer must be set
486 * 3. And the requested type must be equal with used add-on class
487 */
488 if (m_interface->firstKodiInstance == instance && m_interface->globalSingleInstance &&
489 static_cast<IAddonInstance*>(m_interface->globalSingleInstance)->m_type == instanceType)
490 {
491 /* The handling here is intended for the case of the add-on only one
492 * instance and this is integrated in the add-on base class.
493 */
494 *addonInstance = m_interface->globalSingleInstance;
495 status = ADDON_STATUS_OK;
496 }
497 else
498 {
499 /* Here it should use the CreateInstance instance function to allow
500 * creation of several on one addon.
501 */
502
503 /* Check first a parent is defined about (e.g. Codec within inputstream) */
504 if (parent != nullptr)
505 status = static_cast<IAddonInstance*>(parent)->CreateInstance(
506 instanceType, instanceID, instance, version, *addonInstance);
507
508 /* if no parent call the main instance creation function to get it */
509 if (status == ADDON_STATUS_NOT_IMPLEMENTED)
510 {
511 status = base->CreateInstance(instanceType, instanceID, instance, version, *addonInstance);
512 }
513 }
514
515 if (*addonInstance == nullptr)
516 {
517 if (status == ADDON_STATUS_OK)
518 {
519 m_interface->toKodi->addon_log_msg(m_interface->toKodi->kodiBase, ADDON_LOG_FATAL,
520 "kodi::addon::CAddonBase CreateInstance returned an "
521 "empty instance pointer, but reported OK!");
522 return ADDON_STATUS_PERMANENT_FAILURE;
523 }
524 else
525 {
526 return status;
527 }
528 }
529
530 if (static_cast<IAddonInstance*>(*addonInstance)->m_type != instanceType)
531 {
532 m_interface->toKodi->addon_log_msg(
533 m_interface->toKodi->kodiBase, ADDON_LOG_FATAL,
534 "kodi::addon::CAddonBase CreateInstance difference between given and returned");
535 delete static_cast<IAddonInstance*>(*addonInstance);
536 *addonInstance = nullptr;
537 return ADDON_STATUS_PERMANENT_FAILURE;
538 }
539
540 // Store the used ID inside instance, to have on destroy calls by addon to identify
541 static_cast<IAddonInstance*>(*addonInstance)->m_id = instanceID;
542
543 return status;
544 }
545
546 static inline void ADDONBASE_DestroyInstance(int instanceType, KODI_HANDLE instance)
547 {
548 CAddonBase* base = static_cast<CAddonBase*>(m_interface->addonBase);
549
550 if (m_interface->globalSingleInstance == nullptr && instance != base)
551 {
552 base->DestroyInstance(instanceType, static_cast<IAddonInstance*>(instance)->m_id, instance);
553 delete static_cast<IAddonInstance*>(instance);
554 }
555 }
556};
557
558} /* namespace addon */
559
560//==============================================================================
561/// @ingroup cpp_kodi_addon
562/// @brief To get used version inside Kodi itself about asked type.
563///
564/// This thought to allow a addon a handling of newer addon versions within
565/// older Kodi until the type min version not changed.
566///
567/// @param[in] type The wanted type of @ref ADDON_TYPE to ask
568/// @return The version string about type in MAJOR.MINOR.PATCH style.
569///
570inline std::string ATTRIBUTE_HIDDEN GetKodiTypeVersion(int type)
571{
572 using namespace kodi::addon;
573
574 char* str = CAddonBase::m_interface->toKodi->get_type_version(
575 CAddonBase::m_interface->toKodi->kodiBase, type);
576 std::string ret = str;
577 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, str);
578 return ret;
579}
580//------------------------------------------------------------------------------
581
582//==============================================================================
583///
584inline std::string ATTRIBUTE_HIDDEN GetAddonPath(const std::string& append = "")
585{
586 using namespace kodi::addon;
587
588 char* str =
589 CAddonBase::m_interface->toKodi->get_addon_path(CAddonBase::m_interface->toKodi->kodiBase);
590 std::string ret = str;
591 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, str);
592 if (!append.empty())
593 {
594 if (append.at(0) != '\\' && append.at(0) != '/')
595#ifdef TARGET_WINDOWS
596 ret.append("\\");
597#else
598 ret.append("/");
599#endif
600 ret.append(append);
601 }
602 return ret;
603}
604//------------------------------------------------------------------------------
605
606//==============================================================================
607///
608inline std::string ATTRIBUTE_HIDDEN GetBaseUserPath(const std::string& append = "")
609{
610 using namespace kodi::addon;
611
612 char* str = CAddonBase::m_interface->toKodi->get_base_user_path(
613 CAddonBase::m_interface->toKodi->kodiBase);
614 std::string ret = str;
615 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, str);
616 if (!append.empty())
617 {
618 if (append.at(0) != '\\' && append.at(0) != '/')
619#ifdef TARGET_WINDOWS
620 ret.append("\\");
621#else
622 ret.append("/");
623#endif
624 ret.append(append);
625 }
626 return ret;
627}
628//------------------------------------------------------------------------------
629
630//==============================================================================
631///
632inline std::string ATTRIBUTE_HIDDEN GetLibPath()
633{
634 using namespace kodi::addon;
635
636 return CAddonBase::m_interface->libBasePath;
637}
638//------------------------------------------------------------------------------
639
640//==============================================================================
641/// @ingroup cpp_kodi
642/// @brief Add a message to Kodi's log.
643///
644/// @param[in] loglevel The log level of the message.
645/// @param[in] format The format of the message to pass to Kodi.
646/// @param[in] ... Additional text to insert in format text
647///
648///
649/// @note This method uses limited buffer (16k) for the formatted output.
650/// So data, which will not fit into it, will be silently discarded.
651///
652///
653/// ----------------------------------------------------------------------------
654///
655/// **Example:**
656/// ~~~~~~~~~~~~~{.cpp}
657/// #include <kodi/General.h>
658///
659/// kodi::Log(ADDON_LOG_ERROR, "%s: There is an error occurred!", __func__);
660///
661/// ~~~~~~~~~~~~~
662///
663inline void ATTRIBUTE_HIDDEN Log(const AddonLog loglevel, const char* format, ...)
664{
665 using namespace kodi::addon;
666
667 char buffer[16384];
668 va_list args;
669 va_start(args, format);
670 vsnprintf(buffer, sizeof(buffer), format, args);
671 va_end(args);
672 CAddonBase::m_interface->toKodi->addon_log_msg(CAddonBase::m_interface->toKodi->kodiBase,
673 loglevel, buffer);
674}
675//------------------------------------------------------------------------------
676
677//##############################################################################
678/// @ingroup cpp_kodi
679/// @defgroup cpp_kodi_settings 1. Setting control
680/// @brief **Functions to handle settings access**\n
681/// This can be used to get and set the addon related values inside his
682/// settings.xml.
683///
684/// The settings style is given with installed part on e.g.
685/// <b>`$HOME/.kodi/addons/myspecial.addon/resources/settings.xml`</b>. The
686/// related edit becomes then stored inside
687/// <b>`$HOME/.kodi/userdata/addon_data/myspecial.addon/settings.xml`</b>.
688///
689/*!@{*/
690
691//==============================================================================
692/// @brief Check the given setting name is set to default value.
693///
694/// The setting name relate to names used in his <b>settings.xml</b> file.
695///
696/// @param[in] settingName The name of asked setting
697/// @return true if setting is the default
698///
699inline bool ATTRIBUTE_HIDDEN IsSettingUsingDefault(const std::string& settingName)
700{
701 using namespace kodi::addon;
702 return CAddonBase::m_interface->toKodi->is_setting_using_default(
703 CAddonBase::m_interface->toKodi->kodiBase, settingName.c_str());
704}
705//------------------------------------------------------------------------------
706
707//==============================================================================
708/// @brief Check and get a string setting value.
709///
710/// The setting name relate to names used in his <b>settings.xml</b> file.
711///
712/// @param[in] settingName The name of asked setting
713/// @param[out] settingValue The given setting value
714/// @return true if setting was successfully found and "settingValue" is set
715///
716/// @note If returns false, the "settingValue" is not changed.
717///
718///
719/// ----------------------------------------------------------------------------
720///
721/// **Example:**
722/// ~~~~~~~~~~~~~{.cpp}
723/// #include <kodi/General.h>
724///
725/// std::string value;
726/// if (!kodi::CheckSettingString("my_string_value", value))
727/// value = "my_default_if_setting_not_work";
728/// ~~~~~~~~~~~~~
729///
730inline bool ATTRIBUTE_HIDDEN CheckSettingString(const std::string& settingName,
731 std::string& settingValue)
732{
733 using namespace kodi::addon;
734
735 char* buffer = nullptr;
736 bool ret = CAddonBase::m_interface->toKodi->get_setting_string(
737 CAddonBase::m_interface->toKodi->kodiBase, settingName.c_str(), &buffer);
738 if (buffer)
739 {
740 if (ret)
741 settingValue = buffer;
742 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, buffer);
743 }
744 return ret;
745}
746//------------------------------------------------------------------------------
747
748//==============================================================================
749/// @brief Get string setting value.
750///
751/// The setting name relate to names used in his <b>settings.xml</b> file.
752///
753/// @param[in] settingName The name of asked setting
754/// @param[in] defaultValue [opt] Default value if not found
755/// @return The value of setting, empty if not found;
756///
757///
758/// ----------------------------------------------------------------------------
759///
760/// **Example:**
761/// ~~~~~~~~~~~~~{.cpp}
762/// #include <kodi/General.h>
763///
764/// std::string value = kodi::GetSettingString("my_string_value");
765/// ~~~~~~~~~~~~~
766///
767inline std::string ATTRIBUTE_HIDDEN GetSettingString(const std::string& settingName,
768 const std::string& defaultValue = "")
769{
770 std::string settingValue = defaultValue;
771 CheckSettingString(settingName, settingValue);
772 return settingValue;
773}
774//------------------------------------------------------------------------------
775
776//==============================================================================
777/// @brief Set string setting of addon.
778///
779/// The setting name relate to names used in his <b>settings.xml</b> file.
780///
781/// @param[in] settingName The name of setting
782/// @param[in] settingValue The setting value to write
783///
784///
785/// ----------------------------------------------------------------------------
786///
787/// **Example:**
788/// ~~~~~~~~~~~~~{.cpp}
789/// #include <kodi/General.h>
790///
791/// std::string value = "my_new_name for";
792/// kodi::SetSettingString("my_string_value", value);
793/// ~~~~~~~~~~~~~
794///
795inline void ATTRIBUTE_HIDDEN SetSettingString(const std::string& settingName,
796 const std::string& settingValue)
797{
798 using namespace kodi::addon;
799
800 CAddonBase::m_interface->toKodi->set_setting_string(CAddonBase::m_interface->toKodi->kodiBase,
801 settingName.c_str(), settingValue.c_str());
802}
803//------------------------------------------------------------------------------
804
805//==============================================================================
806/// @brief Check and get a integer setting value.
807///
808/// The setting name relate to names used in his <b>settings.xml</b> file.
809///
810/// @param[in] settingName The name of asked setting
811/// @param[out] settingValue The given setting value
812/// @return true if setting was successfully found and "settingValue" is set
813///
814/// @note If returns false, the "settingValue" is not changed.
815///
816///
817/// ----------------------------------------------------------------------------
818///
819/// **Example:**
820/// ~~~~~~~~~~~~~{.cpp}
821/// #include <kodi/General.h>
822///
823/// int value = 0;
824/// if (!kodi::CheckSettingInt("my_integer_value", value))
825/// value = 123; // My default of them
826/// ~~~~~~~~~~~~~
827///
828inline bool ATTRIBUTE_HIDDEN CheckSettingInt(const std::string& settingName, int& settingValue)
829{
830 using namespace kodi::addon;
831
832 return CAddonBase::m_interface->toKodi->get_setting_int(CAddonBase::m_interface->toKodi->kodiBase,
833 settingName.c_str(), &settingValue);
834}
835//------------------------------------------------------------------------------
836
837//==============================================================================
838/// @brief Get integer setting value.
839///
840/// The setting name relate to names used in his <b>settings.xml</b> file.
841///
842/// @param[in] settingName The name of asked setting
843/// @param[in] defaultValue [opt] Default value if not found
844/// @return The value of setting, <b>`0`</b> or defaultValue if not found
845///
846///
847/// ----------------------------------------------------------------------------
848///
849/// **Example:**
850/// ~~~~~~~~~~~~~{.cpp}
851/// #include <kodi/General.h>
852///
853/// int value = kodi::GetSettingInt("my_integer_value");
854/// ~~~~~~~~~~~~~
855///
856inline int ATTRIBUTE_HIDDEN GetSettingInt(const std::string& settingName, int defaultValue = 0)
857{
858 int settingValue = defaultValue;
859 CheckSettingInt(settingName, settingValue);
860 return settingValue;
861}
862//------------------------------------------------------------------------------
863
864//==============================================================================
865/// @brief Set integer setting of addon.
866///
867/// The setting name relate to names used in his <b>settings.xml</b> file.
868///
869/// @param[in] settingName The name of setting
870/// @param[in] settingValue The setting value to write
871///
872///
873/// ----------------------------------------------------------------------------
874///
875/// **Example:**
876/// ~~~~~~~~~~~~~{.cpp}
877/// #include <kodi/General.h>
878///
879/// int value = 123;
880/// kodi::SetSettingInt("my_integer_value", value);
881/// ~~~~~~~~~~~~~
882///
883inline void ATTRIBUTE_HIDDEN SetSettingInt(const std::string& settingName, int settingValue)
884{
885 using namespace kodi::addon;
886
887 CAddonBase::m_interface->toKodi->set_setting_int(CAddonBase::m_interface->toKodi->kodiBase,
888 settingName.c_str(), settingValue);
889}
890//------------------------------------------------------------------------------
891
892//==============================================================================
893/// @brief Check and get a boolean setting value.
894///
895/// The setting name relate to names used in his <b>settings.xml</b> file.
896///
897/// @param[in] settingName The name of asked setting
898/// @param[out] settingValue The given setting value
899/// @return true if setting was successfully found and "settingValue" is set
900///
901/// @note If returns false, the "settingValue" is not changed.
902///
903///
904/// ----------------------------------------------------------------------------
905///
906/// **Example:**
907/// ~~~~~~~~~~~~~{.cpp}
908/// #include <kodi/General.h>
909///
910/// bool value = false;
911/// if (!kodi::CheckSettingBoolean("my_boolean_value", value))
912/// value = true; // My default of them
913/// ~~~~~~~~~~~~~
914///
915inline bool ATTRIBUTE_HIDDEN CheckSettingBoolean(const std::string& settingName, bool& settingValue)
916{
917 using namespace kodi::addon;
918
919 return CAddonBase::m_interface->toKodi->get_setting_bool(
920 CAddonBase::m_interface->toKodi->kodiBase, settingName.c_str(), &settingValue);
921}
922//------------------------------------------------------------------------------
923
924//==============================================================================
925/// @brief Get boolean setting value.
926///
927/// The setting name relate to names used in his <b>settings.xml</b> file.
928///
929/// @param[in] settingName The name of asked setting
930/// @param[in] defaultValue [opt] Default value if not found
931/// @return The value of setting, <b>`false`</b> or defaultValue if not found
932///
933///
934/// ----------------------------------------------------------------------------
935///
936/// **Example:**
937/// ~~~~~~~~~~~~~{.cpp}
938/// #include <kodi/General.h>
939///
940/// bool value = kodi::GetSettingBoolean("my_boolean_value");
941/// ~~~~~~~~~~~~~
942///
943inline bool ATTRIBUTE_HIDDEN GetSettingBoolean(const std::string& settingName,
944 bool defaultValue = false)
945{
946 bool settingValue = defaultValue;
947 CheckSettingBoolean(settingName, settingValue);
948 return settingValue;
949}
950//------------------------------------------------------------------------------
951
952//==============================================================================
953/// @brief Set boolean setting of addon.
954///
955/// The setting name relate to names used in his <b>settings.xml</b> file.
956///
957/// @param[in] settingName The name of setting
958/// @param[in] settingValue The setting value to write
959///
960///
961/// ----------------------------------------------------------------------------
962///
963/// **Example:**
964/// ~~~~~~~~~~~~~{.cpp}
965/// #include <kodi/General.h>
966///
967/// bool value = true;
968/// kodi::SetSettingBoolean("my_boolean_value", value);
969/// ~~~~~~~~~~~~~
970///
971inline void ATTRIBUTE_HIDDEN SetSettingBoolean(const std::string& settingName, bool settingValue)
972{
973 using namespace kodi::addon;
974
975 CAddonBase::m_interface->toKodi->set_setting_bool(CAddonBase::m_interface->toKodi->kodiBase,
976 settingName.c_str(), settingValue);
977}
978//------------------------------------------------------------------------------
979
980//==============================================================================
981/// @brief Check and get a floating point setting value.
982///
983/// The setting name relate to names used in his <b>settings.xml</b> file.
984///
985/// @param[in] settingName The name of asked setting
986/// @param[out] settingValue The given setting value
987/// @return true if setting was successfully found and "settingValue" is set
988///
989/// @note If returns false, the "settingValue" is not changed.
990///
991///
992/// ----------------------------------------------------------------------------
993///
994/// **Example:**
995/// ~~~~~~~~~~~~~{.cpp}
996/// #include <kodi/General.h>
997///
998/// float value = 0.0f;
999/// if (!kodi::CheckSettingBoolean("my_float_value", value))
1000/// value = 1.0f; // My default of them
1001/// ~~~~~~~~~~~~~
1002///
1003inline bool ATTRIBUTE_HIDDEN CheckSettingFloat(const std::string& settingName, float& settingValue)
1004{
1005 using namespace kodi::addon;
1006
1007 return CAddonBase::m_interface->toKodi->get_setting_float(
1008 CAddonBase::m_interface->toKodi->kodiBase, settingName.c_str(), &settingValue);
1009}
1010//------------------------------------------------------------------------------
1011
1012//==============================================================================
1013/// @brief Get floating point setting value.
1014///
1015/// The setting name relate to names used in his <b>settings.xml</b> file.
1016///
1017/// @param[in] settingName The name of asked setting
1018/// @param[in] defaultValue [opt] Default value if not found
1019/// @return The value of setting, <b>`0.0`</b> or defaultValue if not found
1020///
1021///
1022/// ----------------------------------------------------------------------------
1023///
1024/// **Example:**
1025/// ~~~~~~~~~~~~~{.cpp}
1026/// #include <kodi/General.h>
1027///
1028/// float value = kodi::GetSettingFloat("my_float_value");
1029/// ~~~~~~~~~~~~~
1030///
1031inline float ATTRIBUTE_HIDDEN GetSettingFloat(const std::string& settingName,
1032 float defaultValue = 0.0f)
1033{
1034 float settingValue = defaultValue;
1035 CheckSettingFloat(settingName, settingValue);
1036 return settingValue;
1037}
1038//------------------------------------------------------------------------------
1039
1040//==============================================================================
1041/// @brief Set floating point setting of addon.
1042///
1043/// The setting name relate to names used in his <b>settings.xml</b> file.
1044///
1045/// @param[in] settingName The name of setting
1046/// @param[in] settingValue The setting value to write
1047///
1048///
1049/// ----------------------------------------------------------------------------
1050///
1051/// **Example:**
1052/// ~~~~~~~~~~~~~{.cpp}
1053/// #include <kodi/General.h>
1054///
1055/// float value = 1.0f;
1056/// kodi::SetSettingFloat("my_float_value", value);
1057/// ~~~~~~~~~~~~~
1058///
1059inline void ATTRIBUTE_HIDDEN SetSettingFloat(const std::string& settingName, float settingValue)
1060{
1061 using namespace kodi::addon;
1062
1063 CAddonBase::m_interface->toKodi->set_setting_float(CAddonBase::m_interface->toKodi->kodiBase,
1064 settingName.c_str(), settingValue);
1065}
1066//------------------------------------------------------------------------------
1067
1068//==============================================================================
1069/// @brief Check and get a enum setting value.
1070///
1071/// The setting name relate to names used in his <b>settings.xml</b> file.
1072///
1073/// @param[in] settingName The name of asked setting
1074/// @param[out] settingValue The given setting value
1075/// @return true if setting was successfully found and "settingValue" is set
1076///
1077/// @remark The enums are used as integer inside settings.xml.
1078/// @note If returns false, the "settingValue" is not changed.
1079///
1080///
1081/// ----------------------------------------------------------------------------
1082///
1083/// **Example:**
1084/// ~~~~~~~~~~~~~{.cpp}
1085/// #include <kodi/General.h>
1086///
1087/// enum myEnumValue
1088/// {
1089/// valueA,
1090/// valueB,
1091/// valueC
1092/// };
1093///
1094/// myEnumValue value;
1095/// if (!kodi::CheckSettingEnum<myEnumValue>("my_enum_value", value))
1096/// value = valueA; // My default of them
1097/// ~~~~~~~~~~~~~
1098///
1099template<typename enumType>
1100inline bool ATTRIBUTE_HIDDEN CheckSettingEnum(const std::string& settingName,
1101 enumType& settingValue)
1102{
1103 using namespace kodi::addon;
1104
1105 int settingValueInt = static_cast<int>(settingValue);
1106 bool ret = CAddonBase::m_interface->toKodi->get_setting_int(
1107 CAddonBase::m_interface->toKodi->kodiBase, settingName.c_str(), &settingValueInt);
1108 if (ret)
1109 settingValue = static_cast<enumType>(settingValueInt);
1110 return ret;
1111}
1112//------------------------------------------------------------------------------
1113
1114//==============================================================================
1115/// @brief Get enum setting value.
1116///
1117/// The setting name relate to names used in his <b>settings.xml</b> file.
1118///
1119/// @param[in] settingName The name of asked setting
1120/// @param[in] defaultValue [opt] Default value if not found
1121/// @return The value of setting, forced to <b>`0`</b> or defaultValue if not found
1122///
1123/// @remark The enums are used as integer inside settings.xml.
1124///
1125///
1126/// ----------------------------------------------------------------------------
1127///
1128/// **Example:**
1129/// ~~~~~~~~~~~~~{.cpp}
1130/// #include <kodi/General.h>
1131///
1132/// enum myEnumValue
1133/// {
1134/// valueA,
1135/// valueB,
1136/// valueC
1137/// };
1138///
1139/// myEnumValue value = kodi::GetSettingEnum<myEnumValue>("my_enum_value");
1140/// ~~~~~~~~~~~~~
1141///
1142template<typename enumType>
1143inline enumType ATTRIBUTE_HIDDEN GetSettingEnum(const std::string& settingName,
1144 enumType defaultValue = static_cast<enumType>(0))
1145{
1146 enumType settingValue = defaultValue;
1147 CheckSettingEnum(settingName, settingValue);
1148 return settingValue;
1149}
1150//------------------------------------------------------------------------------
1151
1152//==============================================================================
1153/// @brief Set enum setting of addon.
1154///
1155/// The setting name relate to names used in his <b>settings.xml</b> file.
1156///
1157/// @param[in] settingName The name of setting
1158/// @param[in] settingValue The setting value to write
1159///
1160/// @remark The enums are used as integer inside settings.xml.
1161///
1162///
1163/// ----------------------------------------------------------------------------
1164///
1165/// **Example:**
1166/// ~~~~~~~~~~~~~{.cpp}
1167/// #include <kodi/General.h>
1168///
1169/// enum myEnumValue
1170/// {
1171/// valueA,
1172/// valueB,
1173/// valueC
1174/// };
1175///
1176/// myEnumValue value = valueA;
1177/// kodi::SetSettingEnum<myEnumValue>("my_enum_value", value);
1178/// ~~~~~~~~~~~~~
1179///
1180template<typename enumType>
1181inline void ATTRIBUTE_HIDDEN SetSettingEnum(const std::string& settingName, enumType settingValue)
1182{
1183 using namespace kodi::addon;
1184
1185 CAddonBase::m_interface->toKodi->set_setting_int(CAddonBase::m_interface->toKodi->kodiBase,
1186 settingName.c_str(),
1187 static_cast<int>(settingValue));
1188}
1189//------------------------------------------------------------------------------
1190
1191/*!@}*/
1192
1193//============================================================================
1194///
1195inline std::string ATTRIBUTE_HIDDEN TranslateAddonStatus(ADDON_STATUS status)
1196{
1197 switch (status)
1198 {
1199 case ADDON_STATUS_OK:
1200 return "OK";
1201 case ADDON_STATUS_LOST_CONNECTION:
1202 return "Lost Connection";
1203 case ADDON_STATUS_NEED_RESTART:
1204 return "Need Restart";
1205 case ADDON_STATUS_NEED_SETTINGS:
1206 return "Need Settings";
1207 case ADDON_STATUS_UNKNOWN:
1208 return "Unknown error";
1209 case ADDON_STATUS_PERMANENT_FAILURE:
1210 return "Permanent failure";
1211 case ADDON_STATUS_NOT_IMPLEMENTED:
1212 return "Not implemented";
1213 default:
1214 break;
1215 }
1216 return "Unknown";
1217}
1218//----------------------------------------------------------------------------
1219
1220//==============================================================================
1221/// @ingroup cpp_kodi
1222/// @brief Returns a function table to a named interface
1223///
1224/// @return pointer to struct containing interface functions
1225///
1226///
1227/// ------------------------------------------------------------------------
1228///
1229/// **Example:**
1230/// ~~~~~~~~~~~~~{.cpp}
1231/// #include <kodi/General.h>
1232/// #include <kodi/platform/foo.h>
1233/// ...
1234/// FuncTable_foo *table = kodi::GetPlatformInfo(foo_name, foo_version);
1235/// ...
1236/// ~~~~~~~~~~~~~
1237///
1238inline void* GetInterface(const std::string& name, const std::string& version)
1239{
1240 using namespace kodi::addon;
1241
1242 AddonToKodiFuncTable_Addon* toKodi = CAddonBase::m_interface->toKodi;
1243
1244 return toKodi->get_interface(toKodi->kodiBase, name.c_str(), version.c_str());
1245}
1246//----------------------------------------------------------------------------
1247
1248} /* namespace kodi */
1249
1250/*! addon creation macro
1251 * @todo cleanup this stupid big macro
1252 * This macro includes now all for add-on's needed functions. This becomes a bigger
1253 * rework after everything is done on Kodi itself, currently is this way needed
1254 * to have compatibility with not reworked interfaces.
1255 *
1256 * Becomes really cleaned up soon :D
1257 */
1258#define ADDONCREATOR(AddonClass) \
1259 extern "C" __declspec(dllexport) ADDON_STATUS ADDON_Create( \
1260 KODI_HANDLE addonInterface, const char* /*globalApiVersion*/, void* /*unused*/) \
1261 { \
1262 kodi::addon::CAddonBase::m_interface = static_cast<AddonGlobalInterface*>(addonInterface); \
1263 kodi::addon::CAddonBase::m_interface->addonBase = new AddonClass; \
1264 return static_cast<kodi::addon::CAddonBase*>(kodi::addon::CAddonBase::m_interface->addonBase) \
1265 ->Create(); \
1266 } \
1267 extern "C" __declspec(dllexport) void ADDON_Destroy() \
1268 { \
1269 kodi::addon::CAddonBase::ADDONBASE_Destroy(); \
1270 } \
1271 extern "C" __declspec(dllexport) ADDON_STATUS ADDON_GetStatus() \
1272 { \
1273 return kodi::addon::CAddonBase::ADDONBASE_GetStatus(); \
1274 } \
1275 extern "C" __declspec(dllexport) ADDON_STATUS ADDON_SetSetting(const char* settingName, \
1276 const void* settingValue) \
1277 { \
1278 return kodi::addon::CAddonBase::ADDONBASE_SetSetting(settingName, settingValue); \
1279 } \
1280 extern "C" __declspec(dllexport) const char* ADDON_GetTypeVersion(int type) \
1281 { \
1282 return kodi::addon::GetTypeVersion(type); \
1283 } \
1284 extern "C" __declspec(dllexport) const char* ADDON_GetTypeMinVersion(int type) \
1285 { \
1286 return kodi::addon::GetTypeMinVersion(type); \
1287 } \
1288 AddonGlobalInterface* kodi::addon::CAddonBase::m_interface = nullptr;
generated by cgit v1.2.3 (git 2.25.1) at 2026-01-12 15:49:49 +0000