1/* GStreamer base utils library plugin install support for applications
2 * Copyright (C) 2007 Tim-Philipp Müller <tim centricular net>
3 * Copyright (C) 2006 Ryan Lortie <desrt desrt ca>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
14 *
15 * You should have received a copy of the GNU Library General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19 */
20
21#ifndef __GST_PB_UTILS_INSTALL_PLUGINS_H__
22#define __GST_PB_UTILS_INSTALL_PLUGINS_H__
23
24#include <gst/gst.h>
25#include <gst/pbutils/pbutils-prelude.h>
26
27G_BEGIN_DECLS
28
29/*
30 * functions for use by applications to initiate installation of missing plugins
31 */
32
33/**
34 * GstInstallPluginsReturn:
35 * @GST_INSTALL_PLUGINS_SUCCESS: all of the requested plugins could be
36 * installed
37 * @GST_INSTALL_PLUGINS_NOT_FOUND: no appropriate installation candidate for
38 * any of the requested plugins could be found. Only return this if nothing
39 * has been installed. Return #GST_INSTALL_PLUGINS_PARTIAL_SUCCESS if
40 * some (but not all) of the requested plugins could be installed.
41 * @GST_INSTALL_PLUGINS_ERROR: an error occured during the installation. If
42 * this happens, the user has already seen an error message and another
43 * one should not be displayed
44 * @GST_INSTALL_PLUGINS_CRASHED: the installer had an unclean exit code
45 * (ie. death by signal)
46 * @GST_INSTALL_PLUGINS_PARTIAL_SUCCESS: some of the requested plugins could
47 * be installed, but not all
48 * @GST_INSTALL_PLUGINS_USER_ABORT: the user has aborted the installation
49 * @GST_INSTALL_PLUGINS_INVALID: the helper returned an invalid status code
50 * @GST_INSTALL_PLUGINS_STARTED_OK: returned by gst_install_plugins_async() to
51 * indicate that everything went fine so far and the provided callback
52 * will be called with the result of the installation later
53 * @GST_INSTALL_PLUGINS_INTERNAL_FAILURE: some internal failure has
54 * occured when trying to start the installer
55 * @GST_INSTALL_PLUGINS_HELPER_MISSING: the helper script to call the
56 * actual installer is not installed
57 * @GST_INSTALL_PLUGINS_INSTALL_IN_PROGRESS: a previously-started plugin
58 * installation is still in progress, try again later
59 *
60 * Result codes returned by gst_install_plugins_async() and
61 * gst_install_plugins_sync(), and also the result code passed to the
62 * #GstInstallPluginsResultFunc specified with gst_install_plugins_async().
63 *
64 * These codes indicate success or failure of starting an external installer
65 * program and to what extent the requested plugins could be installed.
66 */
67typedef enum {
68 /* Return codes from the installer. Returned by gst_install_plugins_sync(),
69 * or passed as result code to your #GstInstallPluginsResultFunc */
70 GST_INSTALL_PLUGINS_SUCCESS = 0,
71 GST_INSTALL_PLUGINS_NOT_FOUND = 1,
72 GST_INSTALL_PLUGINS_ERROR = 2,
73 GST_INSTALL_PLUGINS_PARTIAL_SUCCESS = 3,
74 GST_INSTALL_PLUGINS_USER_ABORT = 4,
75
76 /* Returned by gst_install_plugins_sync(), or passed as result code to your
77 * #GstInstallPluginsResultFunc */
78 GST_INSTALL_PLUGINS_CRASHED = 100,
79 GST_INSTALL_PLUGINS_INVALID,
80
81 /* Return codes from starting the external helper, may be returned by both
82 * gst_install_plugins_sync() and gst_install_plugins_async(), but should
83 * never be seen by a #GstInstallPluginsResultFunc */
84 GST_INSTALL_PLUGINS_STARTED_OK = 200,
85 GST_INSTALL_PLUGINS_INTERNAL_FAILURE,
86 GST_INSTALL_PLUGINS_HELPER_MISSING,
87 GST_INSTALL_PLUGINS_INSTALL_IN_PROGRESS
88} GstInstallPluginsReturn;
89
90/**
91 * GstInstallPluginsContext:
92 *
93 * Opaque context structure for the plugin installation. Use the provided
94 * API to set details on it.
95 */
96
97#define GST_TYPE_INSTALL_PLUGINS_CONTEXT (gst_install_plugins_context_get_type())
98
99typedef struct _GstInstallPluginsContext GstInstallPluginsContext;
100
101GST_PBUTILS_API
102GstInstallPluginsContext * gst_install_plugins_context_new (void);
103
104GST_PBUTILS_API
105GstInstallPluginsContext * gst_install_plugins_context_copy (GstInstallPluginsContext * ctx);
106GST_PBUTILS_API
107void gst_install_plugins_context_free (GstInstallPluginsContext * ctx);
108
109GST_PBUTILS_API
110void gst_install_plugins_context_set_confirm_search (GstInstallPluginsContext * ctx,
111 gboolean confirm_search);
112
113GST_PBUTILS_API
114void gst_install_plugins_context_set_desktop_id (GstInstallPluginsContext * ctx,
115 const gchar * desktop_id);
116
117GST_PBUTILS_API
118void gst_install_plugins_context_set_startup_notification_id (GstInstallPluginsContext * ctx,
119 const gchar * startup_id);
120
121GST_PBUTILS_API
122void gst_install_plugins_context_set_xid (GstInstallPluginsContext * ctx,
123 guint xid);
124
125GST_PBUTILS_API
126GType gst_install_plugins_context_get_type (void);
127
128/**
129 * GstInstallPluginsResultFunc:
130 * @result: whether the installation of the requested plugins succeeded or not
131 * @user_data: the user data passed to gst_install_plugins_async()
132 *
133 * The prototype of the callback function that will be called once the
134 * external plugin installer program has returned. You only need to provide
135 * a callback function if you are using the asynchronous interface.
136 */
137typedef void (*GstInstallPluginsResultFunc) (GstInstallPluginsReturn result,
138 gpointer user_data);
139
140GST_PBUTILS_API
141GstInstallPluginsReturn gst_install_plugins_async (const gchar * const * details,
142 GstInstallPluginsContext * ctx,
143 GstInstallPluginsResultFunc func,
144 gpointer user_data);
145
146GST_PBUTILS_API
147GstInstallPluginsReturn gst_install_plugins_sync (const gchar * const * details,
148 GstInstallPluginsContext * ctx);
149
150GST_PBUTILS_API
151const gchar * gst_install_plugins_return_get_name (GstInstallPluginsReturn ret);
152
153GST_PBUTILS_API
154gboolean gst_install_plugins_installation_in_progress (void);
155
156GST_PBUTILS_API
157gboolean gst_install_plugins_supported (void);
158
159#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
160G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstInstallPluginsContext, gst_install_plugins_context_free)
161#endif
162
163G_END_DECLS
164
165#endif /* __GST_PB_UTILS_INSTALL_PLUGINS_H__ */
166
167