## Plugins Plugins — The Caja-Actions Extension Interface Definition v 1 |

## Synopsis

    #include <caja-actions/na-extension.h>

    gboolean            na_extension_startup                (GTypeModule *module);
    guint               na_extension_get_version            (void);
    guint               na_extension_list_types             (const GType **types);
    void                na_extension_shutdown               (void);

## Description

Caja-Actions™ accepts extensions as dynamically loadable libraries (aka plugins).

As of today, Caja-Actions™ may be extended in the following areas:

- Storing menus and actions in a specific storage subsystem . This extension is provided via the public NAIIOProvider interface; it takes care of reading and writing menus and actions to a specific storage subsystem.

- Exporting menus and actions . This extension is provided via the public NAIExporter interface; it takes care of exporting menus and actions to the filesystem from the Caja-Actions™ Configuration Tool user interface.

- Importing menus and actions . This extension is provided via the public NAIImporter interface; it takes care of importing menus and actions from the filesystem into the Caja-Actions™ Configuration Tool user interface.

In order to be recognized as a valid Caja-Actions™ plugin, the library must at least export the functions described in this extension API.

### Developing a Caja-Actions™ plugin

#### Building the dynamically loadable library

The suggested way of producing a dynamically loadable library is to use autoconf, automake and libtool GNU applications.

In this case, it should be enough to use the `-module` option in your `Makefile.am`, as in:

      libna_io_desktop_la_LDFLAGS = -module -no-undefined -avoid-version

#### Installing the library

At startup time, Caja-Actions™ searches for its candidate libraries in `PKGLIBDIR` directory, which most often happens to be `/usr/lib/caja-actions/` or `/usr/lib64/caja-actions/`, depending of your system.

### Versions historic

Table 1. Historic of the versions of this extension API

Caja-Actions™ version | extension API version |
--- | --- | ---
since 2.30 | 1 | current version

## Details

### na_extension_startup ()

    gboolean            na_extension_startup                (GTypeModule *module);

This function is called by the Caja-Actions plugin manager when the plugin library is first loaded in memory. The library may so take advantage of this call by initializing itself, registering its internal GType types, etc.

A Caja-Actions extension must implement this function in order to be considered as a valid candidate to dynamic load.

Example 1.

    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
    static GType st_module_type = 0;

    gboolean
    na_extension_startup( GTypeModule *plugin )
    {
        static GTypeInfo info = {
            sizeof( CappDesktopProviderClass ),
            NULL,
            NULL,
            ( GClassInitFunc ) class_init,
            NULL,
            NULL,
            sizeof( CappDesktopProvider ),
            0,
            ( GInstanceInitFunc ) instance_init
        };

        static const GInterfaceInfo iio_provider_iface_info = {
            ( GInterfaceInitFunc ) iio_provider_iface_init,
            NULL,
            NULL
        };

        st_module_type = g_type_module_register_type( plugin, G_TYPE_OBJECT, "CappDesktopProvider", &info, 0 );

        g_type_module_add_interface( plugin, st_module_type, NA_TYPE_IIO_PROVIDER, &iio_provider_iface_info );

        return( TRUE );
    }

`module` : | the GTypeModule of the plugin library being loaded.
Returns : | `TRUE` if the initialization is successful, `FALSE` else. In this later case, the library is unloaded and no more considered.

Since 2.30

### na_extension_get_version ()

    guint               na_extension_get_version            (void);

This function is called by the Caja-Actions™ program each time it needs to know which version of this API the plugin implements.

If this function is not exported by the library, the plugin manager considers that the library only implements the version 1 of this extension API.

Returns : | the version of this API supported by the module.

Since 2.30

### na_extension_list_types ()

    guint               na_extension_list_types             (const GType **types);

Returned GType types must already have been registered in the GType system (e.g. at #`na_extension_startup()` time), and the objects they describe may implement one or more of the interfaces defined in this Caja-Actions public API.

The Caja-Actions plugin manager will instantiate one GTypeInstance- derived object for each returned GType type, and associate these objects to this library.

A Caja-Actions extension must implement this function in order to be considered as a valid candidate to dynamic load.

Example 2.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    /* the count of GType types provided by this extension
     * each new GType type must
     * - be registered in na_extension_startup()
     * - be addressed in na_extension_list_types().
     */
    #define CADP_TYPES_COUNT    1

    guint
    na_extension_list_types( const GType **types )
    {
         static GType types_list [1+CADP_TYPES_COUNT];

         /* CADP_TYPE_DESKTOP_PROVIDER has been previously
          * registered in na_extension_startup function
          */
         types_list[0] = CADP_TYPE_DESKTOP_PROVIDER;

         types_list[CADP_TYPES_COUNT] = 0;
         *types = types_list;

         return( CADP_TYPES_COUNT );
    }

`types` : | the address where to store the zero-terminated array of instantiable GType types this library implements.
Returns : | the number of GType types returned in the `types` array, not counting the terminating zero item.

Since 2.30

### na_extension_shutdown ()

    void                na_extension_shutdown               (void);

This function is called by Caja-Actions when it is about to shutdown itself.

The dynamically loaded library may take advantage of this call to release any resource, handle, and so on, it may have previously allocated.

A Caja-Actions extension must implement this function in order to be considered as a valid candidate to dynamic load.

Since 2.30