ThunarxProviderPlugin

## ThunarxProviderPlugin ThunarxProviderPlugin — The interface to the plugin type registration |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <thunarx/thunarx.h>

                        ThunarxProviderPlugin;
                        ThunarxProviderPluginIface;
    gboolean            thunarx_provider_plugin_get_resident
                                                            (const ThunarxProviderPlugin *plugin);
    void                thunarx_provider_plugin_set_resident
                                                            (ThunarxProviderPlugin *plugin,
                                                             gboolean resident);
    GType               thunarx_provider_plugin_register_type
                                                            (ThunarxProviderPlugin *plugin,
                                                             GType type_parent,
                                                             const gchar *type_name,
                                                             const GTypeInfo *type_info,
                                                             GTypeFlags type_flags);
    void                thunarx_provider_plugin_add_interface
                                                            (ThunarxProviderPlugin *plugin,
                                                             GType instance_type,
                                                             GType interface_type,
                                                             const GInterfaceInfo *interface_info);
    GType               thunarx_provider_plugin_register_enum
                                                            (ThunarxProviderPlugin *plugin,
                                                             const gchar *name,
                                                             const GEnumValue *const_static_values);
    GType               thunarx_provider_plugin_register_flags
                                                            (ThunarxProviderPlugin *plugin,
                                                             const gchar *name,
                                                             const GFlagsValue *const_static_values);
    #define             THUNARX_DEFINE_TYPE                 (TN,
                                                             t_n,
                                                             T_P)
    #define             THUNARX_DEFINE_TYPE_WITH_CODE       (TN,
                                                             t_n,
                                                             T_P,
                                                             _C_)
    #define             THUNARX_DEFINE_ABSTRACT_TYPE        (TN,
                                                             t_n,
                                                             T_P)
    #define             THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN,
                                                             t_n,
                                                             T_P,
                                                             _C_)
    #define             THUNARX_DEFINE_TYPE_EXTENDED        (TypeName,
                                                             type_name,
                                                             TYPE_PARENT,
                                                             flags,
                                                             CODE)
    #define             THUNARX_IMPLEMENT_INTERFACE         (TYPE_IFACE,
                                                             iface_init)

## Object Hierarchy

      GInterface
       +----ThunarxProviderPlugin

## Properties

      "resident"                 gboolean              : Read / Write

## Description

ThunarxProviderPlugin is the interface to the file manager's type plugin loader implementation. It provides methods to extensions - also called provider plugins - to register dynamic types and control certain aspects of the plugin (see `thunarx_provider_plugin_set_resident()`).

## Details

### ThunarxProviderPlugin

    typedef struct _ThunarxProviderPlugin ThunarxProviderPlugin;

The ThunarxProviderPlugin struct is just a typedef for the interface instance type.

### ThunarxProviderPluginIface

    typedef struct {
      gboolean (*get_resident)    (const ThunarxProviderPlugin *plugin);
      void     (*set_resident)    (ThunarxProviderPlugin       *plugin,
                                   gboolean                     resident);

      GType    (*register_type)   (ThunarxProviderPlugin       *plugin,
                                   GType                        type_parent,
                                   const gchar                 *type_name,
                                   const GTypeInfo             *type_info,
                                   GTypeFlags                   type_flags);
      void     (*add_interface)   (ThunarxProviderPlugin       *plugin,
                                   GType                        instance_type,
                                   GType                        interface_type,
                                   const GInterfaceInfo        *interface_info);
      GType    (*register_enum)   (ThunarxProviderPlugin       *plugin,
                                   const gchar                 *name,
                                   const GEnumValue            *const_static_values);
      GType    (*register_flags)  (ThunarxProviderPlugin       *plugin,
                                   const gchar                 *name,
                                   const GFlagsValue           *const_static_values);
    } ThunarxProviderPluginIface;

Interface with virtual methods implemented by the file manager and accessible from the extensions.

`get_resident` () | see `thunarx_provider_plugin_get_resident()`.
`set_resident` () | see `thunarx_provider_plugin_set_resident()`.
`register_type` () | see `thunarx_provider_plugin_register_type()`.
`add_interface` () | see `thunarx_provider_plugin_add_interface()`.
`register_enum` () | see `thunarx_provider_plugin_register_enum()`.
`register_flags` () | see `thunarx_provider_plugin_register_flags()`.

### thunarx_provider_plugin_get_resident ()

    gboolean            thunarx_provider_plugin_get_resident
                                                            (const ThunarxProviderPlugin *plugin);

Determines whether the application is allowed to unload `plugin` from memory when no longer needed and reload it on demand. If `FALSE` is returned, then the application may unload `plugin`, else if `TRUE` is returned the application will take care that `plugin` is never unloaded from memory during the lifetime of the application.

