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
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// from gst-gir-files (https://gitlab.freedesktop.org/gstreamer/gir-files-rs.git)
// DO NOT EDIT

use crate::{ffi, Object, PluginDependencyFlags, Structure};
use glib::translate::*;

glib::wrapper! {
    /// GStreamer is extensible, so [`Element`][crate::Element] instances can be loaded at runtime.
    /// A plugin system can provide one or more of the basic GStreamer
    /// [`PluginFeature`][crate::PluginFeature] subclasses.
    ///
    /// A plugin should export a symbol `gst_plugin_desc` that is a
    /// struct of type `GstPluginDesc`.
    /// the plugin loader will check the version of the core library the plugin was
    /// linked against and will create a new [`Plugin`][crate::Plugin]. It will then call the
    /// `GstPluginInitFunc` function that was provided in the
    /// `gst_plugin_desc`.
    ///
    /// Once you have a handle to a [`Plugin`][crate::Plugin] (e.g. from the [`Registry`][crate::Registry]), you
    /// can add any object that subclasses [`PluginFeature`][crate::PluginFeature].
    ///
    /// Usually plugins are always automatically loaded so you don't need to call
    /// [`load()`][Self::load()] explicitly to bring it into memory. There are options to
    /// statically link plugins to an app or even use GStreamer without a plugin
    /// repository in which case [`load()`][Self::load()] can be needed to bring the plugin
    /// into memory.
    ///
    /// # Implements
    ///
    /// [`GstObjectExt`][trait@crate::prelude::GstObjectExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GstPlugin")]
    pub struct Plugin(Object<ffi::GstPlugin, ffi::GstPluginClass>) @extends Object;

    match fn {
        type_ => || ffi::gst_plugin_get_type(),
    }
}

impl Plugin {
    /// Make GStreamer aware of external dependencies which affect the feature
    /// set of this plugin (ie. the elements or typefinders associated with it).
    ///
    /// GStreamer will re-inspect plugins with external dependencies whenever any
    /// of the external dependencies change. This is useful for plugins which wrap
    /// other plugin systems, e.g. a plugin which wraps a plugin-based visualisation
    /// library and makes visualisations available as GStreamer elements, or a
    /// codec loader which exposes elements and/or caps dependent on what external
    /// codec libraries are currently installed.
    /// ## `env_vars`
    /// [`None`]-terminated array of environment variables affecting the
    ///  feature set of the plugin (e.g. an environment variable containing
    ///  paths where to look for additional modules/plugins of a library),
    ///  or [`None`]. Environment variable names may be followed by a path component
    ///  which will be added to the content of the environment variable, e.g.
    ///  "HOME/.mystuff/plugins".
    /// ## `paths`
    /// [`None`]-terminated array of directories/paths where dependent files
    ///  may be, or [`None`].
    /// ## `names`
    /// [`None`]-terminated array of file names (or file name suffixes,
    ///  depending on `flags`) to be used in combination with the paths from
    ///  `paths` and/or the paths extracted from the environment variables in
    ///  `env_vars`, or [`None`].
    /// ## `flags`
    /// optional flags, or `GST_PLUGIN_DEPENDENCY_FLAG_NONE`
    #[doc(alias = "gst_plugin_add_dependency")]
    pub fn add_dependency(
        &self,
        env_vars: &[&str],
        paths: &[&str],
        names: &[&str],
        flags: PluginDependencyFlags,
    ) {
        unsafe {
            ffi::gst_plugin_add_dependency(
                self.to_glib_none().0,
                env_vars.to_glib_none().0,
                paths.to_glib_none().0,
                names.to_glib_none().0,
                flags.into_glib(),
            );
        }
    }

