<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="gio-Extension-Points">
<refmeta>
<refentrytitle role="top_of_page" id="gio-Extension-Points.top_of_page">Extension Points</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GIO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Extension Points</refname>
<refpurpose>Extension Points</refpurpose>
</refnamediv>

<refsynopsisdiv id="gio-Extension-Points.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gio.h&gt;

                    <link linkend="GIOExtension">GIOExtension</link>;
                    <link linkend="GIOExtensionPoint">GIOExtensionPoint</link>;
const <link linkend="char">char</link> *        <link linkend="g-io-extension-get-name">g_io_extension_get_name</link>             (<link linkend="GIOExtension">GIOExtension</link> *extension);
<link linkend="gint">gint</link>                <link linkend="g-io-extension-get-priority">g_io_extension_get_priority</link>         (<link linkend="GIOExtension">GIOExtension</link> *extension);
<link linkend="GType">GType</link>               <link linkend="g-io-extension-get-type">g_io_extension_get_type</link>             (<link linkend="GIOExtension">GIOExtension</link> *extension);
<link linkend="GIOExtension">GIOExtension</link> *      <link linkend="g-io-extension-point-get-extension-by-name">g_io_extension_point_get_extension_by_name</link>
                                                        (<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> *extension_point,
                                                         const <link linkend="char">char</link> *name);
<link linkend="GList">GList</link> *             <link linkend="g-io-extension-point-get-extensions">g_io_extension_point_get_extensions</link> (<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> *extension_point);
<link linkend="GType">GType</link>               <link linkend="g-io-extension-point-get-required-type">g_io_extension_point_get_required_type</link>
                                                        (<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> *extension_point);
<link linkend="GIOExtension">GIOExtension</link> *      <link linkend="g-io-extension-point-implement">g_io_extension_point_implement</link>      (const <link linkend="char">char</link> *extension_point_name,
                                                         <link linkend="GType">GType</link> type,
                                                         const <link linkend="char">char</link> *extension_name,
                                                         <link linkend="gint">gint</link> priority);
<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> * <link linkend="g-io-extension-point-lookup">g_io_extension_point_lookup</link>         (const <link linkend="char">char</link> *name);
<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> * <link linkend="g-io-extension-point-register">g_io_extension_point_register</link>       (const <link linkend="char">char</link> *name);
<link linkend="void">void</link>                <link linkend="g-io-extension-point-set-required-type">g_io_extension_point_set_required_type</link>
                                                        (<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> *extension_point,
                                                         <link linkend="GType">GType</link> type);
<link linkend="GTypeClass">GTypeClass</link>*         <link linkend="g-io-extension-ref-class">g_io_extension_ref_class</link>            (<link linkend="GIOExtension">GIOExtension</link> *extension);
</synopsis>
</refsynopsisdiv>









<refsect1 id="gio-Extension-Points.description" role="desc">
<title role="desc.title">Description</title>
<para>
<link linkend="GIOExtensionPoint"><type>GIOExtensionPoint</type></link> provides a mechanism for modules to extend the
functionality of the library or application that loaded it in an 
organized fashion.  
</para>
<para>
An extension point is identified by a name, and it may optionally
require that any implementation must by of a certain type (or derived
thereof). Use <link linkend="g-io-extension-point-register"><function>g_io_extension_point_register()</function></link> to register an
extension point, and <link linkend="g-io-extension-point-set-required-type"><function>g_io_extension_point_set_required_type()</function></link> to
set a required type.
</para>
<para>
A module can implement an extension point by specifying the <link linkend="GType"><type>GType</type></link> 
that implements the functionality. Additionally, each implementation
of an extension point has a name, and a priority. Use
<link linkend="g-io-extension-point-implement"><function>g_io_extension_point_implement()</function></link> to implement an extension point.
</para>
<para>
 <informalexample><programlisting>
 GIOExtensionPoint *ep;

 /&ast; Register an extension point &ast;/
 ep = g_io_extension_point_register ("my-extension-point");
 g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
 </programlisting></informalexample>
</para>
<para>
 <informalexample><programlisting>
 /&ast; Implement an extension point &ast;/
 G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
 g_io_extension_point_implement ("my-extension-point",
                                 my_example_impl_get_type (),
                                 "my-example",
                                 10);
 </programlisting></informalexample>
</para>
<para>
 It is up to the code that registered the extension point how
 it uses the implementations that have been associated with it.
 Depending on the use case, it may use all implementations, or
 only the one with the highest priority, or pick a specific
 one by name.</para>
