gst-libs/gst/pbutils/install-plugins.h

   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., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #ifndef __GST_PB_UTILS_INSTALL_PLUGINS_H__
  22 #define __GST_PB_UTILS_INSTALL_PLUGINS_H__
  23
  24 #include <glib-object.h>
  25
  26 G_BEGIN_DECLS
  27
  28 /*
  29  * functions for use by applications to initiate installation of missing plugins
  30  */
  31
  32 /**
  33  * GstInstallPluginsReturn:
  34  * @GST_INSTALL_PLUGINS_SUCCESS: all of the requested plugins could be
  35  *     installed
  36  * @GST_INSTALL_PLUGINS_NOT_FOUND: no appropriate installation candidate for
  37  *     any of the requested plugins could be found. Only return this if nothing
  38  *     has been installed. Return #GST_INSTALL_PLUGINS_PARTIAL_SUCCESS if
  39  *     some (but not all) of the requested plugins could be installed.
  40  * @GST_INSTALL_PLUGINS_ERROR: an error occured during the installation. If
  41  *     this happens, the  user has already seen an error message and another
  42  *     one should not be displayed
  43  * @GST_INSTALL_PLUGINS_CRASHED: the installer had an unclean exit code
  44  *     (ie. death by signal)
  45  * @GST_INSTALL_PLUGINS_PARTIAL_SUCCESS: some of the requested plugins could
  46  *     be installed, but not all
  47  * @GST_INSTALL_PLUGINS_USER_ABORT: the user has aborted the installation
  48  * @GST_INSTALL_PLUGINS_INVALID: the helper returned an invalid status code
  49  * @GST_INSTALL_PLUGINS_STARTED_OK: returned by gst_install_plugins_async() to
  50  *     indicate that everything went fine so far and the provided callback
  51  *     will be called with the result of the installation later
  52  * @GST_INSTALL_PLUGINS_INTERNAL_FAILURE: some internal failure has
  53  *     occured when trying to start the installer
  54  * @GST_INSTALL_PLUGINS_HELPER_MISSING: the helper script to call the
  55  *     actual installer is not installed
  56  * @GST_INSTALL_PLUGINS_INSTALL_IN_PROGRESS: a previously-started plugin
  57  *     installation is still in progress, try again later
  58  *
  59  * Result codes returned by gst_install_plugins_async() and
  60  * gst_install_plugins_sync(), and also the result code passed to the
  61  * #GstInstallPluginsResultFunc specified with gst_install_plugins_async().
  62  *
  63  * These codes indicate success or failure of starting an external installer
  64  * program and to what extent the requested plugins could be installed.
  65  *
  66  * Since: 0.10.12
  67  */
  68 typedef enum {
  69   /* Return codes from the installer. Returned by gst_install_plugins_sync(),
  70    * or passed as result code to your #GstInstallPluginsResultFunc */
  71   GST_INSTALL_PLUGINS_SUCCESS = 0,
  72   GST_INSTALL_PLUGINS_NOT_FOUND = 1,
  73   GST_INSTALL_PLUGINS_ERROR = 2,
  74   GST_INSTALL_PLUGINS_PARTIAL_SUCCESS = 3,
  75   GST_INSTALL_PLUGINS_USER_ABORT = 4,
  76
  77   /* Returned by gst_install_plugins_sync(), or passed as result code to your
  78    * #GstInstallPluginsResultFunc */
  79   GST_INSTALL_PLUGINS_CRASHED = 100,
  80   GST_INSTALL_PLUGINS_INVALID,
  81
  82   /* Return codes from starting the external helper, may be returned by both
  83    * gst_install_plugins_sync() and gst_install_plugins_async(), but should
  84    * never be seen by a #GstInstallPluginsResultFunc */
  85   GST_INSTALL_PLUGINS_STARTED_OK = 200,
  86   GST_INSTALL_PLUGINS_INTERNAL_FAILURE,
  87   GST_INSTALL_PLUGINS_HELPER_MISSING,
  88   GST_INSTALL_PLUGINS_INSTALL_IN_PROGRESS
  89 } GstInstallPluginsReturn;
  90
  91 /**
  92  * GstInstallPluginsContext:
  93  *
  94  * Opaque context structure for the plugin installation. Use the provided
  95  * API to set details on it.
  96  *
  97  * Since: 0.10.12
  98  */
  99
 100 #define GST_TYPE_INSTALL_PLUGINS_CONTEXT        (gst_install_plugins_context_get_type())
 101
 102 typedef struct _GstInstallPluginsContext GstInstallPluginsContext;
 103
 104 GstInstallPluginsContext * gst_install_plugins_context_new (void);
 105
 106 void   gst_install_plugins_context_free    (GstInstallPluginsContext * ctx);
 107
 108 void   gst_install_plugins_context_set_xid (GstInstallPluginsContext * ctx,
 109                                             guint                      xid);
 110
 111 GType  gst_install_plugins_context_get_type (void);
 112
 113 /**
 114  * GstInstallPluginsResultFunc:
 115  * @result: whether the installation of the requested plugins succeeded or not
 116  * @user_data: the user data passed to gst_install_plugins_async()
 117  *
 118  * The prototype of the callback function that will be called once the
 119  * external plugin installer program has returned. You only need to provide
 120  * a callback function if you are using the asynchronous interface.
 121  *
 122  * Since: 0.10.12
 123  */
 124 typedef void (*GstInstallPluginsResultFunc) (GstInstallPluginsReturn  result,
 125                                              gpointer                 user_data);
 126
 127 GstInstallPluginsReturn  gst_install_plugins_async (gchar                    ** details,
 128                                                     GstInstallPluginsContext  * ctx,
 129                                                     GstInstallPluginsResultFunc func,
 130                                                     gpointer                    user_data);
 131
 132 GstInstallPluginsReturn  gst_install_plugins_sync  (gchar                    ** details,
 133                                                     GstInstallPluginsContext  * ctx);
 134
 135 const gchar * gst_install_plugins_return_get_name (GstInstallPluginsReturn ret);
 136
 137 gboolean      gst_install_plugins_installation_in_progress (void);
 138
 139 gboolean      gst_install_plugins_supported (void);
 140
 141 G_END_DECLS
 142
 143 #endif /* __GST_PB_UTILS_INSTALL_PLUGINS_H__ */
 144