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 typedef enum {
  67   /* Return codes from the installer. Returned by gst_install_plugins_sync(),
  68    * or passed as result code to your #GstInstallPluginsResultFunc */
  69   GST_INSTALL_PLUGINS_SUCCESS = 0,
  70   GST_INSTALL_PLUGINS_NOT_FOUND = 1,
  71   GST_INSTALL_PLUGINS_ERROR = 2,
  72   GST_INSTALL_PLUGINS_PARTIAL_SUCCESS = 3,
  73   GST_INSTALL_PLUGINS_USER_ABORT = 4,
  74
  75   /* Returned by gst_install_plugins_sync(), or passed as result code to your
  76    * #GstInstallPluginsResultFunc */
  77   GST_INSTALL_PLUGINS_CRASHED = 100,
  78   GST_INSTALL_PLUGINS_INVALID,
  79
  80   /* Return codes from starting the external helper, may be returned by both
  81    * gst_install_plugins_sync() and gst_install_plugins_async(), but should
  82    * never be seen by a #GstInstallPluginsResultFunc */
  83   GST_INSTALL_PLUGINS_STARTED_OK = 200,
  84   GST_INSTALL_PLUGINS_INTERNAL_FAILURE,
  85   GST_INSTALL_PLUGINS_HELPER_MISSING,
  86   GST_INSTALL_PLUGINS_INSTALL_IN_PROGRESS
  87 } GstInstallPluginsReturn;
  88
  89 /**
  90  * GstInstallPluginsContext:
  91  *
  92  * Opaque context structure for the plugin installation. Use the provided
  93  * API to set details on it.
  94  */
  95
  96 #define GST_TYPE_INSTALL_PLUGINS_CONTEXT        (gst_install_plugins_context_get_type())
  97
  98 typedef struct _GstInstallPluginsContext GstInstallPluginsContext;
  99
 100 GstInstallPluginsContext * gst_install_plugins_context_new (void);
 101
 102 void   gst_install_plugins_context_free    (GstInstallPluginsContext * ctx);
 103
 104 void   gst_install_plugins_context_set_xid (GstInstallPluginsContext * ctx,
 105                                             guint                      xid);
 106
 107 GType  gst_install_plugins_context_get_type (void);
 108
 109 /**
 110  * GstInstallPluginsResultFunc:
 111  * @result: whether the installation of the requested plugins succeeded or not
 112  * @user_data: the user data passed to gst_install_plugins_async()
 113  *
 114  * The prototype of the callback function that will be called once the
 115  * external plugin installer program has returned. You only need to provide
 116  * a callback function if you are using the asynchronous interface.
 117  */
 118 typedef void (*GstInstallPluginsResultFunc) (GstInstallPluginsReturn  result,
 119                                              gpointer                 user_data);
 120
 121 GstInstallPluginsReturn  gst_install_plugins_async (const gchar * const * details,
 122                                                     GstInstallPluginsContext  * ctx,
 123                                                     GstInstallPluginsResultFunc func,
 124                                                     gpointer                    user_data);
 125
 126 GstInstallPluginsReturn  gst_install_plugins_sync  (const gchar * const       * details,
 127                                                     GstInstallPluginsContext  * ctx);
 128
 129 const gchar * gst_install_plugins_return_get_name (GstInstallPluginsReturn ret);
 130
 131 gboolean      gst_install_plugins_installation_in_progress (void);
 132
 133 gboolean      gst_install_plugins_supported (void);
 134
 135 G_END_DECLS
 136
 137 #endif /* __GST_PB_UTILS_INSTALL_PLUGINS_H__ */
 138