| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>gstpbutilsinstallplugins: GStreamer Base Plugins 1.0 Library Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="GStreamer Base Plugins 1.0 Library Reference Manual"> |
| <link rel="up" href="gstreamer-base-utils.html" title="Base Utils Library"> |
| <link rel="prev" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html" title="gstpbutilsmissingplugins"> |
| <link rel="next" href="gst-plugins-base-libs-gstdiscoverer.html" title="gstdiscoverer"> |
| <meta name="generator" content="GTK-Doc V1.25 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"> |
| <a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> |
| <a href="#gst-plugins-base-libs-gstpbutilsinstallplugins.description" class="shortcut">Description</a></span> |
| </td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="gstreamer-base-utils.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <td><a accesskey="p" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> |
| <td><a accesskey="n" href="gst-plugins-base-libs-gstdiscoverer.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="refentry"> |
| <a name="gst-plugins-base-libs-gstpbutilsinstallplugins"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle"><a name="gst-plugins-base-libs-gstpbutilsinstallplugins.top_of_page"></a>gstpbutilsinstallplugins</span></h2> |
| <p>gstpbutilsinstallplugins — Missing plugin installation support for applications</p> |
| </td> |
| <td class="gallery_image" valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsect1"> |
| <a name="gst-plugins-base-libs-gstpbutilsinstallplugins.functions"></a><h2>Functions</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="functions_return"> |
| <col class="functions_name"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <span class="c_punctuation">(</span><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsResultFunc" title="GstInstallPluginsResultFunc ()">*GstInstallPluginsResultFunc</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsReturn" title="enum GstInstallPluginsReturn"><span class="returnvalue">GstInstallPluginsReturn</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-async" title="gst_install_plugins_async ()">gst_install_plugins_async</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsReturn" title="enum GstInstallPluginsReturn"><span class="returnvalue">GstInstallPluginsReturn</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-sync" title="gst_install_plugins_sync ()">gst_install_plugins_sync</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-return-get-name" title="gst_install_plugins_return_get_name ()">gst_install_plugins_return_get_name</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-installation-in-progress" title="gst_install_plugins_installation_in_progress ()">gst_install_plugins_installation_in_progress</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-supported" title="gst_install_plugins_supported ()">gst_install_plugins_supported</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="returnvalue">GstInstallPluginsContext</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-context-new" title="gst_install_plugins_context_new ()">gst_install_plugins_context_new</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-context-free" title="gst_install_plugins_context_free ()">gst_install_plugins_context_free</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-context-set-xid" title="gst_install_plugins_context_set_xid ()">gst_install_plugins_context_set_xid</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-context-set-confirm-search" title="gst_install_plugins_context_set_confirm_search ()">gst_install_plugins_context_set_confirm_search</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-context-set-desktop-id" title="gst_install_plugins_context_set_desktop_id ()">gst_install_plugins_context_set_desktop_id</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-context-set-startup-notification-id" title="gst_install_plugins_context_set_startup_notification_id ()">gst_install_plugins_context_set_startup_notification_id</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="gst-plugins-base-libs-gstpbutilsinstallplugins.other"></a><h2>Types and Values</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="name"> |
| <col class="description"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="datatype_keyword">enum</td> |
| <td class="function_name"><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsReturn" title="enum GstInstallPluginsReturn">GstInstallPluginsReturn</a></td> |
| </tr> |
| <tr> |
| <td class="datatype_keyword"> </td> |
| <td class="function_name"><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext">GstInstallPluginsContext</a></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="gst-plugins-base-libs-gstpbutilsinstallplugins.includes"></a><h2>Includes</h2> |
| <pre class="synopsis">#include <gst/pbutils/install-plugins.h> |
| </pre> |
| </div> |
| <div class="refsect1"> |
| <a name="gst-plugins-base-libs-gstpbutilsinstallplugins.description"></a><h2>Description</h2> |
| <div class="refsect2"> |
| <a name="id-1.2.14.8.6.2"></a><h3>Overview</h3> |
| <p> |
| Using this API, applications can request the installation of missing |
| GStreamer plugins. These may be missing decoders/demuxers or encoders/muxers |
| for a certain format, sources or sinks for a certain URI protocol |
| (e.g. 'http'), or certain elements known by their element factory name |
| ('audioresample'). |
| </p> |
| <p> |
| Whether plugin installation is supported or not depends on the operating |
| system and/or distribution in question. The vendor of the operating system |
| needs to make sure the necessary hooks and mechanisms are in place for |
| plugin installation to work. See below for more detailed information. |
| </p> |
| <p> |
| From the application perspective, plugin installation is usually triggered |
| either |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"><p> |
| when the application itself has found that it wants or needs to install a |
| certain element |
| </p></li> |
| <li class="listitem"><p> |
| when the application has been notified by an element (such as playbin or |
| decodebin) that one or more plugins are missing <span class="emphasis"><em>and</em></span> |
| the application has decided that it wants to install one or more of those |
| missing plugins |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| <p> |
| The install functions in this section all take one or more 'detail strings'. |
| These detail strings contain information about the type of plugin that |
| needs to be installed (decoder, encoder, source, sink, or named element), |
| and some additional information such GStreamer version used and a |
| human-readable description of the component to install for user dialogs. |
| </p> |
| <p> |
| Applications should not concern themselves with the composition of the |
| string itself. They should regard the string as if it was a shared secret |
| between GStreamer and the plugin installer application. |
| </p> |
| <p> |
| Detail strings can be obtained using the function |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html#gst-missing-plugin-message-get-installer-detail" title="gst_missing_plugin_message_get_installer_detail ()"><code class="function">gst_missing_plugin_message_get_installer_detail()</code></a> on a missing-plugin |
| message. Such a message will either have been found by the application on |
| a pipeline's <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstBus.html#GstBus-struct"><span class="type">GstBus</span></a>, or the application will have created it itself using |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html#gst-missing-element-message-new" title="gst_missing_element_message_new ()"><code class="function">gst_missing_element_message_new()</code></a>, <a class="link" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html#gst-missing-decoder-message-new" title="gst_missing_decoder_message_new ()"><code class="function">gst_missing_decoder_message_new()</code></a>, |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html#gst-missing-encoder-message-new" title="gst_missing_encoder_message_new ()"><code class="function">gst_missing_encoder_message_new()</code></a>, <a class="link" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html#gst-missing-uri-sink-message-new" title="gst_missing_uri_sink_message_new ()"><code class="function">gst_missing_uri_sink_message_new()</code></a>, or |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html#gst-missing-uri-source-message-new" title="gst_missing_uri_source_message_new ()"><code class="function">gst_missing_uri_source_message_new()</code></a>. |
| </p> |
| <p> |
| For each GStreamer element/plugin/component that should be installed, the |
| application needs one of those 'installer detail' string mentioned in the |
| previous section. This string can be obtained, as already mentioned above, |
| from a missing-plugin message using the function |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html#gst-missing-plugin-message-get-installer-detail" title="gst_missing_plugin_message_get_installer_detail ()"><code class="function">gst_missing_plugin_message_get_installer_detail()</code></a>. The missing-plugin |
| message is either posted by another element and then found on the bus |
| by the application, or the application has created it itself as described |
| above. |
| </p> |
| <p> |
| The application will then call <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-async" title="gst_install_plugins_async ()"><code class="function">gst_install_plugins_async()</code></a>, passing a |
| NULL-terminated array of installer detail strings, and a function that |
| should be called when the installation of the plugins has finished |
| (successfully or not). Optionally, a <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a> created |
| with <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-context-new" title="gst_install_plugins_context_new ()"><code class="function">gst_install_plugins_context_new()</code></a> may be passed as well. This way |
| additional optional arguments like the application window's XID can be |
| passed to the external installer application. |
| </p> |
| <p> |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-async" title="gst_install_plugins_async ()"><code class="function">gst_install_plugins_async()</code></a> will return almost immediately, with the |
| return code indicating whether plugin installation was started or not. |
| If the necessary hooks for plugin installation are in place and an |
| external installer application has in fact been called, the passed in |
| function will be called with a result code as soon as the external installer |
| has finished. If the result code indicates that new plugins have been |
| installed, the application will want to call <a href="/usr/share/gtk-doc/html/gstreamer-1.0gstreamer-Gst.html#gst-update-registry"><code class="function">gst_update_registry()</code></a> so the |
| run-time plugin registry is updated and the new plugins are made available |
| to the application. |
| </p> |
| <div class="note"> |
| A Gtk/GLib main loop must be running in order for the result function to |
| be called when the external installer has finished. If this is not the case, |
| make sure to regularly call |
| <pre class="programlisting"> |
| g_main_context_iteration (NULL,FALSE); |
| </pre> |
| from your code. |
| </div> |
| <p> |
| </p> |
| <p> |
| <span class="emphasis"><em>1. Installer hook</em></span> |
| </p> |
| <p> |
| When GStreamer applications initiate plugin installation via |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-async" title="gst_install_plugins_async ()"><code class="function">gst_install_plugins_async()</code></a> or <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-sync" title="gst_install_plugins_sync ()"><code class="function">gst_install_plugins_sync()</code></a>, a pre-defined |
| helper application will be called. |
| </p> |
| <p> |
| The exact path of the helper application to be called is set at compile |
| time, usually by the <code class="literal">./configure</code> script based on the |
| install prefix. For a normal package build into the <code class="literal">/usr</code> |
| prefix, this will usually default to |
| <code class="filename">/usr/libexec/gst-install-plugins-helper</code> or |
| <code class="filename">/usr/lib/gst-install-plugins-helper</code>. |
| </p> |
| <p> |
| Vendors/distros who want to support GStreamer plugin installation should |
| either provide such a helper script/application or use the |
| <code class="literal">./configure</code> option |
| <code class="literal">--with-install-plugins-helper=/path/to/installer</code> to |
| make GStreamer call an installer of their own directly. |
| </p> |
| <p> |
| It is strongly recommended that vendors provide a small helper application |
| as interlocutor to the real installer though, even more so if command line |
| argument munging is required to transform the command line arguments |
| passed by GStreamer to the helper application into arguments that are |
| understood by the real installer. |
| </p> |
| <p> |
| The helper application path defined at compile time can be overriden at |
| runtime by setting the <code class="envar">GST_INSTALL_PLUGINS_HELPER</code> |
| environment variable. This can be useful for testing/debugging purposes. |
| </p> |
| <p> |
| <span class="emphasis"><em>2. Arguments passed to the install helper</em></span> |
| </p> |
| <p> |
| GStreamer will pass the following arguments to the install helper (this is |
| in addition to the path of the executable itself, which is by convention |
| argv[0]): |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"><p> |
| none to many optional arguments in the form of |
| <code class="literal">--foo-bar=val</code>. Example: |
| <code class="literal">--transient-for=XID</code> where XID is the X Window ID of |
| the main window of the calling application (so the installer can make |
| itself transient to that window). Unknown optional arguments should |
| be ignored by the installer. |
| </p></li> |
| <li class="listitem"><p> |
| one 'installer detail string' argument for each plugin to be installed; |
| these strings will have a <code class="literal">gstreamer</code> prefix; the |
| exact format of the detail string is explained below |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| <p> |
| <span class="emphasis"><em>3. Detail string describing the missing plugin</em></span> |
| </p> |
| <p> |
| The string is in UTF-8 encoding and is made up of several fields, separated |
| by '|' characters (but neither the first nor the last character is a '|'). |
| The fields are: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"> |
| <p> |
| plugin system identifier, ie. "gstreamer" |
| </p> |
| <p> |
| This identifier determines the format of the rest of the detail string. |
| Automatic plugin installers should not process detail strings with |
| unknown identifiers. This allows other plugin-based libraries to use |
| the same mechanism for their automatic plugin installation needs, or |
| for the format to be changed should it turn out to be insufficient. |
| </p> |
| </li> |
| <li class="listitem"> |
| <p> |
| plugin system version, e.g. "0.10" |
| </p> |
| <p> |
| This is required so that when there is a GStreamer-0.12 or GStreamer-1.0 |
| at some point in future, the different major versions can still co-exist |
| and use the same plugin install mechanism in the same way. |
| </p> |
| </li> |
| <li class="listitem"> |
| <p> |
| application identifier, e.g. "totem" |
| </p> |
| <p> |
| This may also be in the form of "pid/12345" if the program name can't |
| be obtained for some reason. |
| </p> |
| </li> |
| <li class="listitem"><p> |
| human-readable localised description of the required component, |
| e.g. "Vorbis audio decoder" |
| </p></li> |
| <li class="listitem"> |
| <p> |
| identifier string for the required component (see below for details about |
| how to map this to the package/plugin that needs installing), e.g. |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> |
| <li class="listitem"><p> |
| urisource-$(PROTOCOL_REQUIRED), e.g. urisource-http or urisource-mms |
| </p></li> |
| <li class="listitem"><p> |
| element-$(ELEMENT_REQUIRED), e.g. element-videoconvert |
| </p></li> |
| <li class="listitem"> |
| <p> |
| decoder-$(CAPS_REQUIRED), e.g. (do read below for more details!): |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: square; "> |
| <li class="listitem"><p>decoder-audio/x-vorbis</p></li> |
| <li class="listitem"><p>decoder-application/ogg</p></li> |
| <li class="listitem"><p>decoder-audio/mpeg, mpegversion=(int)4</p></li> |
| <li class="listitem"><p>decoder-video/mpeg, systemstream=(boolean)true, mpegversion=(int)2</p></li> |
| </ul></div> |
| <p> |
| </p> |
| </li> |
| <li class="listitem"><p> |
| encoder-$(CAPS_REQUIRED), e.g. encoder-audio/x-vorbis |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| </li> |
| <li class="listitem"><p> |
| optional further fields not yet specified |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| <p> |
| An entire ID string might then look like this, for example: |
| <code class="literal"> |
| gstreamer|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis |
| </code> |
| </p> |
| <p> |
| Plugin installers parsing this ID string should expect further fields also |
| separated by '|' symbols and either ignore them, warn the user, or error |
| out when encountering them. |
| </p> |
| <p> |
| Those unfamiliar with the GStreamer 'caps' system should note a few things |
| about the caps string used in the above decoder/encoder case: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"><p> |
| the first part ("video/mpeg") of the caps string is a GStreamer media |
| type and <span class="emphasis"><em>not</em></span> a MIME type. Wherever possible, the |
| GStreamer media type will be the same as the corresponding MIME type, |
| but often it is not. |
| </p></li> |
| <li class="listitem"><p> |
| a caps string may or may not have additional comma-separated fields |
| of various types (as seen in the examples above) |
| </p></li> |
| <li class="listitem"> |
| <p> |
| the caps string of a 'required' component (as above) will always have |
| fields with fixed values, whereas an introspected string (see below) |
| may have fields with non-fixed values. Compare for example: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> |
| <li class="listitem"><p> |
| <code class="literal">audio/mpeg, mpegversion=(int)4</code> vs. |
| <code class="literal">audio/mpeg, mpegversion=(int){2, 4}</code> |
| </p></li> |
| <li class="listitem"><p> |
| <code class="literal">video/mpeg, mpegversion=(int)2</code> vs. |
| <code class="literal">video/mpeg, systemstream=(boolean){ true, false}, mpegversion=(int)[1, 2]</code> |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| </li> |
| </ul></div> |
| <p> |
| </p> |
| <p> |
| <span class="emphasis"><em>4. Exit codes the installer should return</em></span> |
| </p> |
| <p> |
| The installer should return one of the following exit codes when it exits: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"><p> |
| 0 if all of the requested plugins could be installed |
| (<a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GST-INSTALL-PLUGINS-SUCCESS:CAPS"><span class="type">GST_INSTALL_PLUGINS_SUCCESS</span></a>) |
| </p></li> |
| <li class="listitem"><p> |
| 1 if no appropriate installation candidate for any of the requested |
| plugins could be found. Only return this if nothing has been installed |
| (<a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GST-INSTALL-PLUGINS-NOT-FOUND:CAPS"><span class="type">GST_INSTALL_PLUGINS_NOT_FOUND</span></a>) |
| </p></li> |
| <li class="listitem"><p> |
| 2 if an error occured during the installation. The application will |
| assume that the user will already have seen an error message by the |
| installer in this case and will usually not show another one |
| (<a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GST-INSTALL-PLUGINS-ERROR:CAPS"><span class="type">GST_INSTALL_PLUGINS_ERROR</span></a>) |
| </p></li> |
| <li class="listitem"><p> |
| 3 if some of the requested plugins could be installed, but not all |
| (<a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GST-INSTALL-PLUGINS-PARTIAL-SUCCESS:CAPS"><span class="type">GST_INSTALL_PLUGINS_PARTIAL_SUCCESS</span></a>) |
| </p></li> |
| <li class="listitem"><p> |
| 4 if the user aborted the installation (<a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GST-INSTALL-PLUGINS-USER-ABORT:CAPS"><span class="type">GST_INSTALL_PLUGINS_USER_ABORT</span></a>) |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| <p> |
| <span class="emphasis"><em>5. How to map the required detail string to packages</em></span> |
| </p> |
| <p> |
| It is up to the vendor to find mechanism to map required components from |
| the detail string to the actual packages/plugins to install. This could |
| be a hardcoded list of mappings, for example, or be part of the packaging |
| system metadata. |
| </p> |
| <p> |
| GStreamer plugin files can be introspected for this information. The |
| <code class="literal">gst-inspect</code> utility has a special command line option |
| that will output information similar to what is required. For example |
| <span class="command"><strong> |
| $ gst-inspect-1.0 --print-plugin-auto-install-info /path/to/libgstvorbis.so |
| </strong></span> |
| should output something along the lines of |
| <code class="computeroutput"> |
| decoder-audio/x-vorbis |
| element-vorbisdec |
| element-vorbisenc |
| element-vorbisparse |
| element-vorbistag |
| encoder-audio/x-vorbis |
| </code> |
| Note that in the encoder and decoder case the introspected caps can be more |
| complex with additional fields, e.g. |
| <code class="literal">audio/mpeg,mpegversion=(int){2,4}</code>, so they will not |
| always exactly match the caps wanted by the application. It is up to the |
| installer to deal with this (either by doing proper caps intersection using |
| the GStreamer <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstCaps.html#GstCaps-struct"><span class="type">GstCaps</span></a> API, or by only taking into account the media type). |
| </p> |
| <p> |
| Another potential source of problems are plugins such as ladspa or |
| libvisual where the list of elements depends on the installed |
| ladspa/libvisual plugins at the time. This is also up to the distribution |
| to handle (but usually not relevant for playback applications). |
| </p> |
| </div> |
| </div> |
| <div class="refsect1"> |
| <a name="gst-plugins-base-libs-gstpbutilsinstallplugins.functions_details"></a><h2>Functions</h2> |
| <div class="refsect2"> |
| <a name="GstInstallPluginsResultFunc"></a><h3>GstInstallPluginsResultFunc ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| <span class="c_punctuation">(</span>*GstInstallPluginsResultFunc<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsReturn" title="enum GstInstallPluginsReturn"><span class="type">GstInstallPluginsReturn</span></a> result</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> |
| <p>The prototype of the callback function that will be called once the |
| external plugin installer program has returned. You only need to provide |
| a callback function if you are using the asynchronous interface.</p> |
| <div class="refsect3"> |
| <a name="GstInstallPluginsResultFunc.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>result</p></td> |
| <td class="parameter_description"><p>whether the installation of the requested plugins succeeded or not</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>user_data</p></td> |
| <td class="parameter_description"><p>the user data passed to <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-async" title="gst_install_plugins_async ()"><code class="function">gst_install_plugins_async()</code></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-async"></a><h3>gst_install_plugins_async ()</h3> |
| <pre class="programlisting"><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsReturn" title="enum GstInstallPluginsReturn"><span class="returnvalue">GstInstallPluginsReturn</span></a> |
| gst_install_plugins_async (<em class="parameter"><code>const <a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gchar"><span class="type">gchar</span></a> * const *details</code></em>, |
| <em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a> *ctx</code></em>, |
| <em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsResultFunc" title="GstInstallPluginsResultFunc ()"><span class="type">GstInstallPluginsResultFunc</span></a> func</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> |
| <p>Requests plugin installation without blocking. Once the plugins have been |
| installed or installation has failed, <em class="parameter"><code>func</code></em> |
| will be called with the result |
| of the installation and your provided <em class="parameter"><code>user_data</code></em> |
| pointer.</p> |
| <p>This function requires a running GLib/Gtk main loop. If you are not |
| running a GLib/Gtk main loop, make sure to regularly call |
| g_main_context_iteration(NULL,FALSE).</p> |
| <p>The installer strings that make up <em class="parameter"><code>detail</code></em> |
| are typically obtained by |
| calling <a class="link" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html#gst-missing-plugin-message-get-installer-detail" title="gst_missing_plugin_message_get_installer_detail ()"><code class="function">gst_missing_plugin_message_get_installer_detail()</code></a> on missing-plugin |
| messages that have been caught on a pipeline's bus or created by the |
| application via the provided API, such as <a class="link" href="gst-plugins-base-libs-gstpbutilsmissingplugins.html#gst-missing-element-message-new" title="gst_missing_element_message_new ()"><code class="function">gst_missing_element_message_new()</code></a>.</p> |
| <p>It is possible to request the installation of multiple missing plugins in |
| one go (as might be required if there is a demuxer for a certain format |
| installed but no suitable video decoder and no suitable audio decoder).</p> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-async.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>details</p></td> |
| <td class="parameter_description"><p> NULL-terminated array |
| of installer string details (see below). </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>ctx</p></td> |
| <td class="parameter_description"><p> a <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a>, or NULL. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>func</p></td> |
| <td class="parameter_description"><p> the function to call when the installer program returns. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>user_data</p></td> |
| <td class="parameter_description"><p> the user data to pass to <em class="parameter"><code>func</code></em> |
| when called, or NULL. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-async.returns"></a><h4>Returns</h4> |
| <p> result code whether an external installer could be started</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-sync"></a><h3>gst_install_plugins_sync ()</h3> |
| <pre class="programlisting"><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsReturn" title="enum GstInstallPluginsReturn"><span class="returnvalue">GstInstallPluginsReturn</span></a> |
| gst_install_plugins_sync (<em class="parameter"><code>const <a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gchar"><span class="type">gchar</span></a> * const *details</code></em>, |
| <em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a> *ctx</code></em>);</pre> |
| <p>Requests plugin installation and block until the plugins have been |
| installed or installation has failed.</p> |
| <p>This function should almost never be used, it only exists for cases where |
| a non-GLib main loop is running and the user wants to run it in a separate |
| thread and marshal the result back asynchronously into the main thread |
| using the other non-GLib main loop. You should almost always use |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-async" title="gst_install_plugins_async ()"><code class="function">gst_install_plugins_async()</code></a> instead of this function.</p> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-sync.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>details</p></td> |
| <td class="parameter_description"><p> NULL-terminated array |
| of installer string details. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>ctx</p></td> |
| <td class="parameter_description"><p> a <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a>, or NULL. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-sync.returns"></a><h4>Returns</h4> |
| <p> the result of the installation.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-return-get-name"></a><h3>gst_install_plugins_return_get_name ()</h3> |
| <pre class="programlisting">const <a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> * |
| gst_install_plugins_return_get_name (<em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsReturn" title="enum GstInstallPluginsReturn"><span class="type">GstInstallPluginsReturn</span></a> ret</code></em>);</pre> |
| <p>Convenience function to return the descriptive string associated |
| with a status code. This function returns English strings and |
| should not be used for user messages. It is here only to assist |
| in debugging.</p> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-return-get-name.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>ret</p></td> |
| <td class="parameter_description"><p>the return status code</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-return-get-name.returns"></a><h4>Returns</h4> |
| <p> a descriptive string for the status code in <em class="parameter"><code>ret</code></em> |
| </p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-installation-in-progress"></a><h3>gst_install_plugins_installation_in_progress ()</h3> |
| <pre class="programlisting"><a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| gst_install_plugins_installation_in_progress |
| (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> |
| <p>Checks whether plugin installation (initiated by this application only) |
| is currently in progress.</p> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-installation-in-progress.returns"></a><h4>Returns</h4> |
| <p> TRUE if plugin installation is in progress, otherwise FALSE</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-supported"></a><h3>gst_install_plugins_supported ()</h3> |
| <pre class="programlisting"><a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| gst_install_plugins_supported (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> |
| <p>Checks whether plugin installation is likely to be supported by the |
| current environment. This currently only checks whether the helper script |
| that is to be provided by the distribution or operating system vendor |
| exists.</p> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-supported.returns"></a><h4>Returns</h4> |
| <p> TRUE if plugin installation is likely to be supported.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-context-new"></a><h3>gst_install_plugins_context_new ()</h3> |
| <pre class="programlisting"><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="returnvalue">GstInstallPluginsContext</span></a> * |
| gst_install_plugins_context_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> |
| <p>Creates a new <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a>.</p> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-context-new.returns"></a><h4>Returns</h4> |
| <p> a new <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a>. Free with |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-context-free" title="gst_install_plugins_context_free ()"><code class="function">gst_install_plugins_context_free()</code></a> when no longer needed</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-context-free"></a><h3>gst_install_plugins_context_free ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| gst_install_plugins_context_free (<em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a> *ctx</code></em>);</pre> |
| <p>Frees a <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a>.</p> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-context-free.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>ctx</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-context-set-xid"></a><h3>gst_install_plugins_context_set_xid ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| gst_install_plugins_context_set_xid (<em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a> *ctx</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#guint"><span class="type">guint</span></a> xid</code></em>);</pre> |
| <p>This function is for X11-based applications (such as most Gtk/Qt |
| applications on linux/unix) only. You can use it to tell the external |
| installer the XID of your main application window. That way the installer |
| can make its own window transient to your application window during the |
| installation.</p> |
| <p>If set, the XID will be passed to the installer via a --transient-for=XID |
| command line option.</p> |
| <p>Gtk+/Gnome application should be able to obtain the XID of the top-level |
| window like this:</p> |
| <pre class="programlisting"> |
| ##include <gtk/gtk.h> |
| ##ifdef GDK_WINDOWING_X11 |
| ##include <gdk/gdkx.h> |
| ##endif |
| ... |
| ##ifdef GDK_WINDOWING_X11 |
| xid = GDK_WINDOW_XWINDOW (GTK_WIDGET (application_window)->window); |
| ##endif |
| ... |
| </pre> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-context-set-xid.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>ctx</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>xid</p></td> |
| <td class="parameter_description"><p>the XWindow ID (XID) of the top-level application</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-context-set-confirm-search"></a><h3>gst_install_plugins_context_set_confirm_search ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| gst_install_plugins_context_set_confirm_search |
| (<em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a> *ctx</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> confirm_search</code></em>);</pre> |
| <p>This function is used to tell the external installer process whether it |
| should ask for confirmation or not before searching for missing plugins.</p> |
| <p>If set, this option will be passed to the installer via a |
| --interaction=[show-confirm-search|hide-confirm-search] command line option.</p> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-context-set-confirm-search.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>ctx</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>confirm_search</p></td> |
| <td class="parameter_description"><p>whether to ask for confirmation before searching for plugins</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: 1.6</p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-context-set-desktop-id"></a><h3>gst_install_plugins_context_set_desktop_id ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| gst_install_plugins_context_set_desktop_id |
| (<em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a> *ctx</code></em>, |
| <em class="parameter"><code>const <a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *desktop_id</code></em>);</pre> |
| <p>This function is used to pass the calling application's desktop file ID to |
| the external installer process.</p> |
| <p>A desktop file ID is the basename of the desktop file, including the |
| .desktop extension.</p> |
| <p>If set, the desktop file ID will be passed to the installer via a |
| --desktop-id= command line option.</p> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-context-set-desktop-id.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>ctx</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>desktop_id</p></td> |
| <td class="parameter_description"><p>the desktop file ID of the calling application</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: 1.6</p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="gst-install-plugins-context-set-startup-notification-id"></a><h3>gst_install_plugins_context_set_startup_notification_id ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| gst_install_plugins_context_set_startup_notification_id |
| (<em class="parameter"><code><a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a> *ctx</code></em>, |
| <em class="parameter"><code>const <a href="/usr/share/gtk-doc/html/glibglib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *startup_id</code></em>);</pre> |
| <p>Sets the startup notification ID for the launched process.</p> |
| <p>This is typically used to to pass the current X11 event timestamp to the |
| external installer process.</p> |
| <p>Startup notification IDs are defined in the |
| <a class="ulink" href="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt" target="_top">FreeDesktop.Org Startup Notifications standard</a>.</p> |
| <p>If set, the ID will be passed to the installer via a |
| --startup-notification-id= command line option.</p> |
| <p>GTK+/GNOME applications should be able to create a startup notification ID |
| like this:</p> |
| <pre class="programlisting"> |
| timestamp = gtk_get_current_event_time (); |
| startup_id = g_strdup_printf ("_TIME%u", timestamp); |
| ... |
| </pre> |
| <div class="refsect3"> |
| <a name="gst-install-plugins-context-set-startup-notification-id.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>ctx</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsContext" title="GstInstallPluginsContext"><span class="type">GstInstallPluginsContext</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>startup_id</p></td> |
| <td class="parameter_description"><p>the startup notification ID</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: 1.6</p> |
| </div> |
| </div> |
| <div class="refsect1"> |
| <a name="gst-plugins-base-libs-gstpbutilsinstallplugins.other_details"></a><h2>Types and Values</h2> |
| <div class="refsect2"> |
| <a name="GstInstallPluginsReturn"></a><h3>enum GstInstallPluginsReturn</h3> |
| <p>Result codes returned by <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-async" title="gst_install_plugins_async ()"><code class="function">gst_install_plugins_async()</code></a> and |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-sync" title="gst_install_plugins_sync ()"><code class="function">gst_install_plugins_sync()</code></a>, and also the result code passed to the |
| <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GstInstallPluginsResultFunc" title="GstInstallPluginsResultFunc ()"><span class="type">GstInstallPluginsResultFunc</span></a> specified with <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-async" title="gst_install_plugins_async ()"><code class="function">gst_install_plugins_async()</code></a>.</p> |
| <p>These codes indicate success or failure of starting an external installer |
| program and to what extent the requested plugins could be installed.</p> |
| <div class="refsect3"> |
| <a name="GstInstallPluginsReturn.members"></a><h4>Members</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="300px" class="enum_members_name"> |
| <col class="enum_members_description"> |
| <col width="200px" class="enum_members_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-SUCCESS:CAPS"></a>GST_INSTALL_PLUGINS_SUCCESS</p></td> |
| <td class="enum_member_description"> |
| <p>all of the requested plugins could be |
| installed</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-NOT-FOUND:CAPS"></a>GST_INSTALL_PLUGINS_NOT_FOUND</p></td> |
| <td class="enum_member_description"> |
| <p>no appropriate installation candidate for |
| any of the requested plugins could be found. Only return this if nothing |
| has been installed. Return <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#GST-INSTALL-PLUGINS-PARTIAL-SUCCESS:CAPS"><span class="type">GST_INSTALL_PLUGINS_PARTIAL_SUCCESS</span></a> if |
| some (but not all) of the requested plugins could be installed.</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-ERROR:CAPS"></a>GST_INSTALL_PLUGINS_ERROR</p></td> |
| <td class="enum_member_description"> |
| <p>an error occured during the installation. If |
| this happens, the user has already seen an error message and another |
| one should not be displayed</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-PARTIAL-SUCCESS:CAPS"></a>GST_INSTALL_PLUGINS_PARTIAL_SUCCESS</p></td> |
| <td class="enum_member_description"> |
| <p>some of the requested plugins could |
| be installed, but not all</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-USER-ABORT:CAPS"></a>GST_INSTALL_PLUGINS_USER_ABORT</p></td> |
| <td class="enum_member_description"> |
| <p>the user has aborted the installation</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-CRASHED:CAPS"></a>GST_INSTALL_PLUGINS_CRASHED</p></td> |
| <td class="enum_member_description"> |
| <p>the installer had an unclean exit code |
| (ie. death by signal)</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-INVALID:CAPS"></a>GST_INSTALL_PLUGINS_INVALID</p></td> |
| <td class="enum_member_description"> |
| <p>the helper returned an invalid status code</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-STARTED-OK:CAPS"></a>GST_INSTALL_PLUGINS_STARTED_OK</p></td> |
| <td class="enum_member_description"> |
| <p>returned by <a class="link" href="gst-plugins-base-libs-gstpbutilsinstallplugins.html#gst-install-plugins-async" title="gst_install_plugins_async ()"><code class="function">gst_install_plugins_async()</code></a> to |
| indicate that everything went fine so far and the provided callback |
| will be called with the result of the installation later</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-INTERNAL-FAILURE:CAPS"></a>GST_INSTALL_PLUGINS_INTERNAL_FAILURE</p></td> |
| <td class="enum_member_description"> |
| <p>some internal failure has |
| occured when trying to start the installer</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-HELPER-MISSING:CAPS"></a>GST_INSTALL_PLUGINS_HELPER_MISSING</p></td> |
| <td class="enum_member_description"> |
| <p>the helper script to call the |
| actual installer is not installed</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="GST-INSTALL-PLUGINS-INSTALL-IN-PROGRESS:CAPS"></a>GST_INSTALL_PLUGINS_INSTALL_IN_PROGRESS</p></td> |
| <td class="enum_member_description"> |
| <p>a previously-started plugin |
| installation is still in progress, try again later</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="GstInstallPluginsContext"></a><h3>GstInstallPluginsContext</h3> |
| <pre class="programlisting">typedef struct _GstInstallPluginsContext GstInstallPluginsContext;</pre> |
| <p>Opaque context structure for the plugin installation. Use the provided |
| API to set details on it.</p> |
| </div> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr>Generated by GTK-Doc V1.25</div> |
| </body> |
| </html> |
