InfinotedPluginManager

InfinotedPluginManager — Loads and propagates events to infinoted plugins.

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

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

Types and Values

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

[constructor]

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.

[allow-none]

Returns

A new InfinotedPluginManager.

[transfer full]


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.

[array zero-terminated=1][allow-none]

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.

[transfer none]


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.

[transfer none]


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.

[transfer none]


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.

[transfer none]


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.

[transfer none][allow-none]


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.

[transfer none][allow-none]


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.

Owner: InfinotedPluginManager

Flags: Read / Write / Construct Only


The “directory” property

  “directory”                InfdDirectory *

The infinote directory served by the server.

Owner: InfinotedPluginManager

Flags: Read / Write / Construct Only


The “log” property

  “log”                      InfinotedLog *

The log object into which to write log messages.

Owner: InfinotedPluginManager

Flags: Read / Write / Construct Only


The “path” property

  “path”                     char *

The path from which plugins are loaded.

Owner: InfinotedPluginManager

Flags: Read

Default value: NULL