libinfinoted-plugin-manager-0.6 Reference Manual: InfinotedPluginManager

## InfinotedPluginManager InfinotedPluginManager — Loads and propagates events to infinoted plugins. |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfinotedPluginManager * | infinoted_plugin_manager_new ()
gboolean | infinoted_plugin_manager_load ()
InfdDirectory * | infinoted_plugin_manager_get_directory ()
InfIo * | infinoted_plugin_manager_get_io ()
InfinotedLog * | infinoted_plugin_manager_get_log ()
InfCertificateCredentials * | infinoted_plugin_manager_get_credentials ()
gpointer | infinoted_plugin_manager_get_connection_info ()
gpointer | infinoted_plugin_manager_get_session_info ()
GQuark | infinoted_plugin_manager_error_quark ()

## Properties

InfCertificateCredentials * | credentials | Read / Write / Construct Only
InfdDirectory * | directory | Read / Write / Construct Only
InfinotedLog * | log | Read / Write / Construct Only
gchar * | path | Read

## Types and Values

struct | InfinotedPluginManager
struct | InfinotedPluginManagerClass
struct | InfinotedPlugin
enum | InfinotedPluginManagerError

## Object Hierarchy

        GObject
        ╰── InfinotedPluginManager

## Includes

    #include <infinoted/infinoted-plugin-manager.h>

## Description

InfinotedPluginManager handles the loading of plugins for the infinoted server. It initializes and deinitializes plugins, and it makes callbacks when connections or sessions are added or removed. Furthermore, it provides an interface for plugins to obtain and interact with the server itself, most notable its InfdDirectory instance.

## Functions

### infinoted_plugin_manager_new ()

    InfinotedPluginManager *
    infinoted_plugin_manager_new (InfdDirectory *directory,
                                  InfinotedLog *log,
                                  InfCertificateCredentials *creds);

Creates a new InfinotedPluginManager with the given directory, log and credentials. These three objects will be available for plugins to enhance the infinoted functionality. Plugins can be loaded with `infinoted_plugin_manager_load()`.

#### Parameters

directory | The InfdDirectory on which plugins should operate. |
log | The InfinotedLog to write log messages to. |
creds | The InfCertificateCredentials used to secure data transfer with the clients, or `NULL`. |

#### Returns

A new InfinotedPluginManager.

### infinoted_plugin_manager_load ()

    gboolean
    infinoted_plugin_manager_load (InfinotedPluginManager *manager,
                                   const gchar *plugin_path,
                                   const gchar * const*plugins,
                                   GKeyFile *options,
                                   GError **error);

Loads all plugins specified in `plugins` from the location at `plugin_path` . If loading one of the module fails the function sets `error` and returns `FALSE`, and the object ends up with no plugins loaded. If `plugins` is `NULL`, no plugins are loaded.

If this function is called while there are already plugins loaded, all existing plugins are unloaded first.

#### Parameters

manager | A InfinotedPluginManager. |
plugin_path | The path from which to load plugins. |
plugins | A list of plugins to load, or `NULL`. |
options | A GKeyFile with configuration options for the plugins. |
error | Location to store error information, if any, or `NULL`. |

#### Returns

`TRUE` on success or `FALSE` on error.

### infinoted_plugin_manager_get_directory ()

    InfdDirectory *
    infinoted_plugin_manager_get_directory
                                   (InfinotedPluginManager *manager);

Returns the InfdDirectory used by the plugin manager.

#### Parameters

manager | A InfinotedPluginManager. |

#### Returns

A InfdDirectory owned by the plugin manager.

### infinoted_plugin_manager_get_io ()

    InfIo *
    infinoted_plugin_manager_get_io (InfinotedPluginManager *manager);

Returns the InfIo of the InfdDirectory used by the plugin manager.

#### Parameters

manager | A InfinotedPluginManager. |

#### Returns

A InfIo owned by the plugin manager.

### infinoted_plugin_manager_get_log ()

    InfinotedLog *
    infinoted_plugin_manager_get_log (InfinotedPluginManager *manager);

Returns the InfinotedLog that the plugin manager and the plugins do write log messages to.

#### Parameters

manager | A InfinotedPluginManager. |

#### Returns

A InfinotedLog owned by the plugin manager.

### infinoted_plugin_manager_get_credentials ()

    InfCertificateCredentials *
    infinoted_plugin_manager_get_credentials
                                   (InfinotedPluginManager *manager);

Returns the InfCertificateCredentials used for securing the data transfer with all clients.

#### Parameters

manager | A InfinotedPluginManager. |

#### Returns

A InfCertificateCredentials object owned by the plugin manager.

### infinoted_plugin_manager_get_connection_info ()

    gpointer
    infinoted_plugin_manager_get_connection_info
                                   (InfinotedPluginManager *mgr,
                                    gpointer plugin_info,
                                    InfXmlConnection *connection);

Queries the connection-specfic plugin data for the plugin instance `plugin_info` . Returns `NULL` if no such object exists, i.e. when the plugin's `connection_info_size` is set to 0.

#### Parameters

mgr | A InfinotedPluginManager. |
plugin_info | The `plugin_info` pointer of a plugin instance. |
connection | The InfXmlConnection for which to retrieve plugin data. |

#### Returns

A pointer to the connection-specific plugin data, or `NULL`.

### infinoted_plugin_manager_get_session_info ()

    gpointer
    infinoted_plugin_manager_get_session_info
                                   (InfinotedPluginManager *mgr,
                                    gpointer plugin_info,
                                    InfSessionProxy *proxy);

