1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
/* Simple Plugin API
*
* Copyright © 2018 Wim Taymans
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice (including the next
* paragraph) shall be included in all copies or substantial portions of the
* Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
* DEALINGS IN THE SOFTWARE.
*/
#ifndef SPA_PLUGIN_H
#define SPA_PLUGIN_H
#ifdef __cplusplus
extern "C" {
#endif
#include <spa/utils/defs.h>
#include <spa/utils/dict.h>
/**
* \defgroup spa_handle Plugin Handle
* SPA plugin handle and factory interfaces
*/
/**
* \addtogroup spa_handle
* \{
*/
struct spa_handle {
/** Version of this struct */
#define SPA_VERSION_HANDLE 0
uint32_t version;
/**
* Get the interface provided by \a handle with \a type.
*
* \a interface is always a struct spa_interface but depending on
* \a type, the struct might contain other information.
*
* \param handle a spa_handle
* \param type the interface type
* \param interface result to hold the interface.
* \return 0 on success
* -ENOTSUP when there are no interfaces
* -EINVAL when handle or info is NULL
*/
int (*get_interface) (struct spa_handle *handle, const char *type, void **interface);
/**
* Clean up the memory of \a handle. After this, \a handle should not be used
* anymore.
*
* \param handle a pointer to memory
* \return 0 on success
*/
int (*clear) (struct spa_handle *handle);
};
#define spa_handle_get_interface(h,...) (h)->get_interface((h),__VA_ARGS__)
#define spa_handle_clear(h) (h)->clear((h))
/**
* This structure lists the information about available interfaces on
* handles.
*/
struct spa_interface_info {
const char *type; /*< the type of the interface, can be
* used to get the interface */
};
/**
* Extra supporting infrastructure passed to the init() function of
* a factory. It can be extra information or interfaces such as logging.
*/
struct spa_support {
const char *type; /*< the type of the support item */
void *data; /*< specific data for the item */
};
/** Find a support item of the given type */
static inline void *spa_support_find(const struct spa_support *support,
uint32_t n_support,
const char *type)
{
uint32_t i;
for (i = 0; i < n_support; i++) {
if (strcmp(support[i].type, type) == 0)
return support[i].data;
}
return NULL;
}
#define SPA_SUPPORT_INIT(type,data) (struct spa_support) { (type), (data) }
struct spa_handle_factory {
/** The version of this structure */
#define SPA_VERSION_HANDLE_FACTORY 1
uint32_t version;
/**
* The name of the factory contains a logical name that describes
* the function of the handle. Other plugins might contain an alternative
* implementation with the same name.
*
* See utils/names.h for the list of standard names.
*
* Examples include:
*
* api.alsa.pcm.sink: an object to write PCM samples to an alsa PLAYBACK
* device
* api.v4l2.source: an object to read from a v4l2 source.
*/
const char *name;
/**
* Extra information about the handles of this factory.
*/
const struct spa_dict *info;
/**
* Get the size of handles from this factory.
*
* \param factory a spa_handle_factory
* \param params extra parameters that determine the size of the
* handle.
*/
size_t (*get_size) (const struct spa_handle_factory *factory,
const struct spa_dict *params);
/**
* Initialize an instance of this factory. The caller should allocate
* memory at least size bytes and pass this as \a handle.
*
* \a support can optionally contain extra interfaces or data items that the
* plugin can use such as a logger.
*
* \param factory a spa_handle_factory
* \param handle a pointer to memory
* \param info extra handle specific information, usually obtained
* from a spa_device. This can be used to configure the handle.
* \param support support items
* \param n_support number of elements in \a support
* \return 0 on success
* < 0 errno type error
*/
int (*init) (const struct spa_handle_factory *factory,
struct spa_handle *handle,
const struct spa_dict *info,
const struct spa_support *support,
uint32_t n_support);
/**
* spa_handle_factory::enum_interface_info:
* \param factory: a #spa_handle_factory
* \param info: result to hold spa_interface_info.
* \param index: index to keep track of the enumeration, 0 for first item
*
* Enumerate the interface information for \a factory.
*
* \return 1 when an item is available
* 0 when no more items are available
* < 0 errno type error
*/
int (*enum_interface_info) (const struct spa_handle_factory *factory,
const struct spa_interface_info **info,
uint32_t *index);
};
#define spa_handle_factory_get_size(h,...) (h)->get_size((h),__VA_ARGS__)
#define spa_handle_factory_init(h,...) (h)->init((h),__VA_ARGS__)
#define spa_handle_factory_enum_interface_info(h,...) (h)->enum_interface_info((h),__VA_ARGS__)
/**
* The function signature of the entry point in a plugin.
*
* \param factory a location to hold the factory result
* \param index index to keep track of the enumeration
* \return 1 on success
* 0 when there are no more factories
* -EINVAL when factory is NULL
*/
typedef int (*spa_handle_factory_enum_func_t) (const struct spa_handle_factory **factory,
uint32_t *index);
#define SPA_HANDLE_FACTORY_ENUM_FUNC_NAME "spa_handle_factory_enum"
/**
* The entry point in a plugin.
*
* \param factory a location to hold the factory result
* \param index index to keep track of the enumeration
* \return 1 on success
* 0 when no more items are available
* < 0 errno type error
*/
int spa_handle_factory_enum(const struct spa_handle_factory **factory, uint32_t *index);
#define SPA_KEY_FACTORY_NAME "factory.name" /**< the name of a factory */
#define SPA_KEY_FACTORY_AUTHOR "factory.author" /**< a comma separated list of factory authors */
#define SPA_KEY_FACTORY_DESCRIPTION "factory.description" /**< description of a factory */
#define SPA_KEY_FACTORY_USAGE "factory.usage" /**< usage of a factory */
#define SPA_KEY_LIBRARY_NAME "library.name" /**< the name of a library. This is usually
* the filename of the plugin without the
* path or the plugin extension. */
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* SPA_PLUGIN_H */
|
