1 /* 2 * Copyright (c) 2023 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 PLUGIN_INTF_PLUGIN_DEFINITION_H 17 #define PLUGIN_INTF_PLUGIN_DEFINITION_H 18 19 #include <string> 20 #include <memory> 21 #include <functional> 22 #include "plugin_types.h" 23 24 namespace OHOS { 25 namespace MediaAVCodec { 26 namespace Plugin { 27 /** 28 * @enum Plugin Return Status. 29 * 30 * @since 10 31 * @version 1.0 32 */ 33 enum struct Status : int32_t { 34 END_OF_STREAM = 1, ///< Read source when end of stream 35 OK = 0, ///< The execution result is correct. 36 NO_ERROR = OK, ///< Same as Status::OK 37 ERROR_UNKNOWN = -1, ///< An unknown error occurred. 38 ERROR_PLUGIN_ALREADY_EXISTS = -2, ///< The plugin already exists, usually occurs when in plugin registered. 39 ERROR_INCOMPATIBLE_VERSION = -3, 40 ///< Incompatible version, may occur during plugin registration or function calling. 41 ERROR_NO_MEMORY = -4, ///< The system memory is insufficient. 42 ERROR_WRONG_STATE = -5, ///< The function is called in an invalid state. 43 ERROR_UNIMPLEMENTED = -6, ///< This method or interface is not implemented. 44 ERROR_INVALID_PARAMETER = -7, ///< The plugin does not support this parameter. 45 ERROR_INVALID_DATA = -8, ///< The value is not in the valid range. 46 ERROR_MISMATCHED_TYPE = -9, ///< Mismatched data type 47 ERROR_TIMED_OUT = -10, ///< Operation timeout. 48 ERROR_UNSUPPORTED_FORMAT = -11, ///< The plugin not support this format/name. 49 ERROR_NOT_ENOUGH_DATA = -12, ///< Not enough data when read from source. 50 ERROR_NOT_EXISTED = -13, ///< Source is not existed. 51 ERROR_AGAIN = -14, ///< Operation is not available right now, should try again later. 52 ERROR_PERMISSION_DENIED = -15, ///< Permission denied. 53 ERROR_NULL_POINTER = -16, ///< Null pointer. 54 ERROR_INVALID_OPERATION = -17, ///< Invalid operation. 55 ERROR_CLIENT = -18, ///< Http client error 56 ERROR_SERVER = -19, ///< Http server error 57 ERROR_DELAY_READY = -20, ///< Delay ready event 58 }; 59 60 /** 61 * @brief Macro definition, creating the version information. 62 * 63 * @details The versioning is the process of assigning a unique version number to a unique state 64 * of plugin interface. Within a given version number category (major, minor), these numbers are 65 * usually assigned in ascending order and correspond to new developments in the plugin. 66 * 67 * Given a version number MAJOR.MINOR: 68 * - MAJOR: When you make incompatible API changes. 69 * - MINOR: When you add features in a backwards-compatible manner or do backwards-compatible bug fixes. 70 */ 71 #define MAKE_VERSION(MAJOR, MINOR) ((((MAJOR)&0xFFFF) << 16) | ((MINOR)&0xFFFF)) 72 73 /// Plugin interface major number 74 #define PLUGIN_INTERFACE_VERSION_MAJOR (1) 75 76 /// Plugin interface minor number 77 #define PLUGIN_INTERFACE_VERSION_MINOR (0) 78 79 /// Plugin interface version 80 #define PLUGIN_INTERFACE_VERSION MAKE_VERSION(PLUGIN_INTERFACE_VERSION_MAJOR, PLUGIN_INTERFACE_VERSION_MINOR) 81 82 /** 83 * @enum License Type. 84 * an official permission or permit. 85 * 86 * @since 10 87 * @version 1.0 88 */ 89 enum struct LicenseType : uint8_t { 90 APACHE_V2, ///< The Apache License 2.0 91 LGPL, ///< The GNU Lesser General Public License 92 GPL, ///< The GNU General Public License 93 CC0, ///< The Creative Commons Zero v1.0 Universal 94 UNKNOWN, ///< Unknown License 95 }; 96 97 /** 98 * @brief Definition of plugin packaging information. 99 * 100 * @since 10 101 * @version 1.0 102 */ 103 struct PackageDef { 104 uint32_t pkgVersion; ///< Package information version, which indicates the latest plug-in interface version 105 ///< used by the plugin in the package. The default value is PLUGIN_INTERFACE_VERSION. 106 107 std::string name; ///< Package name. The plugin framework registers the plugin using this name. 108 ///< If the plugins are packaged as a dynamic library, the name of library 109 ///< must be in the format of "libplugin_<name>.so". 110 111 LicenseType 112 licenseType; ///< The License information of the plugin in the package. 113 ///< The different plugins must be the same. 114 ///< The plugin framework processing in the plugin running state based on different license. 115 }; 116 117 /// Plugin create function. All plugins must implement this function. 118 template <typename T> 119 using PluginCreatorFunc = std::function<std::shared_ptr<T>(const std::string& name)>; 120 121 /** 122 * @brief Describes the basic information about the plugin. 123 * 124 * @since 10 125 * @version 1.0 126 */ 127 struct PluginDefBase { 128 uint32_t apiVersion; ///< Versions of different plugins. Different types of plugin have their own versions. 129 130 PluginType pluginType = PluginType::INVALID_TYPE; ///< Describe the plugin type, e.g. 'source', 'codec'. 131 132 std::string name; ///< Indicates the name of a plugin. The name of the same type plugins must be unique. 133 ///< Plugins with the same name may fail to be registered. 134 135 std::string description; ///< Detailed description of the plugin. 136 137 uint32_t rank; ///< Plugin score. The plugin with a high score may be preferred. You can evaluate the 138 ///< plugin score in terms of performance, version support, and license. Range: 0 to 100. 139 }; 140 141 /** 142 * @brief The plugin registration interface. 143 * The plugin framework will provide the implementation. 144 * Developers only need to invoke the API to register the plugin. 145 * 146 * @since 10 147 * @version 1.0 148 */ 149 struct Register { 150 virtual ~Register() = default; 151 /** 152 * @brief Register the plugin. 153 * 154 * @param def Basic information about the plugin 155 * @return Registration status return 156 * @retval OK: The plugin is registered succeed. 157 * @retval CSERR_PLUGIN_ALREADY_EXISTS: The plugin already exists in plugin registered. 158 * @retval CSERR_INCOMPATIBLE_VERSION: Incompatible version during plugin registration. 159 */ 160 virtual Status AddPlugin(const PluginDefBase& def) = 0; 161 }; 162 163 /** 164 * @brief The package registration interface. 165 * The plugin framework will provide the implementation and auto invoke the API to 166 * finish the package registration when plugin framework first time be initialized. 167 * 168 * @since 10 169 * @version 1.0 170 */ 171 struct PackageRegister : Register { 172 ~PackageRegister() override = default; 173 174 /** 175 * @brief Register the package. 176 * During package registration, all plugins in the package are automatically registered. 177 * 178 * @param def plugin packaging information. 179 * @return Registration status return 180 * @retval OK: The package is registered succeed without any errors. 181 * @retval CSERR_PLUGIN_ALREADY_EXISTS: The package or plugins already exists. 182 * @retval CSERR_INCOMPATIBLE_VERSION: Incompatible plugin interface version or api version. 183 */ 184 virtual Status AddPackage(const PackageDef& def) = 0; 185 }; 186 187 /// Plugin registration function, all plugins must be implemented. 188 using RegisterFunc = Status (*)(std::shared_ptr<Register> reg); 189 190 /// Plugin deregister function, all plugins must be implemented. 191 using UnregisterFunc = void (*)(); 192 193 #if defined(WIN32) || defined(_WIN32) || defined(__WIN32__) 194 #define PLUGIN_EXPORT extern "C" __declspec(dllexport) 195 #else 196 #if defined(__GNUC__) || (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x590)) 197 #define PLUGIN_EXPORT extern "C" __attribute__((visibility("default"))) 198 #else 199 #define PLUGIN_EXPORT 200 #endif 201 #endif 202 203 /// Macro definition, string concatenation 204 #define PLUGIN_PASTE_ARGS(str1, str2) str1##str2 205 206 /// Macro definition, string concatenation 207 #define PLUGIN_PASTE(str1, str2) PLUGIN_PASTE_ARGS(str1, str2) 208 209 /// Macro definition, stringify 210 #define PLUGIN_STRINGIFY_ARG(str) #str 211 212 /// Macro definition, stringify 213 #define PLUGIN_STRINGIFY(str) PLUGIN_STRINGIFY_ARG(str) 214 215 /** 216 * @brief Macro definition, Defines basic plugin information. 217 * Which is invoked during plugin package registration. All plugin packages must be implemented. 218 * 219 * @param name Package name. For details, @see PackageDef::name 220 * @param license Package License, For details, @see PackageDef::licenseType 221 * @param registerFunc Plugin registration function, MUST NOT be NULL. 222 * @param unregisterFunc Plugin deregister function，MUST NOT be NULL. 223 */ 224 #define PLUGIN_DEFINITION(name, license, registerFunc, unregisterFunc) \ 225 PLUGIN_EXPORT Status PLUGIN_PASTE(register_, name)( \ 226 const std::shared_ptr<OHOS::MediaAVCodec::Plugin::PackageRegister>& pkgReg) \ 227 { \ 228 pkgReg->AddPackage({ PLUGIN_INTERFACE_VERSION, PLUGIN_STRINGIFY(name), license }); \ 229 std::shared_ptr<OHOS::MediaAVCodec::Plugin::Register> pluginReg = pkgReg; \ 230 return registerFunc(pluginReg); \ 231 } \ 232 PLUGIN_EXPORT void PLUGIN_PASTE(unregister_, name)() \ 233 { \ 234 unregisterFunc(); \ 235 } 236 } // namespace Plugin 237 } // namespace MediaAVCodec 238 } // namespace OHOS 239 #endif // PLUGIN_INTF_PLUGIN_DEFINITION_H 240