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_plugin_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 #ifdef __SYMBIAN32__

   104 IMPORT_C

   105 #endif

   106 

   107 

   108 GstInstallPluginsContext * gst_install_plugins_context_new (void);

   109 #ifdef __SYMBIAN32__

   110 IMPORT_C

   111 #endif

   112 

   113 

   114 void   gst_install_plugins_context_free    (GstInstallPluginsContext * ctx);

   115 #ifdef __SYMBIAN32__

   116 IMPORT_C

   117 #endif

   118 

   119 

   120 void   gst_install_plugins_context_set_xid (GstInstallPluginsContext * ctx,

   121                                             guint                      xid);

   122 #ifdef __SYMBIAN32__

   123 IMPORT_C

   124 #endif

   125 

   126 

   127 GType  gst_install_plugins_context_get_type (void);

   128 

   129 /**

   130  * GstInstallPluginsResultFunc:

   131  * @result: whether the installation of the requested plugins succeeded or not

   132  * @user_data: the user data passed to gst_install_plugins_async()

   133  *

   134  * The prototype of the callback function that will be called once the

   135  * external plugin installer program has returned. You only need to provide

   136  * a callback function if you are using the asynchronous interface.

   137  *

   138  * Since: 0.10.12

   139  */

   140 typedef void (*GstInstallPluginsResultFunc) (GstInstallPluginsReturn  result,

   141                                              gpointer                 user_data);

   142 #ifdef __SYMBIAN32__

   143 IMPORT_C

   144 #endif

   145 

   146 

   147 GstInstallPluginsReturn  gst_install_plugins_async (gchar                    ** details,

   148                                                     GstInstallPluginsContext  * ctx,

   149                                                     GstInstallPluginsResultFunc func,

   150                                                     gpointer                    user_data);

   151 

   152 GstInstallPluginsReturn  gst_install_plugins_sync  (gchar                    ** details,

   153                                                     GstInstallPluginsContext  * ctx);

   154 #ifdef __SYMBIAN32__

   155 IMPORT_C

   156 #endif

   157 

   158 

   159 const gchar * gst_install_plugins_return_get_name (GstInstallPluginsReturn ret);

   160 #ifdef __SYMBIAN32__

   161 IMPORT_C

   162 #endif

   163 

   164 

   165 gboolean      gst_install_plugins_installation_in_progress (void);

   166 #ifdef __SYMBIAN32__

   167 IMPORT_C

   168 #endif

   169 

   170 

   171 gboolean      gst_install_plugins_supported (void);

   172 

   173 G_END_DECLS

   174 

   175 #endif /* __GST_PB_UTILS_INSTALL_PLUGINS_H__ */

   176