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 27 G_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 */ 67 typedef 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 99 typedef struct _GstInstallPluginsContext GstInstallPluginsContext; 100 101 GST_PBUTILS_API 102 GstInstallPluginsContext * gst_install_plugins_context_new (void); 103 104 GST_PBUTILS_API 105 GstInstallPluginsContext * gst_install_plugins_context_copy (GstInstallPluginsContext * ctx); 106 GST_PBUTILS_API 107 void gst_install_plugins_context_free (GstInstallPluginsContext * ctx); 108 109 GST_PBUTILS_API 110 void gst_install_plugins_context_set_confirm_search (GstInstallPluginsContext * ctx, 111 gboolean confirm_search); 112 113 GST_PBUTILS_API 114 void gst_install_plugins_context_set_desktop_id (GstInstallPluginsContext * ctx, 115 const gchar * desktop_id); 116 117 GST_PBUTILS_API 118 void gst_install_plugins_context_set_startup_notification_id (GstInstallPluginsContext * ctx, 119 const gchar * startup_id); 120 121 GST_PBUTILS_API 122 void gst_install_plugins_context_set_xid (GstInstallPluginsContext * ctx, 123 guint xid); 124 125 GST_PBUTILS_API 126 GType 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 */ 137 typedef void (*GstInstallPluginsResultFunc) (GstInstallPluginsReturn result, 138 gpointer user_data); 139 140 GST_PBUTILS_API 141 GstInstallPluginsReturn gst_install_plugins_async (const gchar * const * details, 142 GstInstallPluginsContext * ctx, 143 GstInstallPluginsResultFunc func, 144 gpointer user_data); 145 146 GST_PBUTILS_API 147 GstInstallPluginsReturn gst_install_plugins_sync (const gchar * const * details, 148 GstInstallPluginsContext * ctx); 149 150 GST_PBUTILS_API 151 const gchar * gst_install_plugins_return_get_name (GstInstallPluginsReturn ret); 152 153 GST_PBUTILS_API 154 gboolean gst_install_plugins_installation_in_progress (void); 155 156 GST_PBUTILS_API 157 gboolean gst_install_plugins_supported (void); 158 159 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC 160 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstInstallPluginsContext, gst_install_plugins_context_free) 161 #endif 162 163 G_END_DECLS 164 165 #endif /* __GST_PB_UTILS_INSTALL_PLUGINS_H__ */ 166 167