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_BASE_H 17 #define HISTREAMER_PLUGIN_INTF_PLUGIN_BASE_H 18 19 #include <memory> 20 #include "plugin/common/plugin_buffer.h" 21 #include "plugin/common/plugin_event.h" 22 #include "plugin/common/plugin_tags.h" 23 #include "plugin/common/plugin_types.h" 24 25 namespace OHOS { 26 namespace Media { 27 namespace Plugin { 28 enum class ErrorType { 29 PLUGIN_ERROR, 30 ALGO_ERROR, 31 CLIENT_ERROR, 32 SERVER_ERROR, 33 }; 34 /** 35 * @brief Plugin status callback interface. 36 * 37 * @since 1.0 38 * @version 1.0 39 */ 40 struct Callback { 41 /// Destructor 42 virtual ~Callback() = default; 43 44 /** 45 * @brief When asynchronous time occurs during plugin running, 46 * the plugin implementer invokes this interface to notify the plugin user. 47 * 48 * @note Reserved Interface, Not used yet. 49 * 50 * @param event Event ID. 51 */ 52 virtual void OnEvent(const PluginEvent &event) = 0; 53 }; 54 55 /** 56 * @brief Base class of a plugin. All plugins of different types inherit this interface. 57 * 58 * @details The base class contains only common operation methods and defines basic operation processes. 59 * Different operations are valid only in the corresponding states. The timing of calls is guaranteed by 60 * the plugin framework. Some operations also change the plugin status. 61 * For details, see the description of each function. 62 * 63 * @since 1.0 64 * @version 1.0 65 */ 66 struct PluginBase { 67 /// Constructor PluginBasePluginBase68 explicit PluginBase(std::string name): pluginName_(std::move(name)) {} 69 70 /// Destructor 71 virtual ~PluginBase() = default; 72 73 /** 74 * @brief Get plugin name 75 * 76 * @return plugin name 77 */ GetNamePluginBase78 std::string GetName() const 79 { 80 return pluginName_; 81 } 82 83 /** 84 * @brief Plugin initialization, which is used to load external resources or plugin common resources. 85 * 86 * The function is valid only in the CREATED state. If the initialization is successful, 87 * the plugin enters the INITIALIZED state. 88 * 89 * @return Execution status return 90 * @retval OK: Plugin Init succeeded. 91 * @retval ERROR_NO_MEMORY: Memory allocation or external resource loading error caused by insufficient memory. 92 */ InitPluginBase93 virtual Status Init() 94 { 95 return Status::OK; 96 } 97 98 /** 99 * @brief Plugin deinitialize to release resources. 100 * 101 * This function can be invoked in any state. 102 * After the function is invoked, the plugin will no longer be available. 103 * 104 * @return Execution status return 105 * @retval OK: Plugin Deinit succeeded. 106 */ DeinitPluginBase107 virtual Status Deinit() 108 { 109 return Status::OK; 110 } 111 112 /** 113 * @brief Preparing parameters required or allocate the memory for plugin running. 114 * 115 * The function is valid only in the INITIALIZED state. If the prepare is successful, 116 * the plugin enters the PREPARED state. 117 * 118 * @return Execution status return 119 * @retval OK: Plugin Prepare succeeded. 120 * @retval ERROR_NO_MEMORY: Memory allocation error caused by insufficient memory. 121 */ PreparePluginBase122 virtual Status Prepare() 123 { 124 return Status::OK; 125 } 126 127 /** 128 * @brief Reset the plugin, reset the plugin running status and parameters before Prepare. 129 * 130 * The function is valid only in the PREPARED/RUNNING/PAUSED state. If the reset is successful, 131 * the plugin enters the INITIALIZED state. 132 * 133 * @return Execution status return 134 * @retval OK: Plugin Reset succeeded. 135 * @retval ERROR_UNIMPLEMENTED: This method is not implemented and cannot respond to reset. 136 */ ResetPluginBase137 virtual Status Reset() 138 { 139 return Status::OK; 140 } 141 142 /** 143 * @brief The plugin enters the running state and can process data. 144 * 145 * The function is valid only in the PREPARED state. If the start is successful, 146 * the plugin enters the RUNNING state. If an error occurs during the running, 147 * the plu-in status can be changed through asynchronous callback. 148 * 149 * @return Execution status return 150 * @retval OK: Plugin Start succeeded. 151 */ StartPluginBase152 virtual Status Start() 153 { 154 return Status::OK; 155 } 156 157 /** 158 * @brief The plugin enters the stopped state and stops processing data. 159 * 160 * The function is valid only in the RUNNING state. If the stop is successful, 161 * the plugin enters the PREPARED state. Temporary data generated during the operation will be cleared. 162 * 163 * @return Execution status return 164 * @retval OK: Plugin Stop succeeded. 165 */ StopPluginBase166 virtual Status Stop() 167 { 168 return Status::OK; 169 } 170 171 /** 172 * @brief Get the value of a specified parameter. 173 * 174 * This function can be called in any state except DESTROYED and INVALID. 175 * 176 * @param tag Plugin parameter type, which is described by tag. 177 * @param value Plugin parameter value. which is described by Any type. Need check the real type in tag. 178 * @return Execution status return 179 * @retval OK: Plugin GetParameter succeeded. 180 * @retval ERROR_INVALID_PARAMETER: The plugin does not support this parameter. 181 */ GetParameterPluginBase182 virtual Status GetParameter(Tag tag, ValueType &value) 183 { 184 return Status::ERROR_UNIMPLEMENTED; 185 } 186 187 /** 188 * @brief Set the specified parameter. The value must be within the valid range of the parameter. 189 * 190 * This function can be called in any state except DESTROYED and INVALID. 191 * 192 * @param tag Plugin parameter type, which is described by tag. 193 * @param value Plugin parameter value. which is described by Any type. Need check the real type in tag. 194 * @return Execution status return 195 * @retval OK: Plugin SetParameter succeeded. 196 * @retval ERROR_INVALID_PARAMETER: The plugin does not support this parameter. 197 * @retval ERROR_INVALID_DATA: The value is not in the valid range. 198 * @retval ERROR_MISMATCHED_TYPE: The data type is mismatched. 199 */ SetParameterPluginBase200 virtual Status SetParameter(Tag tag, const ValueType &value) 201 { 202 return Status::ERROR_UNIMPLEMENTED; 203 } 204 205 /** 206 * @brief Get the allocator specified by the plugin. 207 * The allocator can allocate memory types that meet the plugin requirements. 208 * The filter first looks up the allocator from the negotiation result; 209 * If it does not exist, the return value here will be used. 210 * 211 * @return Obtains the allocator object or NULL if the plugin does not have requirements for memory. 212 */ GetAllocatorPluginBase213 virtual std::shared_ptr<Allocator> GetAllocator() 214 { 215 return nullptr; 216 } 217 218 /** 219 * @brief Sets the plugin callback message to notify the plugin user. 220 * 221 * This function can be called in any state except DESTROYED and INVALID. 222 * 223 * @param cb Message callback, NULL callback listening is canceled. 224 * @return Execution status return 225 * @retval OK: Plugin SetCallback succeeded. 226 */ 227 virtual Status SetCallback(Callback* cb) = 0; 228 229 protected: 230 const std::string pluginName_; 231 }; 232 } // namespace Plugin 233 } // namespace Media 234 } // namespace OHOS 235 #endif // HISTREAMER_PLUGIN_INTF_PLUGIN_BASE_H 236