1 /* 2 * Copyright (c) 2021-2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef HISTREAMER_PLUGIN_INTF_PLUGIN_DEFINITION_H 17 #define HISTREAMER_PLUGIN_INTF_PLUGIN_DEFINITION_H 18 19 #include <string> 20 #include <memory> 21 #include "common/plugin_types.h" 22 23 namespace OHOS { 24 namespace Media { 25 namespace Plugin { 26 /** 27 * @brief Macro definition, creating the version information. 28 * 29 * @details The versioning is the process of assigning a unique version number to a unique state 30 * of plugin interface. Within a given version number category (major, minor), these numbers are 31 * usually assigned in ascending order and correspond to new developments in the plugin. 32 * 33 * Given a version number MAJOR.MINOR: 34 * - MAJOR: When you make incompatible API changes. 35 * - MINOR: When you add features in a backwards-compatible manner or do backwards-compatible bug fixes. 36 */ 37 #define MAKE_VERSION(MAJOR, MINOR) ((((MAJOR)&0xFFFF) << 16) | ((MINOR)&0xFFFF)) 38 39 /// Plugin interface major number 40 #define PLUGIN_INTERFACE_VERSION_MAJOR (1) 41 42 /// Plugin interface minor number 43 #define PLUGIN_INTERFACE_VERSION_MINOR (0) 44 45 /// Plugin interface version 46 #define PLUGIN_INTERFACE_VERSION MAKE_VERSION(PLUGIN_INTERFACE_VERSION_MAJOR, PLUGIN_INTERFACE_VERSION_MINOR) 47 48 /** 49 * @enum License Type. 50 * an official permission or permit. 51 * 52 * @since 1.0 53 * @version 1.0 54 */ 55 enum struct LicenseType : uint8_t { 56 APACHE_V2, ///< The Apache License 2.0 57 LGPL, ///< The GNU Lesser General Public License 58 GPL, ///< The GNU General Public License 59 CC0, ///< The Creative Commons Zero v1.0 Universal 60 UNKNOWN, ///< Unknown License 61 }; 62 63 /** 64 * @brief Definition of plugin packaging information. 65 * 66 * @since 1.0 67 * @version 1.0 68 */ 69 struct PackageDef { 70 uint32_t pkgVersion; ///< Package information version, which indicates the latest plug-in interface version 71 ///< used by the plugin in the package. The default value is PLUGIN_INTERFACE_VERSION. 72 73 std::string name; ///< Package name. The plugin framework registers the plugin using this name. 74 ///< If the plugins are packaged as a dynamic library, the name of library 75 ///< must be in the format of "libplugin_<name>.so". 76 77 LicenseType 78 licenseType; ///< The License information of the plugin in the package. 79 ///< The different plugins must be the same. 80 ///< The plugin framework processing in the plugin running state based on different license. 81 }; 82 83 /// Plugin create function. All plugins must implement this function. 84 template <typename T> 85 using PluginCreatorFunc = std::shared_ptr<T>(*)(const std::string& name); 86 87 /** 88 * @brief Describes the basic information about the plugin. 89 * 90 * @since 1.0 91 * @version 1.0 92 */ 93 struct PluginDefBase { 94 uint32_t apiVersion; ///< Versions of different plugins. Different types of plugin have their own versions. 95 96 PluginType pluginType = PluginType::INVALID_TYPE; ///< Describe the plugin type, e.g. 'source', 'codec'. 97 98 std::string name; ///< Indicates the name of a plugin. The name of the same type plugins must be unique. 99 ///< Plugins with the same name may fail to be registered. 100 101 std::string description; ///< Detailed description of the plugin. 102 103 uint32_t rank; ///< Plugin score. The plugin with a high score may be preferred. You can evaluate the 104 ///< plugin score in terms of performance, version support, and license. Range: 0 to 100. 105 }; 106 107 /** 108 * @brief The plugin registration interface. 109 * The plugin framework will provide the implementation. 110 * Developers only need to invoke the API to register the plugin. 111 * 112 * @since 1.0 113 * @version 1.0 114 */ 115 struct Register { 116 virtual ~Register() = default; 117 /** 118 * @brief Register the plugin. 119 * 120 * @param def Basic information about the plugin 121 * @return Registration status return 122 * @retval OK: The plugin is registered succeed. 123 * @retval ERROR_PLUGIN_ALREADY_EXISTS: The plugin already exists in plugin registered. 124 * @retval ERROR_INCOMPATIBLE_VERSION: Incompatible version during plugin registration. 125 */ 126 virtual Status AddPlugin(const PluginDefBase& def) = 0; 127 }; 128 129 /** 130 * @brief The package registration interface. 131 * The plugin framework will provide the implementation and auto invoke the API to 132 * finish the package registration when plugin framework first time be initialized. 133 * 134 * @since 1.0 135 * @version 1.0 136 */ 137 struct PackageRegister : Register { 138 ~PackageRegister() override = default; 139 140 /** 141 * @brief Register the package. 142 * During package registration, all plugins in the package are automatically registered. 143 * 144 * @param def plugin packaging information. 145 * @return Registration status return 146 * @retval OK: The package is registered succeed without any errors. 147 * @retval ERROR_PLUGIN_ALREADY_EXISTS: The package or plugins already exists. 148 * @retval ERROR_INCOMPATIBLE_VERSION: Incompatible plugin interface version or api version. 149 */ 150 virtual Status AddPackage(const PackageDef& def) = 0; 151 }; 152 153 /// Plugin registration function, all plugins must be implemented. 154 using RegisterFunc = Status (*)(std::shared_ptr<Register> reg); 155 156 /// Plugin deregister function, all plugins must be implemented. 157 using UnregisterFunc = void (*)(); 158 159 #if defined(WIN32) || defined(_WIN32) || defined(__WIN32__) 160 #define PLUGIN_EXPORT extern "C" __declspec(dllexport) 161 #else 162 #if defined(__GNUC__) || (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x590)) 163 #define PLUGIN_EXPORT extern "C" __attribute__((visibility("default"))) 164 #else 165 #define PLUGIN_EXPORT 166 #endif 167 #endif 168 169 /// Macro definition, string concatenation 170 #define PLUGIN_PASTE_ARGS(str1, str2) str1##str2 171 172 /// Macro definition, string concatenation 173 #define PLUGIN_PASTE(str1, str2) PLUGIN_PASTE_ARGS(str1, str2) 174 175 /// Macro definition, stringify 176 #define PLUGIN_STRINGIFY_ARG(str) #str 177 178 /// Macro definition, stringify 179 #define PLUGIN_STRINGIFY(str) PLUGIN_STRINGIFY_ARG(str) 180 181 /** 182 * @brief Macro definition, Defines basic plugin information. 183 * Which is invoked during plugin package registration. All plugin packages must be implemented. 184 * 185 * @param name Package name. For details, @see PackageDef::name 186 * @param license Package License, For details, @see PackageDef::licenseType 187 * @param registerFunc Plugin registration function, MUST NOT be NULL. 188 * @param unregisterFunc Plugin deregister function，MUST NOT be NULL. 189 */ 190 #define PLUGIN_DEFINITION(name, license, registerFunc, unregisterFunc) \ 191 PLUGIN_EXPORT OHOS::Media::Plugin::Status PLUGIN_PASTE(register_, name)( \ 192 const std::shared_ptr<OHOS::Media::Plugin::PackageRegister>& pkgReg) \ 193 { \ 194 pkgReg->AddPackage({PLUGIN_INTERFACE_VERSION, PLUGIN_STRINGIFY(name), license}); \ 195 std::shared_ptr<OHOS::Media::Plugin::Register> pluginReg = pkgReg; \ 196 return registerFunc(pluginReg); \ 197 } \ 198 PLUGIN_EXPORT void PLUGIN_PASTE(unregister_, name)() \ 199 { \ 200 unregisterFunc(); \ 201 } 202 } // namespace Plugin 203 } // namespace Media 204 } // namespace OHOS 205 #endif // HISTREAMER_PLUGIN_INTF_PLUGIN_DEFINITION_H 206