    /// Make GStreamer aware of external dependencies which affect the feature
    /// set of this plugin (ie. the elements or typefinders associated with it).
    ///
    /// GStreamer will re-inspect plugins with external dependencies whenever any
    /// of the external dependencies change. This is useful for plugins which wrap
    /// other plugin systems, e.g. a plugin which wraps a plugin-based visualisation
    /// library and makes visualisations available as GStreamer elements, or a
    /// codec loader which exposes elements and/or caps dependent on what external
    /// codec libraries are currently installed.
    ///
    /// Convenience wrapper function for [`add_dependency()`][Self::add_dependency()] which
    /// takes simple strings as arguments instead of string arrays, with multiple
    /// arguments separated by predefined delimiters (see above).
    /// ## `env_vars`
    /// one or more environment variables (separated by ':', ';' or ','),
    ///  or [`None`]. Environment variable names may be followed by a path component
    ///  which will be added to the content of the environment variable, e.g.
    ///  "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH"
    /// ## `paths`
    /// one ore more directory paths (separated by ':' or ';' or ','),
    ///  or [`None`]. Example: "/usr/lib/mystuff/plugins"
    /// ## `names`
    /// one or more file names or file name suffixes (separated by commas),
    ///  or [`None`]
    /// ## `flags`
    /// optional flags, or `GST_PLUGIN_DEPENDENCY_FLAG_NONE`
    #[doc(alias = "gst_plugin_add_dependency_simple")]
    pub fn add_dependency_simple(
        &self,
        env_vars: Option<&str>,
        paths: Option<&str>,
        names: Option<&str>,
        flags: PluginDependencyFlags,
    ) {
        unsafe {
            ffi::gst_plugin_add_dependency_simple(
                self.to_glib_none().0,
                env_vars.to_glib_none().0,
                paths.to_glib_none().0,
                names.to_glib_none().0,
                flags.into_glib(),
            );
        }
    }

    /// ## `message`
    /// the status error message
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_add_status_error")]
    pub fn add_status_error(&self, message: &str) {
        unsafe {
            ffi::gst_plugin_add_status_error(self.to_glib_none().0, message.to_glib_none().0);
        }
    }

    /// ## `message`
    /// the status info message
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_add_status_info")]
    pub fn add_status_info(&self, message: &str) {
        unsafe {
            ffi::gst_plugin_add_status_info(self.to_glib_none().0, message.to_glib_none().0);
        }
    }

    /// ## `message`
    /// the status warning message
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_add_status_warning")]
    pub fn add_status_warning(&self, message: &str) {
        unsafe {
            ffi::gst_plugin_add_status_warning(self.to_glib_none().0, message.to_glib_none().0);
        }
    }