`plugin` : | a ThunarxProviderPlugin.
Returns : | `TRUE` if `plugin` will be kept in memory once loaded for the first time.

### thunarx_provider_plugin_set_resident ()

    void                thunarx_provider_plugin_set_resident
                                                            (ThunarxProviderPlugin *plugin,
                                                             gboolean resident);

This method is used to instruct the application that `plugin` must be kept in memory during the lifetime of the application. The default is to allow the application to unload `plugin` from the memory when no longer needed. If this method is invoked with a `resident` value of `TRUE` then the application will never try to unload `plugin`.

This method has no effect unless called from the `thunar_extension_initialize` method of the `plugin`.

`plugin` : | a ThunarxProviderPlugin.
`resident` : | `TRUE` to make `plugin` resident in memory.

### thunarx_provider_plugin_register_type ()

    GType               thunarx_provider_plugin_register_type
                                                            (ThunarxProviderPlugin *plugin,
                                                             GType type_parent,
                                                             const gchar *type_name,
                                                             const GTypeInfo *type_info,
                                                             GTypeFlags type_flags);

Looks up or registers a type that is implemented with a particular type `plugin`. If a type with name `type_name` was previously registered, the GType identifier for the type is returned, otherwise the type is newly registered, and the resulting GType identifier returned.

When reregistering a type (typically because a module is unloaded then reloaded, and reinitialized), module and `type_parent` must be the same as they were previously.

`plugin` : | a ThunarxProviderPlugin.
`type_parent` : | the type for the parent class.
`type_name` : | name for the type.
`type_info` : | type information structure.
`type_flags` : | flags field providing details about the type.
Returns : | the new or existing type id.

### thunarx_provider_plugin_add_interface ()

    void                thunarx_provider_plugin_add_interface
                                                            (ThunarxProviderPlugin *plugin,
                                                             GType instance_type,
                                                             GType interface_type,
                                                             const GInterfaceInfo *interface_info);

Registers an additional interface for a type, whose interface lives in the given type `plugin`. If the interface was already registered for the type in this `plugin`, nothing will be done.

As long as any instances of the type exist, the type `plugin` will not be unloaded.

`plugin` : | a ThunarxProviderPlugin.
`instance_type` : | type to which to add the interface.
`interface_type` : | interface type to add.
`interface_info` : | type information structure.

### thunarx_provider_plugin_register_enum ()

    GType               thunarx_provider_plugin_register_enum
                                                            (ThunarxProviderPlugin *plugin,
                                                             const gchar *name,
                                                             const GEnumValue *const_static_values);

Looks up or registers an enumeration that is implemented with a particular type `plugin`. If a type with name `name` was previously registered, the GType identifier for the type is returned, otherwise the type is newly registered, and the resulting GType identifier returned.

As long as any instances of the type exist, the type `plugin` will not be unloaded.

`plugin` : | a ThunarxProviderPlugin.
`name` : | the name for the type.
`const_static_values` : | an array of GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being `0`.
Returns : | the new or existing type id.

### thunarx_provider_plugin_register_flags ()

    GType               thunarx_provider_plugin_register_flags
                                                            (ThunarxProviderPlugin *plugin,
                                                             const gchar *name,
                                                             const GFlagsValue *const_static_values);

Looks up or registers a flags type that is implemented with a particular type `plugin`. If a type with name qname was previously registered, the GType identifier for the type is returned, otherwise the type is newly registered, and the resulting GType identifier returned.

As long as any instances of the type exist, the type `plugin` will not be unloaded.

`plugin` : | a ThunarxProviderPlugin.
`name` : | name for the type.
`const_static_values` : | an array of GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being `0`.
Returns : | the new or existing type id.

### THUNARX_DEFINE_TYPE()

    #define THUNARX_DEFINE_TYPE(TN, t_n, T_P)                         THUNARX_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})

A convenience macro for plugin type implementations, which declares a class initialization function, a static variable named `t_n`_parent_class pointing to the parent and a static variable named `t_n`_type containing the GType of the type to define. Furthermore, it defines a `t_n` `_get_type()` function and a `t_n` `_register_type()` function. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

`TN` : | the name of the new type, in Camel case.
`t_n` : | the name of the new type, in lowercase, with words separated by '_'.
`T_P` : | the GType of the parent type.

### THUNARX_DEFINE_TYPE_WITH_CODE()

    #define THUNARX_DEFINE_TYPE_WITH_CODE(TN, t_n, T_P, _C_)          THUNARX_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, _C_)

A convenience macro for plugin type implementations. Similar to `THUNARX_DEFINE_TYPE()`, but allows to insert custom code into the `*_get_type()` function, e.g. interface implemenations via `THUNARX_IMPLEMENT_INTERFACE()`. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

