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