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
25namespace OHOS {
26namespace Media {
27namespace Plugin {
28enum 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 */
40struct 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 */
66struct PluginBase {
67    /// Constructor
68    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     */
78    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     */
93    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     */
107    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     */
122    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     */
137    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     */
152    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     */
166    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     */
182    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     */
200    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     */
213    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
229protected:
230    const std::string pluginName_;
231};
232} // namespace Plugin
233} // namespace Media
234} // namespace OHOS
235#endif // HISTREAMER_PLUGIN_INTF_PLUGIN_BASE_H
236