`TN` : | the name of the new type, in Camel case.
`t_n` : | the name of the new type, in lowercase, with words separated by '_'.
`T_P` : | the GType of the parent type.
`_C_` : | custom code that gets inserted in the `*_get_type()` function.

### THUNARX_DEFINE_ABSTRACT_TYPE()

    #define THUNARX_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P)                THUNARX_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})

A convenience macro for plugin type implementations. Similar to `THUNARX_DEFINE_TYPE()`, but defines an abstract type. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

`TN` : | the name of the new type, in Camel case.
`t_n` : | the name of the new type, in lowercase, with words separated by '_'.
`T_P` : | the GType of the parent type.

### THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE()

    #define THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_) THUNARX_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, _C_)

A convenience macro for plugin type implementations. Similar to `THUNARX_DEFINE_TYPE_WITH_CODE()`, but defines an abstract type and allows to insert custom code into the `*_get_type()` function, e.g. interface implementations via `THUNARX_IMPLEMENT_INTERFACE()`. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

`TN` : | the name of the new type, in Camel case.
`t_n` : | the name of the new type, in lowercase, with words separated by '_'.
`T_P` : | the GType of the parent type.
`_C_` : | custom code that gets inserted in the `*_get_type()` function.

### THUNARX_DEFINE_TYPE_EXTENDED()

    #define             THUNARX_DEFINE_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE)

The most general convenience macro for plugin type implementations, on which `THUNARX_DEFINE_TYPE()`, `THUNARX_DEFINE_TYPE_WITH_CODE()`, `THUNARX_DEFINE_ABSTRACT_TYPE()` and `THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE()` are based.

    1
    2
    3
    4
    5
    6
    THUNARX_DEFINE_TYPE_EXTENDED (FooExtension,
                                  foo_extension,
                                  G_TYPE_OBJECT,
                                  0,
                                  THUNARX_IMPLEMENT_INTERFACE (TYPE_BAR,
                                                               foo_extension_bar_init));

expands to

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    static gpointer foo_extension_parent_class = NULL;
    static GType    foo_extension_type = G_TYPE_INVALID;
    static void     foo_extension_init              (FooExtension *self);
    static void     foo_extension_class_init        (FooExtensionClass *klass);
    static void     foo_extension_class_intern_init (FooExtensionClass *klass)
    {
      foo_extension_parent_class = g_type_class_peek_parent (klass);
      foo_extension_class_init (klass);
    }
    GType
    foo_extension_get_type (void)
    {
      return foo_extension_type;
    }
    void
    foo_extension_register_type (ThunarxProviderPlugin *plugin)
    {
      GType thunarx_define_type_id;
      static const thunarx_define_type_info =
      {
        sizeof (FooExtensionClass),
        NULL,
        NULL,
        (GClassInitFunc) foo_extension_class_intern_init,
        NULL,
        NULL,
        sizeof (FooExtension),
        0,
        (GInstanceInitFunc) foo_extension_init,
        NULL,
      };
      thunarx_define_type_id = thunarx_provider_plugin_register_type (thunarx_define_type_plugin, G_TYPE_OBJECT,
                                                                      "FooExtension", &thunarx_define_type_info, 0);
      {
        static const GInterfaceInfo thunarx_implement_interface_info =
        {
          (GInterfaceInitFunc) foo_extension_bar_init,
        };
        thunarx_provider_plugin_add_interface (thunarx_define_type_plugin, thunarx_define_type_id,
                                               TYPE_BAR, &thunarx_implement_interface_info);
      };
      foo_extension_type = thunarx_define_type_id;
    }

The only pieces which have to be manually provided are the definitions of the instance and class structure and the definitions of the instance and class init functions.

`TypeName` : | The name of the new type, in Camel case.
`type_name` : | The name of the new type, in lowercase, with words separated by '_'.
`TYPE_PARENT` : | The GType of the parent type.
`flags` : | GTypeFlags to pass to `thunarx_provider_plugin_register_type()`.
`CODE` : | Custom code that gets inserted in the `*_register_type()` function.

### THUNARX_IMPLEMENT_INTERFACE()

    #define             THUNARX_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init)

A convenience macro to ease interface addition in the `_C_` section of `THUNARX_DEFINE_TYPE_WITH_CODE()` or `THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE()`. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

Note that this macro can only be used together with the `THUNARX_DEFINE_*` macros, since it depends on variable names used by those macros.

`TYPE_IFACE` : | the GType of the interface to add.
`iface_init` : | the interface init function.

## Property Details

### The `"resident"` property

      "resident"                 gboolean              : Read / Write

Tells whether a plugin must reside in memory once loaded for the first time. See `thunarx_provider_plugin_get_resident()` and `thunarx_provider_plugin_set_resident()` for more details.

Default value: FALSE

## See Also

ThunarxProviderFactory