1 #ifndef DALI_INTEGRATION_ADDON_MANAGER_H
2 #define DALI_INTEGRATION_ADDON_MANAGER_H
5 * Copyright (c) 2020 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/public-api/object/base-handle.h>
33 // Type of extensions (may be used internally)
41 * @brief Helper function building the version number as 32-bit integer.
42 * The return value should be used to encode AddOnInfo::version field.
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
49 constexpr uint32_t DALI_ADDON_VERSION(uint32_t maj, uint32_t min, uint32_t rev)
51 return ((maj & 0xff) << 24) | ((min & 0xfff) << 16);
55 * Structure describes AddOn details
59 AddOnType type; /// may be use in order to classify extension
60 void* next; /// holds pointer to additional data-structures
62 std::string name; /// Name of the extension
66 * Structure contains details of build
70 uint32_t libCoreVersion;
71 uint32_t libAdaptorVersion;
72 uint32_t libToolkitVersion;
77 * The structure contains essential function pointers which AddOnManager
78 * requires in order to use AddOns.
80 struct AddOnDispatchTable
83 void (*GetAddOnInfo)(Dali::AddOnInfo&) = nullptr;
84 void* (*GetGlobalProc)(const char*) = nullptr;
85 void* (*GetInstanceProc)(const char*) = nullptr;
87 // Lifecycle callbacks
88 void (*OnStart)() = nullptr;
89 void (*OnResume)() = nullptr;
90 void (*OnPause)() = nullptr;
91 void (*OnStop)() = nullptr;
95 * The AddOnLibrary type represents fully opaque object which hides
96 * the actual handle to the library and other related data.
98 typedef void* AddOnLibrary;
100 namespace Integration
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:
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
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.
115 class DALI_CORE_API AddOnManager
119 * @brief Constructor, initialised by the Adaptor
127 virtual ~AddOnManager();
129 // Functions called by the application
132 * @brief Retrieves list of the available AddOns
133 * @return List of AddOn names
135 virtual std::vector<std::string> EnumerateAddOns() = 0;
138 * @brief Returns AddOnInfo structure for specified AddOn name
139 * @param[in] name Name of AddOn
140 * @param[out]] info Output reference
141 * @return True on success, False if extension info cannot be retrieved
143 virtual bool GetAddOnInfo(const std::string& name, AddOnInfo& info) = 0;
146 * @brief Loads and initialises specified extensions
147 * @param[in] extensionNames Array of extension names
148 * @return vector of initialised extension handles
150 virtual std::vector<AddOnLibrary> LoadAddOns(const std::vector<std::string>& addonNames) = 0;
153 * @brief Loads AddOn with specified name
154 * @param[in] addOnName Name of AddOn to be acquired
155 * @return Returns a valid handle or nullptr
157 inline AddOnLibrary GetAddOn(const std::string& addonName)
159 return LoadAddOns({addonName})[0];
163 * @brief Returns AddOn global function pointer
164 * @param[in] addOnLibrary valid AddOn library object
165 * @param[in] procName Name of the function to retrieve
166 * @return Pointer to the function or null if function doesn't exist
168 virtual void* GetGlobalProc(const Dali::AddOnLibrary& addOnLibrary, const char* procName) = 0;
171 * @brief Returns addon instance function pointer
172 * @param[in] addOnLibrary valid AddOn library object
173 * @param[in] procName Name of the function to retrieve
174 * @return Pointer to the function or null if function doesn't exist
176 virtual void* GetInstanceProc(const Dali::AddOnLibrary& addOnLibrary, const char* procName) = 0;
179 * @brief Returns addon global function of specified type
180 * @param[in] addOnLibrary valid AddOn library object
181 * @param[in] procName Name of the function to retrieve
182 * @return std::function object or null if function doesn't exist
185 DALI_INTERNAL std::function<T> GetGlobalProc(const Dali::AddOnLibrary& addonlibrary, const char* procName)
187 auto ptr = GetGlobalProc(addonlibrary, procName);
190 return std::function<T>(*reinterpret_cast<T**>(&ptr));
196 * @brief Returns AddOn instance function of specified type
197 * @param[in] addOnLibrary valid AddOn library object
198 * @param[in] procName Name of the function to retrieve
199 * @return std::function object or null if function doesn't exist
202 DALI_INTERNAL std::function<T> GetInstanceProc(const Dali::AddOnLibrary& addOnLibrary, const char* procName)
204 auto ptr = GetInstanceProc(addOnLibrary, procName);
207 return std::function<T>(*reinterpret_cast<T**>(&ptr));
213 * @brief Invokes global function by name
214 * @param[in] addOnLibrary valid AddOn library object
215 * @param[in] functionName Name of function to be called
216 * @param args[in] Arguments
217 * @return Result of called function
219 template<class R, class... Args>
220 DALI_INTERNAL R InvokeGlobalProc(AddOnLibrary addOnLibrary, const char* functionName, Args&&... args)
222 return std::move(GetGlobalProc<R(Args...)>(addOnLibrary, functionName)(args...));
225 // Lifecycle events, functions are called by the Adaptor
228 * @brief Lifecycle pause function
230 virtual void Pause() = 0;
233 * @brief Lifecycle resume function
235 virtual void Resume() = 0;
238 * @brief Lifecycle start function
240 virtual void Start() = 0;
243 * @brief Lifecycle stop function
245 virtual void Stop() = 0;
247 // Functions called by the AddOn
250 * @brief Registers the dispatch table with AddOnManager.
252 * The function must be called by the AddOn in order to self-register and add
253 * the dispatch table. The platform-dependent implementation must override it
254 * in order to store the dispatch table. The way the dispatch table is stored
255 * depends on the implementation.
257 * @param[in] dispatchTable Pointer to the valid dispatch table
259 virtual void RegisterAddOnDispatchTable(const AddOnDispatchTable* dispatchTable) = 0;
262 * @brief Retrieves AddOnManager singleton
263 * @return pointer to the AddOnManager
265 static AddOnManager* Get();
268 static AddOnManager* mSingleton; ///< Singleton storing an instance of AddOnManager
270 } // namespace Integration
273 #endif // DALI_INTEGRATION_ADDON_MANAGER