InfinotedPluginManager

InfinotedPluginManager — Loads and propagates events to infinoted plugins.

Stability Level

Unstable, unless otherwise indicated

Synopsis

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

                    InfinotedPluginManager;
struct              InfinotedPluginManagerClass;
struct              InfinotedPlugin;
enum                InfinotedPluginManagerError;
InfinotedPluginManager * infinoted_plugin_manager_new   (InfdDirectory *directory,
                                                         InfinotedLog *log,
                                                         InfCertificateCredentials *creds);
gboolean            infinoted_plugin_manager_load       (InfinotedPluginManager *manager,
                                                         const gchar *plugin_path,
                                                         const gchar * const*plugins,
                                                         GKeyFile *options,
                                                         GError **error);
InfdDirectory *     infinoted_plugin_manager_get_directory
                                                        (InfinotedPluginManager *manager);
InfIo *             infinoted_plugin_manager_get_io     (InfinotedPluginManager *manager);
InfinotedLog *      infinoted_plugin_manager_get_log    (InfinotedPluginManager *manager);
InfCertificateCredentials * infinoted_plugin_manager_get_credentials
                                                        (InfinotedPluginManager *manager);
gpointer            infinoted_plugin_manager_get_connection_info
                                                        (InfinotedPluginManager *mgr,
                                                         gpointer plugin_info,
                                                         InfXmlConnection *connection);
gpointer            infinoted_plugin_manager_get_session_info
                                                        (InfinotedPluginManager *mgr,
                                                         gpointer plugin_info,
                                                         InfSessionProxy *proxy);
GQuark              infinoted_plugin_manager_error_quark
                                                        (void);

Object Hierarchy

  GObject
   +----InfinotedPluginManager

Properties

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

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.

Details

InfinotedPluginManager

typedef struct _InfinotedPluginManager 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.

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

typedef enum {
  INFINOTED_PLUGIN_MANAGER_ERROR_OPEN_FAILED,
  INFINOTED_PLUGIN_MANAGER_ERROR_NO_ENTRY_POINT
} InfinotedPluginManagerError;

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

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.

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().

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.

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.

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.

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.

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.

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.

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.

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.

Property Details

The "credentials" property

  "credentials"              InfCertificateCredentials*  : Read / Write / Construct Only

The server's TLS credentials.


The "directory" property

  "directory"                InfdDirectory*        : Read / Write / Construct Only

The infinote directory served by the server.


The "log" property

  "log"                      InfinotedLog*         : Read / Write / Construct Only

The log object into which to write log messages.


The "path" property

  "path"                     gchar*                : Read

The path from which plugins are loaded.

Default value: NULL