    /// Get the long descriptive name of the plugin
    ///
    /// # Returns
    ///
    /// the long name of the plugin
    #[doc(alias = "gst_plugin_get_description")]
    #[doc(alias = "get_description")]
    pub fn description(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_description(self.to_glib_none().0)) }
    }

    /// get the filename of the plugin
    ///
    /// # Returns
    ///
    /// the filename of the plugin
    #[doc(alias = "gst_plugin_get_filename")]
    #[doc(alias = "get_filename")]
    pub fn filename(&self) -> Option<std::path::PathBuf> {
        unsafe { from_glib_none(ffi::gst_plugin_get_filename(self.to_glib_none().0)) }
    }

    /// get the license of the plugin
    ///
    /// # Returns
    ///
    /// the license of the plugin
    #[doc(alias = "gst_plugin_get_license")]
    #[doc(alias = "get_license")]
    pub fn license(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_license(self.to_glib_none().0)) }
    }

    /// Get the short name of the plugin
    ///
    /// # Returns
    ///
    /// the name of the plugin
    #[doc(alias = "gst_plugin_get_name")]
    #[doc(alias = "get_name")]
    pub fn plugin_name(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_name(self.to_glib_none().0)) }
    }

    /// get the URL where the plugin comes from
    ///
    /// # Returns
    ///
    /// the origin of the plugin
    #[doc(alias = "gst_plugin_get_origin")]
    #[doc(alias = "get_origin")]
    pub fn origin(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_origin(self.to_glib_none().0)) }
    }

    /// get the package the plugin belongs to.
    ///
    /// # Returns
    ///
    /// the package of the plugin
    #[doc(alias = "gst_plugin_get_package")]
    #[doc(alias = "get_package")]
    pub fn package(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_package(self.to_glib_none().0)) }
    }

    /// Get the release date (and possibly time) in form of a string, if available.
    ///
    /// For normal GStreamer plugin releases this will usually just be a date in
    /// the form of "YYYY-MM-DD", while pre-releases and builds from git may contain
    /// a time component after the date as well, in which case the string will be
    /// formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z").
    ///
    /// There may be plugins that do not have a valid release date set on them.
    ///
    /// # Returns
    ///
    /// the date string of the plugin, or [`None`] if not
    /// available.
    #[doc(alias = "gst_plugin_get_release_date_string")]
    #[doc(alias = "get_release_date_string")]
    pub fn release_date_string(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::gst_plugin_get_release_date_string(
                self.to_glib_none().0,
            ))
        }
    }

    /// get the source module the plugin belongs to.
    ///
    /// # Returns
    ///
    /// the source of the plugin
    #[doc(alias = "gst_plugin_get_source")]
    #[doc(alias = "get_source")]
    pub fn source(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_source(self.to_glib_none().0)) }
    }

    ///
    /// # Returns
    ///
    /// an array of plugin status error messages, or NULL
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_get_status_errors")]
    #[doc(alias = "get_status_errors")]
    pub fn status_errors(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gst_plugin_get_status_errors(
                self.to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// an array of plugin status info messages, or NULL
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_get_status_infos")]
    #[doc(alias = "get_status_infos")]
    pub fn status_infos(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gst_plugin_get_status_infos(
                self.to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// an array of plugin status warning messages, or NULL
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_get_status_warnings")]
    #[doc(alias = "get_status_warnings")]
    pub fn status_warnings(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gst_plugin_get_status_warnings(
                self.to_glib_none().0,
            ))
        }
    }

    /// get the version of the plugin
    ///
    /// # Returns
    ///
    /// the version of the plugin
    #[doc(alias = "gst_plugin_get_version")]
    #[doc(alias = "get_version")]
    pub fn version(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_version(self.to_glib_none().0)) }
    }

    /// queries if the plugin is loaded into memory
    ///
    /// # Returns
    ///
    /// [`true`] is loaded, [`false`] otherwise
    #[doc(alias = "gst_plugin_is_loaded")]
    pub fn is_loaded(&self) -> bool {
        unsafe { from_glib(ffi::gst_plugin_is_loaded(self.to_glib_none().0)) }
    }

    /// Loads `self`. Note that the *return value* is the loaded plugin; `self` is
    /// untouched. The normal use pattern of this function goes like this:
    ///
    ///
    /// ```text
    /// GstPlugin *loaded_plugin;
    /// loaded_plugin = gst_plugin_load (plugin);
    /// // presumably, we're no longer interested in the potentially-unloaded plugin
    /// gst_object_unref (plugin);
    /// plugin = loaded_plugin;
    /// ```
    ///
    /// # Returns
    ///
    /// a reference to a loaded plugin, or
    /// [`None`] on error.
    #[doc(alias = "gst_plugin_load")]
    pub fn load(&self) -> Result<Plugin, glib::BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::gst_plugin_load(self.to_glib_none().0))
                .ok_or_else(|| glib::bool_error!("Failed to load plugin"))
        }
    }

    /// Adds plugin specific data to cache. Passes the ownership of the structure to
    /// the `self`.
    ///
    /// The cache is flushed every time the registry is rebuilt.
    /// ## `cache_data`
    /// a structure containing the data to cache
    #[doc(alias = "gst_plugin_set_cache_data")]
    pub fn set_cache_data(&self, cache_data: Structure) {
        unsafe {
            ffi::gst_plugin_set_cache_data(self.to_glib_none().0, cache_data.into_glib_ptr());
        }
    }

    /// Load the named plugin. Refs the plugin.
    /// ## `name`
    /// name of plugin to load
    ///
    /// # Returns
    ///
    /// a reference to a loaded plugin, or
    /// [`None`] on error.
    #[doc(alias = "gst_plugin_load_by_name")]
    pub fn load_by_name(name: &str) -> Result<Plugin, glib::BoolError> {
        assert_initialized_main_thread!();
        unsafe {
            Option::<_>::from_glib_full(ffi::gst_plugin_load_by_name(name.to_glib_none().0))
                .ok_or_else(|| glib::bool_error!("Failed to load plugin"))
        }
    }

    /// Loads the given plugin and refs it. Caller needs to unref after use.
    /// ## `filename`
    /// the plugin filename to load
    ///
    /// # Returns
    ///
    /// a reference to the existing loaded GstPlugin, a
    /// reference to the newly-loaded GstPlugin, or [`None`] if an error occurred.
    #[doc(alias = "gst_plugin_load_file")]
    pub fn load_file(filename: impl AsRef<std::path::Path>) -> Result<Plugin, glib::Error> {
        assert_initialized_main_thread!();
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gst_plugin_load_file(filename.as_ref().to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

impl std::fmt::Display for Plugin {
    #[inline]
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        f.write_str(&self.plugin_name())
    }
}

unsafe impl Send for Plugin {}
unsafe impl Sync for Plugin {}