#pragma once
/*
* Copyright (C) 2005-2017 Team Kodi
* http://kodi.tv
*
* This Program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2, or (at your option)
* any later version.
*
* This Program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with Kodi; see the file COPYING. If not, see
* .
*
*/
#include "AddonBase.h"
/*
* For interface between add-on and kodi.
*
* This structure defines the addresses of functions stored inside Kodi which
* are then available for the add-on to call
*
* All function pointers there are used by the C++ interface functions below.
* You find the set of them on xbmc/addons/interfaces/General.cpp
*
* Note: For add-on development itself this is not needed
*/
typedef struct AddonToKodiFuncTable_kodi
{
bool (*open_settings_dialog)(void* kodiBase);
char* (*unknown_to_utf8)(void* kodiBase, const char* source, bool* ret, bool failOnBadChar);
char* (*get_localized_string)(void* kodiBase, long dwCode);
char* (*get_language)(void* kodiBase, int format, bool region);
bool (*queue_notification)(void* kodiBase, int type, const char* header, const char* message, const char* imageFile, unsigned int displayTime, bool withSound, unsigned int messageTime);
} AddonToKodiFuncTable_kodi;
//==============================================================================
/// \ingroup cpp_kodi_Defs
/// @brief For kodi::QueueNotification() used message types
///
typedef enum QueueMsg
{
/// Show info notification message
QUEUE_INFO,
/// Show warning notification message
QUEUE_WARNING,
/// Show error notification message
QUEUE_ERROR,
/// Show with own given image and parts if set on values
QUEUE_OWN_STYLE
} QueueMsg;
//------------------------------------------------------------------------------
//==============================================================================
/// \ingroup cpp_kodi_Defs
/// @brief Format codes to get string from them.
///
typedef enum LangFormats
{
/// two letter code as defined in ISO 639-1
LANG_FMT_ISO_639_1,
/// three letter code as defined in ISO 639-2/T or ISO 639-2/B
LANG_FMT_ISO_639_2,
/// full language name in English
LANG_FMT_ENGLISH_NAME
} LangFormats;
//------------------------------------------------------------------------------
//==============================================================================
namespace kodi {
///
/// \ingroup cpp_kodi
/// @brief Opens this Add-Ons settings dialog.
///
/// @return true if settings were changed and the dialog confirmed, false otherwise.
///
///
/// --------------------------------------------------------------------------
///
/// **Example:**
/// ~~~~~~~~~~~~~{.cpp}
/// #include
/// ..
/// kodi::OpenSettings();
/// ..
/// ~~~~~~~~~~~~~
///
inline bool OpenSettings()
{
return ::kodi::addon::CAddonBase::m_interface->toKodi->kodi->open_settings_dialog(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase);
}
} /* namespace kodi */
//------------------------------------------------------------------------------
//==============================================================================
namespace kodi {
///
/// \ingroup cpp_kodi
/// @brief Returns an addon's localized 'unicode string'.
///
/// @param[in] labelId string you want to localize
/// @param[in] defaultStr [opt] The default message, also helps to identify
/// the code that is used (default is
/// empty)
/// @return The localized message, or default if the add-on
/// helper fails to return a message
///
/// @note Label id's \b 30000 to \b 30999 and \b 32000 to \b 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:**
/// ~~~~~~~~~~~~~{.cpp}
/// #include
/// ...
/// std::string str = kodi::GetLocalizedString(30005, "Use me as default");
/// ...
/// ~~~~~~~~~~~~~
///
inline std::string GetLocalizedString(uint32_t labelId, const std::string& defaultStr = "")
{
std::string retString = defaultStr;
char* strMsg = ::kodi::addon::CAddonBase::m_interface->toKodi->kodi->get_localized_string(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase, labelId);
if (strMsg != nullptr)
{
if (std::strlen(strMsg))
retString = strMsg;
::kodi::addon::CAddonBase::m_interface->toKodi->free_string(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase, strMsg);
}
return retString;
}
} /* namespace kodi */
//------------------------------------------------------------------------------
//==============================================================================
namespace kodi {
///
/// \ingroup cpp_kodi
/// @brief Translate a string with an unknown encoding to UTF8.
///
/// @param[in] stringSrc The string to translate.
/// @param[out] utf8StringDst The translated string.
/// @param[in] failOnBadChar [opt] returns failed if bad character is inside (default is false)
/// @return true if OK
///
///
/// ------------------------------------------------------------------------
///
/// **Example:**
/// ~~~~~~~~~~~~~{.cpp}
/// #include
/// ...
/// std::string ret;
/// if (!kodi::UnknownToUTF8("test string", ret, true))
/// fprintf(stderr, "Translation to UTF8 failed!\n");
/// ...
/// ~~~~~~~~~~~~~
///
inline bool UnknownToUTF8(const std::string& stringSrc, std::string& utf8StringDst, bool failOnBadChar = false)
{
bool ret = false;
char* retString = ::kodi::addon::CAddonBase::m_interface->toKodi->kodi->unknown_to_utf8(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase,
stringSrc.c_str(), &ret, failOnBadChar);
if (retString != nullptr)
{
if (ret)
utf8StringDst = retString;
::kodi::addon::CAddonBase::m_interface->toKodi->free_string(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase, retString);
}
return ret;
}
} /* namespace kodi */
//------------------------------------------------------------------------------
//==============================================================================
namespace kodi {
///
/// \ingroup cpp_kodi
/// @brief Returns the active language as a string.
///
/// @param[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 |
/// @param[in] region [opt] append the region delimited by "-" of the language (setting) to the returned language string (default is false)
/// @return active language
///
///
/// ------------------------------------------------------------------------
///
/// **Example:**
/// ~~~~~~~~~~~~~{.cpp}
/// #include
/// ...
/// std::string language = kodi::GetLanguage(LANG_FMT_ISO_639_1, false);
/// ...
/// ~~~~~~~~~~~~~
///
inline std::string GetLanguage(LangFormats format = LANG_FMT_ENGLISH_NAME, bool region = false)
{
std::string language;
char* retString = ::kodi::addon::CAddonBase::m_interface->toKodi->kodi->get_language(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase, format, region);
if (retString != nullptr)
{
if (std::strlen(retString))
language = retString;
::kodi::addon::CAddonBase::m_interface->toKodi->free_string(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase, retString);
}
return language;
}
} /* namespace kodi */
//------------------------------------------------------------------------------
//==============================================================================
namespace kodi {
///
/// \ingroup cpp_kodi
/// @brief 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.
///
/// @param[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 |
/// @param[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.
/// @param[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:**
/// ~~~~~~~~~~~~~{.cpp}
/// #include
/// ...
/// kodi::QueueFormattedNotification(QUEUE_WARNING, "I'm want to inform you, here with a test call to show '%s'", "this");
/// ...
/// ~~~~~~~~~~~~~
///
inline void QueueFormattedNotification(QueueMsg type, const char* format, ... )
{
va_list args;
char buffer[16384];
va_start(args, format);
vsprintf(buffer, format, args);
va_end(args);
::kodi::addon::CAddonBase::m_interface->toKodi->kodi->queue_notification(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase,
type, "", buffer, "", 5000, false, 1000);
}
} /* namespace kodi */
//------------------------------------------------------------------------------
//==============================================================================
namespace kodi {
///
/// \ingroup cpp_kodi
/// @brief Queue a notification in the GUI.
///
/// @param[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
/// @param[in] header Header Name (if leaved empty becomes addon name used)
/// @param[in] message Message to display on Kodi
/// @param[in] imageFile [opt] The image file to show on message (to use must be type set to QUEUE_OWN_STYLE)
/// @param[in] displayTime [opt] The time how long message is displayed (default 5 sec) (to use must be type set to QUEUE_OWN_STYLE)
/// @param[in] withSound [opt] if true also warning sound becomes played (default with sound) (to use must be type set to QUEUE_OWN_STYLE)
/// @param[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:**
/// ~~~~~~~~~~~~~{.cpp}
/// #include
/// ...
/// kodi::QueueNotification(QUEUE_OWN_STYLE, "I'm want to inform you", "Here with a test call", "", 3000, false, 1000);
/// ...
/// ~~~~~~~~~~~~~
///
/// **Example:**
/// ~~~~~~~~~~~~~{.cpp}
/// #include
/// ...
/// kodi::QueueNotification(QUEUE_WARNING, "I'm want to inform you", "Here with a test call");
/// ...
/// ~~~~~~~~~~~~~
///
/// **Example:**
/// ~~~~~~~~~~~~~{.cpp}
/// #include
/// ...
/// kodi::QueueNotification(QUEUE_OWN_STYLE, "", "Here with a test call", "./myImage.png");
/// ...
/// ~~~~~~~~~~~~~
///
inline void 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)
{
::kodi::addon::CAddonBase::m_interface->toKodi->kodi->queue_notification(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase,
type, header.c_str(), message.c_str(), imageFile.c_str(), displayTime,
withSound, messageTime);
}
} /* namespace kodi */
//------------------------------------------------------------------------------