<para>
</para>
</refsect1>

<refsect1 id="gio-Extension-Points.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GIOExtension" role="struct">
<title>GIOExtension</title>
<indexterm zone="GIOExtension"><primary sortas="IOExtension">GIOExtension</primary></indexterm><programlisting>typedef struct _GIOExtension GIOExtension;</programlisting>
<para>
</para></refsect2>
<refsect2 id="GIOExtensionPoint" role="struct">
<title>GIOExtensionPoint</title>
<indexterm zone="GIOExtensionPoint"><primary sortas="IOExtensionPoint">GIOExtensionPoint</primary></indexterm><programlisting>typedef struct _GIOExtensionPoint GIOExtensionPoint;</programlisting>
<para>
</para></refsect2>
<refsect2 id="g-io-extension-get-name" role="function">
<title>g_io_extension_get_name ()</title>
<indexterm zone="g-io-extension-get-name"><primary sortas="io_extension_get_name">g_io_extension_get_name</primary></indexterm><programlisting>const <link linkend="char">char</link> *        g_io_extension_get_name             (<link linkend="GIOExtension">GIOExtension</link> *extension);</programlisting>
<para>
Gets the name under which <parameter>extension</parameter> was registered.
</para>
<para>
Note that the same type may be registered as extension
for multiple extension points, under different names.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>extension</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOExtension"><type>GIOExtension</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the name of <parameter>extension</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-get-priority" role="function">
<title>g_io_extension_get_priority ()</title>
<indexterm zone="g-io-extension-get-priority"><primary sortas="io_extension_get_priority">g_io_extension_get_priority</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_io_extension_get_priority         (<link linkend="GIOExtension">GIOExtension</link> *extension);</programlisting>
<para>
Gets the priority with which <parameter>extension</parameter> was registered.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>extension</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOExtension"><type>GIOExtension</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the priority of <parameter>extension</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-get-type" role="function">
<title>g_io_extension_get_type ()</title>
<indexterm zone="g-io-extension-get-type"><primary sortas="io_extension_get_type">g_io_extension_get_type</primary></indexterm><programlisting><link linkend="GType">GType</link>               g_io_extension_get_type             (<link linkend="GIOExtension">GIOExtension</link> *extension);</programlisting>
<para>
Gets the type associated with <parameter>extension</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>extension</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOExtension"><type>GIOExtension</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the type of <parameter>extension</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-point-get-extension-by-name" role="function">
<title>g_io_extension_point_get_extension_by_name ()</title>
<indexterm zone="g-io-extension-point-get-extension-by-name"><primary sortas="io_extension_point_get_extension_by_name">g_io_extension_point_get_extension_by_name</primary></indexterm><programlisting><link linkend="GIOExtension">GIOExtension</link> *      g_io_extension_point_get_extension_by_name
                                                        (<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> *extension_point,
                                                         const <link linkend="char">char</link> *name);</programlisting>
<para>
Finds a <link linkend="GIOExtension"><type>GIOExtension</type></link> for an extension point by name.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>extension_point</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOExtensionPoint"><type>GIOExtensionPoint</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara> the name of the extension to get
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GIOExtension"><type>GIOExtension</type></link> for <parameter>extension_point</parameter> that has the
   given name, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if there is no extension with that name
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-point-get-extensions" role="function">
<title>g_io_extension_point_get_extensions ()</title>
<indexterm zone="g-io-extension-point-get-extensions"><primary sortas="io_extension_point_get_extensions">g_io_extension_point_get_extensions</primary></indexterm><programlisting><link linkend="GList">GList</link> *             g_io_extension_point_get_extensions (<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> *extension_point);</programlisting>
<para>
Gets a list of all extensions that implement this extension point.
The list is sorted by priority, beginning with the highest priority.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>extension_point</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOExtensionPoint"><type>GIOExtensionPoint</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GList"><type>GList</type></link> of <link linkend="GIOExtension"><type>GIOExtension</type></link><!-- -->s. The list is owned by
  GIO and should not be modified
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-point-get-required-type" role="function">
<title>g_io_extension_point_get_required_type ()</title>
<indexterm zone="g-io-extension-point-get-required-type"><primary sortas="io_extension_point_get_required_type">g_io_extension_point_get_required_type</primary></indexterm><programlisting><link linkend="GType">GType</link>               g_io_extension_point_get_required_type
                                                        (<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> *extension_point);</programlisting>