Queries the session-specfic plugin data for the plugin instance `plugin_info` . Returns `NULL` if no such object exists, i.e. when the plugin's `session_info_size` is set to 0.

#### Parameters

mgr | A InfinotedPluginManager. |
plugin_info | The `plugin_info` pointer of a plugin instance. |
proxy | The InfSessionProxy for which to retrieve plugin data. |

#### Returns

A pointer to the session-specific plugin data, or `NULL`.

### infinoted_plugin_manager_error_quark ()

    GQuark
    infinoted_plugin_manager_error_quark (void);

Returns the GQuark for errors from the InfinotedPluginManager module.

#### Returns

The error domain for the InfinotedPluginManager module.

## Types and Values

### struct InfinotedPluginManager

    struct InfinotedPluginManager;

InfinotedPluginManager is an opaque data type. You should only access it via the public API functions.

### struct InfinotedPluginManagerClass

    struct InfinotedPluginManagerClass {
    };

This structure does not contain any public fields.

### struct InfinotedPlugin

    struct InfinotedPlugin {
      const gchar* name;
      const gchar* description;
      const InfinotedParameterInfo* options;

      gsize info_size;
      gsize connection_info_size;
      gsize session_info_size;
      const gchar* session_type;

      void(*on_info_initialize)(gpointer plugin_info);

      gboolean(*on_initialize)(InfinotedPluginManager* manager,
                               gpointer plugin_info,
                               GError** error);

      void(*on_deinitialize)(gpointer plugin_info);

      void(*on_connection_added)(InfXmlConnection* connection,
                                 gpointer plugin_info,
                                 gpointer connection_info);

      void(*on_connection_removed)(InfXmlConnection* connection,
                                   gpointer plugin_info,
                                   gpointer connection_info);

      void(*on_session_added)(const InfBrowserIter* iter,
                              InfSessionProxy* proxy,
                              gpointer plugin_info,
                              gpointer session_info);

      void(*on_session_removed)(const InfBrowserIter* iter,
                                InfSessionProxy* proxy,
                                gpointer plugin_info,
                                gpointer session_info);
    };

Declares a InfinotedPlugin. If an instance of this structure is called `INFINOTED_PLUGIN` and exported from a shared object, it can be loaded as a plugin by infinoted.

#### Members

const gchar *`name`; | The name of the plugin. The filename of the shared object should be `libinfinoted-plugin-<name>`. |
const gchar *`description`; | A human-readable description of what the plugin does. |
const InfinotedParameterInfo *`options`; | A 0-terminated list of plugin parameters. The parameters are provided to the plugin via the infinoted configuration file or the command line. The last element of the list must have the `name` field set to `NULL`. |
gsize `info_size`; | The size of the plugin instance structure. When the plugin is instantiated, this amount of memory will be allocated for the plugin instance. This field must be different from 0. |
gsize `connection_info_size`; | The size of the plugin's connection info structure. For each plugin instance, this amount of memory will be allocated for each connection of the server. The plugin can use it to store connection-specific data. This field can be 0. |
gsize `session_info_size`; | The size of the plugin's session info structure. For each plugin instance, this amount of memory will be allocated for each session that is currently active on the server. The plugin can use it to store session-specific data. This field can be 0. |
const gchar *`session_type`; | If non-`NULL`, specifies the session type handled by the plugin. Only for sessions of this type or a derived type a session info structure is allocated. The `on_session_added` and `on_session_removed` callbacks are always made, independent of this field. |
`on_info_initialize` () | Function called after the plugin has been instantiated. It should initialize all fields of the plugin instance to a sane default value. |
`on_initialize` () | Function called to initialize the plugin. The function can return `FALSE` and set the `error` parameter to prevent the plugin from being used. The server will not be started in this case. Even if this function returns `FALSE`, `on_deinitialize` will be called on the plugin to clean up partly constructed plugin data by this function. |
`on_deinitialize` () | Function called when the plugin is unloaded. Should clean up all resources the plugin has allocated. |
`on_connection_added` () | Function called when there is a new connection to the server. It is also called for all existing connections at the time the plugin is loaded. |
`on_connection_removed` () | Function called when a client connection has been dropped. It is also called for all existing connections right before the plugin is unloaded. |
`on_session_added` () | Function called when a new session has become active on the server. It is also called for all existing sessions at the time the plugin is loaded. |
`on_session_removed` () | Function called when a session has become inactive and the server is freeing resources allocated to it. It is also called for all existing sessions right before the plugin is unloaded. |

### enum InfinotedPluginManagerError

Error codes for the `INFINOTED_PLUGIN_MANAGER_ERROR` error domain. These errors can occur when loading a plugin with `infinoted_plugin_manager_load()`.

#### Members

INFINOTED_PLUGIN_MANAGER_ERROR_OPEN_FAILED | Failed to open the code module of a plugin. |
INFINOTED_PLUGIN_MANAGER_ERROR_NO_ENTRY_POINT | The code module of a plugin does not provide the `INFINOTED_PLUGIN` symbol. |

## Property Details

### The `“credentials”` property

      “credentials”              InfCertificateCredentials *

The server's TLS credentials.

Flags: Read / Write / Construct Only

### The `“directory”` property

      “directory”                InfdDirectory *

The infinote directory served by the server.

Flags: Read / Write / Construct Only

### The `“log”` property

      “log”                      InfinotedLog *

The log object into which to write log messages.

Flags: Read / Write / Construct Only

### The `“path”` property

      “path”                     gchar *

The path from which plugins are loaded.

Flags: Read

Default value: NULL