dali/integration-api/addon-manager.h

   1 #ifndef DALI_INTEGRATION_ADDON_MANAGER_H
   2 #define DALI_INTEGRATION_ADDON_MANAGER_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/object/base-handle.h>
  23
  24 // EXTERNAL EXCLUDES
  25 #include <string>
  26 #include <memory>
  27 #include <vector>
  28 #include <functional>
  29 #include <cstdio>
  30
  31 namespace Dali
  32 {
  33 // Type of extensions (may be used internally)
  34 enum class AddOnType
  35 {
  36   GENERIC,
  37   IMAGE_LOADER
  38 };
  39
  40 /**
  41  * @brief Helper function building the version number as 32-bit integer.
  42  * The return value should be used to encode AddOnInfo::version field.
  43  *
  44  * @param[in] maj Major version number
  45  * @param[in] min Minor version number
  46  * @param[in] rev Revision version number
  47  * @return returns 32-bit version number
  48  */
  49 constexpr uint32_t DALI_ADDON_VERSION( uint32_t maj, uint32_t min, uint32_t rev )
  50 {
  51   return ((maj&0xff) << 24) | ((min & 0xfff) << 16);
  52 }
  53
  54 /**
  55  * Structure describes AddOn details
  56  */
  57 struct AddOnInfo
  58 {
  59   AddOnType type;        /// may be use in order to classify extension
  60   void* next;           /// holds pointer to additional data-structures
  61
  62   std::string name;     /// Name of the extension
  63   uint32_t    version;
  64
  65   /**
  66    * Structure contains details of build
  67    */
  68   struct BuildInfo
  69   {
  70     uint32_t libCoreVersion;
  71     uint32_t libAdaptorVersion;
  72     uint32_t libToolkitVersion;
  73   } buildInfo;
  74 };
  75
  76 /**
  77  * The structure contains essential function pointers which AddOnManager
  78  * requires in order to use AddOns.
  79  */
  80 struct AddOnDispatchTable
  81 {
  82   std::string name;
  83   void (*GetAddOnInfo)( Dali::AddOnInfo&) = nullptr;
  84   void*(*GetGlobalProc)(const char*) = nullptr;
  85   void*(*GetInstanceProc)(const char*) = nullptr;
  86
  87   // Lifecycle callbacks
  88   void(*OnStart)() = nullptr;
  89   void(*OnResume)() = nullptr;
  90   void(*OnPause)() = nullptr;
  91   void(*OnStop)() = nullptr;
  92 };
  93
  94 /**
  95  * The AddOnLibrary type represents fully opaque object which hides
  96  * the actual handle to the library and other related data.
  97  */
  98 typedef void* AddOnLibrary;
  99
 100 namespace Integration
 101 {
 102 /**
 103  * AddOnManager class
 104  *
 105  * Handles DALi AddOn support. The object of AddOnManager exists as a singleton and
 106  * is created by the Adaptor. The AddOnManager is used by:
 107  *
 108  * 1) Application - query the AddOns and obtain AddOn interfaces
 109  * 2) DALi - handling lifecycle events
 110  * 3) AddOn - self-registering the AddOn dispatch table
 111  *
 112  * It is up to the implementation how the AddOn libraries are enumerated and opened. Any
 113  * caching (functions, open libraries) must be handled by the implementation.
 114  */
 115 class DALI_CORE_API AddOnManager
 116 {
 117 protected:
 118   /**
 119    * @brief Constructor, initialised by the Adaptor
 120    */
 121   AddOnManager();
 122
 123 public:
 124
 125   /**
 126    * @brief Destructor
 127    */
 128   virtual ~AddOnManager();
 129
 130   // Functions called by the application
 131 public:
 132   /**
 133    * @brief Retrieves list of the available AddOns
 134    * @return List of AddOn names
 135    */
 136   virtual std::vector<std::string> EnumerateAddOns() = 0;
 137
 138   /**
 139    * @brief Returns AddOnInfo structure for specified AddOn name
 140    * @param[in] name Name of AddOn
 141    * @param[out]] info Output reference
 142    * @return True on success, False if extension info cannot be retrieved
 143    */
 144   virtual bool GetAddOnInfo(const std::string& name, AddOnInfo& info ) = 0;
 145
 146   /**
 147    * @brief Loads and initialises specified extensions
 148    * @param[in] extensionNames Array of extension names
 149    * @return vector of initialised extension handles
 150    */
 151   virtual std::vector<AddOnLibrary> LoadAddOns( const std::vector<std::string>& addonNames ) = 0;
 152
 153   /**
 154    * @brief Loads AddOn with specified name
 155    * @param[in] addOnName Name of AddOn to be acquired
 156    * @return Returns a valid handle or nullptr
 157    */
 158   inline AddOnLibrary GetAddOn( const std::string& addonName )
 159   {
 160     return LoadAddOns( { addonName } )[0];
 161   }
 162
 163   /**
 164    * @brief Returns AddOn global function pointer
 165    * @param[in] addOnLibrary valid AddOn library object
 166    * @param[in] procName Name of the function to retrieve
 167    * @return Pointer to the function or null if function doesn't exist
 168    */
 169   virtual void* GetGlobalProc( const Dali::AddOnLibrary& addOnLibrary, const char* procName ) = 0;
 170
 171   /**
 172    * @brief Returns addon instance function pointer
 173    * @param[in] addOnLibrary valid AddOn library object
 174    * @param[in] procName Name of the function to retrieve
 175    * @return Pointer to the function or null if function doesn't exist
 176    */
 177   virtual void* GetInstanceProc( const Dali::AddOnLibrary& addOnLibrary, const char* procName ) = 0;
 178
 179   /**
 180    * @brief Returns addon global function of specified type
 181    * @param[in] addOnLibrary valid AddOn library object
 182    * @param[in] procName Name of the function to retrieve
 183    * @return std::function object or null if function doesn't exist
 184    */
 185   template<class T>
 186   DALI_INTERNAL std::function<T> GetGlobalProc( const Dali::AddOnLibrary& addonlibrary, const char* procName )
 187   {
 188     auto ptr = GetGlobalProc( addonlibrary, procName );
 189     if( ptr )
 190     {
 191       return std::function<T>( *reinterpret_cast<T**>(&ptr) );
 192     }
 193     return {};
 194   };
 195
 196   /**
 197    * @brief Returns AddOn instance function of specified type
 198    * @param[in] addOnLibrary valid AddOn library object
 199    * @param[in] procName Name of the function to retrieve
 200    * @return std::function object or null if function doesn't exist
 201    */
 202   template<class T>
 203   DALI_INTERNAL std::function<T> GetInstanceProc( const Dali::AddOnLibrary& addOnLibrary, const char* procName )
 204   {
 205     auto ptr = GetInstanceProc( addOnLibrary, procName );
 206     if( ptr )
 207     {
 208       return std::function<T>( *reinterpret_cast<T**>(&ptr) );
 209     }
 210     return {};
 211   };
 212
 213   /**
 214    * @brief Invokes global function by name
 215    * @param[in] addOnLibrary valid AddOn library object
 216    * @param[in] functionName Name of function to be called
 217    * @param args[in] Arguments
 218    * @return Result of called function
 219    */
 220   template<class R, class... Args>
 221   DALI_INTERNAL R InvokeGlobalProc( AddOnLibrary addOnLibrary, const char* functionName, Args&&... args)
 222   {
 223     return std::move(GetGlobalProc<R(Args...)>( addOnLibrary, functionName )( args... ));
 224   }
 225
 226   // Lifecycle events, functions are called by the Adaptor
 227 public:
 228
 229   /**
 230    * @brief Lifecycle pause function
 231    */
 232   virtual void Pause() = 0;
 233
 234   /**
 235    * @brief Lifecycle resume function
 236    */
 237   virtual void Resume() = 0;
 238
 239   /**
 240    * @brief Lifecycle start function
 241    */
 242   virtual void Start() = 0;
 243
 244   /**
 245    * @brief Lifecycle stop function
 246    */
 247   virtual void Stop() = 0;
 248
 249   // Functions called by the AddOn
 250 public:
 251
 252   /**
 253    * @brief Registers the dispatch table with AddOnManager.
 254    *
 255    * The function must be called by the AddOn in order to self-register and add
 256    * the dispatch table. The platform-dependent implementation must override it
 257    * in order to store the dispatch table. The way the dispatch table is stored
 258    * depends on the implementation.
 259    *
 260    * @param[in] dispatchTable Pointer to the valid dispatch table
 261    */
 262   virtual void RegisterAddOnDispatchTable( const AddOnDispatchTable* dispatchTable ) = 0;
 263
 264   /**
 265    * @brief Retrieves AddOnManager singleton
 266    * @return pointer to the AddOnManager
 267    */
 268   static AddOnManager* Get();
 269
 270 protected:
 271
 272   static AddOnManager* mSingleton; ///< Singleton storing an instance of AddOnManager
 273 };
 274 } // namespace Integration
 275 } // namespace Dali
 276
 277 #endif // DALI_INTEGRATION_ADDON_MANAGER