<para>
Gets the required type for <parameter>extension_point</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>extension_point</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOExtensionPoint"><type>GIOExtensionPoint</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GType"><type>GType</type></link> that all implementations must have, 
    or <link linkend="G-TYPE-INVALID--CAPS"><type>G_TYPE_INVALID</type></link> if the extension point has no required type
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-point-implement" role="function">
<title>g_io_extension_point_implement ()</title>
<indexterm zone="g-io-extension-point-implement"><primary sortas="io_extension_point_implement">g_io_extension_point_implement</primary></indexterm><programlisting><link linkend="GIOExtension">GIOExtension</link> *      g_io_extension_point_implement      (const <link linkend="char">char</link> *extension_point_name,
                                                         <link linkend="GType">GType</link> type,
                                                         const <link linkend="char">char</link> *extension_name,
                                                         <link linkend="gint">gint</link> priority);</programlisting>
<para>
Registers <parameter>type</parameter> as extension for the extension point with name
<parameter>extension_point_name</parameter>. 
</para>
<para>
If <parameter>type</parameter> has already been registered as an extension for this 
extension point, the existing <link linkend="GIOExtension"><type>GIOExtension</type></link> object is returned.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>extension_point_name</parameter>&#160;:</term>
<listitem><simpara> the name of the extension point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GType"><type>GType</type></link> to register as extension 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>extension_name</parameter>&#160;:</term>
<listitem><simpara> the name for the extension
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter>&#160;:</term>
<listitem><simpara> the priority for the extension
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GIOExtension"><type>GIOExtension</type></link> object for <link linkend="GType"><type>GType</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-point-lookup" role="function">
<title>g_io_extension_point_lookup ()</title>
<indexterm zone="g-io-extension-point-lookup"><primary sortas="io_extension_point_lookup">g_io_extension_point_lookup</primary></indexterm><programlisting><link linkend="GIOExtensionPoint">GIOExtensionPoint</link> * g_io_extension_point_lookup         (const <link linkend="char">char</link> *name);</programlisting>
<para>
Looks up an existing extension point.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara> the name of the extension point
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GIOExtensionPoint"><type>GIOExtensionPoint</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if there is no
   registered extension point with the given name
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-point-register" role="function">
<title>g_io_extension_point_register ()</title>
<indexterm zone="g-io-extension-point-register"><primary sortas="io_extension_point_register">g_io_extension_point_register</primary></indexterm><programlisting><link linkend="GIOExtensionPoint">GIOExtensionPoint</link> * g_io_extension_point_register       (const <link linkend="char">char</link> *name);</programlisting>
<para>
Registers an extension point.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara> The name of the extension point
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the new <link linkend="GIOExtensionPoint"><type>GIOExtensionPoint</type></link>. This object is owned by GIO
   and should not be freed
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-point-set-required-type" role="function">
<title>g_io_extension_point_set_required_type ()</title>
<indexterm zone="g-io-extension-point-set-required-type"><primary sortas="io_extension_point_set_required_type">g_io_extension_point_set_required_type</primary></indexterm><programlisting><link linkend="void">void</link>                g_io_extension_point_set_required_type
                                                        (<link linkend="GIOExtensionPoint">GIOExtensionPoint</link> *extension_point,
                                                         <link linkend="GType">GType</link> type);</programlisting>
<para>
Sets the required type for <parameter>extension_point</parameter> to <parameter>type</parameter>. 
All implementations must henceforth have this type.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>extension_point</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOExtensionPoint"><type>GIOExtensionPoint</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GType"><type>GType</type></link> to require
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-extension-ref-class" role="function">
<title>g_io_extension_ref_class ()</title>
<indexterm zone="g-io-extension-ref-class"><primary sortas="io_extension_ref_class">g_io_extension_ref_class</primary></indexterm><programlisting><link linkend="GTypeClass">GTypeClass</link>*         g_io_extension_ref_class            (<link linkend="GIOExtension">GIOExtension</link> *extension);</programlisting>
<para>
Gets a reference to the class for the type that is 
associated with <parameter>extension</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>extension</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOExtension"><type>GIOExtension</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GTypeClass"><type>GTypeClass</type></link> for the type of <parameter>extension</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1 id="gio-Extension-Points.see-also">
<title>See Also</title>
<link linkend="extending-gio">Extending GIO</link>
</refsect1>

</refentry>
