EthosPluginInfo

EthosPluginInfo — plugin description during runtime

Synopsis

#define             ETHOS_PLUGIN_INFO_CONST             (obj)
struct              EthosPluginInfo;
struct              EthosPluginInfoClass;
gboolean            ethos_plugin_info_get_active        (EthosPluginInfo *plugin_info);
gchar **            ethos_plugin_info_get_authors       (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_copyright     (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_dependencies  (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_description   (EthosPluginInfo *plugin_info);
GList *             ethos_plugin_info_get_errors        (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_filename      (EthosPluginInfo *plugin_info);
guint               ethos_plugin_info_get_iage          (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_icon_name     (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_id            (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_loader        (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_module        (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_name          (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_version       (EthosPluginInfo *plugin_info);
const gchar *       ethos_plugin_info_get_website       (EthosPluginInfo *plugin_info);
gboolean            ethos_plugin_info_has_errors        (EthosPluginInfo *plugin_info);
gboolean            ethos_plugin_info_load_from_data    (EthosPluginInfo *plugin_info,
                                                         const gchar *group,
                                                         const gchar *data,
                                                         gsize length,
                                                         GError **error);
gboolean            ethos_plugin_info_load_from_file    (EthosPluginInfo *plugin_info,
                                                         const gchar *group,
                                                         const gchar *filename,
                                                         GError **error);
gboolean            ethos_plugin_info_load_from_key_file
                                                        (EthosPluginInfo *plugin_info,
                                                         const gchar *group,
                                                         GKeyFile *key_file,
                                                         GError **error);
EthosPluginInfo *   ethos_plugin_info_new               (void);
void                ethos_plugin_info_set_active        (EthosPluginInfo *plugin_info,
                                                         gboolean active);
void                ethos_plugin_info_set_filename      (EthosPluginInfo *plugin_info,
                                                         const gchar *filename);
void                ethos_plugin_info_set_id            (EthosPluginInfo *plugin_info,
                                                         const gchar *id);

Object Hierarchy

  GObject
   +----EthosPluginInfo

Properties

  "active"                   gboolean              : Read
  "authors"                  GStrv                 : Read
  "copyright"                gchar*                : Read
  "dependencies"             gchar*                : Read
  "description"              gchar*                : Read
  "filename"                 gchar*                : Read / Write
  "icon-name"                gchar*                : Read
  "id"                       gchar*                : Read / Write
  "loader"                   gchar*                : Read
  "module"                   gchar*                : Read
  "name"                     gchar*                : Read
  "version"                  gchar*                : Read
  "website"                  gchar*                : Read

Signals

  "loaded"                                         : Run First
  "unloaded"                                       : Run First

Description

EthosPluginInfo encapsulates information about a plugin during runtime. The data for an EthosPluginInfo is read from a plugin description file such as "my-plugin.example-plugin". This includes information about the plugin module to load, what EthosPluginLoader should be used, the author, description, and the icon for the plugin.

The naming of the plugin description files is derived from the name of the application or the name set using ethos_manager_set_app_name(). It is all lowercase and is named such as "name.appname-plugin" where appname is lowercase. Therfore, if the application was named "Marina" and the plugin was named "foo", an apt name for the description file would be "foo.marina-plugin".

The plugin description file consists of a simple GKeyFile format. The header for key-file is also derived from the application name. Therefore, if the application was named "Marina", the header for the key file would be "[Marina Plugin]".

A plugin for an application named "Sample" may look like:

# example.sample-plugin
[Sample Plugin]
Name=Example
Loader=python
Module=example
IAge=1
Authors=Foo;Bar;Baz
Copyright=MIT X11
Website=http://example.com

Details

ETHOS_PLUGIN_INFO_CONST()

#define ETHOS_PLUGIN_INFO_CONST(obj)		(G_TYPE_CHECK_INSTANCE_CAST ((obj), ETHOS_TYPE_PLUGIN_INFO, EthosPluginInfo const))


struct EthosPluginInfo

struct EthosPluginInfo;


struct EthosPluginInfoClass

struct EthosPluginInfoClass {
	GObjectClass parent_class;

	void (*reserved1) (void);
	void (*reserved2) (void);
	void (*reserved3) (void);
	void (*reserved4) (void);
};


ethos_plugin_info_get_active ()

gboolean            ethos_plugin_info_get_active        (EthosPluginInfo *plugin_info);

Retrieves whether or not the plugin is currently activated.

plugin_info :

An EthosPluginInfo

Returns :

TRUE if the plugin is currently active

ethos_plugin_info_get_authors ()

gchar **            ethos_plugin_info_get_authors       (EthosPluginInfo *plugin_info);

Retreives the authors of the plugin.

plugin_info :

An EthosPluginInfo

Returns :

A NULL terminated array of strings that contain the authors. This value should not be modified or freed.

ethos_plugin_info_get_copyright ()

const gchar *       ethos_plugin_info_get_copyright     (EthosPluginInfo *plugin_info);

Retrieves the copyright of the plugin

plugin_info :

An EthosPluginInfo

Returns :

A string containing the copyright. The string should not be modified or freed.

ethos_plugin_info_get_dependencies ()

const gchar *       ethos_plugin_info_get_dependencies  (EthosPluginInfo *plugin_info);

Retrieves the list of dependencies as a string. The string is a set of checks that must pass before the plugin can be loaded.

Such as:

"network >= 0.1 xmpp"

Would require the network plugin 0.1 or greater and any version of the xmpp plugin.

plugin_info :

An EthosPluginInfo

Returns :

A string containing the dependencies or NULL.

ethos_plugin_info_get_description ()

const gchar *       ethos_plugin_info_get_description   (EthosPluginInfo *plugin_info);

Retrieves the description of the plugin

plugin_info :

An EthosPluginInfo

Returns :

A string containing the description. The string should not be modified or freed.

ethos_plugin_info_get_errors ()

GList *             ethos_plugin_info_get_errors        (EthosPluginInfo *plugin_info);

Retrieves a list of errors that occurred while trying to load the plugin. If no errors have occurred, NULL is returned. The list is a copy however the GErrors contained are not. You should free the list with g_list_free().

plugin_info :

An EthosPluginInfo

Returns :

A GList containing GErrors that should be freed with g_list_free().

ethos_plugin_info_get_filename ()

const gchar *       ethos_plugin_info_get_filename      (EthosPluginInfo *plugin_info);

Retreives the filename that was used to load the plugin_info.

plugin_info :

An EthosPluginInfo

Returns :

A string or NULL

ethos_plugin_info_get_iage ()

guint               ethos_plugin_info_get_iage          (EthosPluginInfo *plugin_info);

Retreives the interface age that the plugin conforms to.

plugin_info :

An EthosPluginInfo

Returns :

a guint containing the age.

ethos_plugin_info_get_icon_name ()

const gchar *       ethos_plugin_info_get_icon_name     (EthosPluginInfo *plugin_info);

Retrieves the icon field for the EthosPluginInfo

plugin_info :

An EthosPluginInfo

Returns :

A string containing the icon name or NULL. This value should not be modified or freed.

ethos_plugin_info_get_id ()

const gchar *       ethos_plugin_info_get_id            (EthosPluginInfo *plugin_info);

Retreives the unique id of the plugin.

plugin_info :

An EthosPluginInfo

Returns :

The unique id of the plugin which should not be modified or freed.

ethos_plugin_info_get_loader ()

const gchar *       ethos_plugin_info_get_loader        (EthosPluginInfo *plugin_info);

Retrieves the name of the EthosPluginLoader that should load the plugin.

plugin_info :

An EthosPluginInfo

Returns :

The loader to use to load the plugin. This value should not be modified or freed.

ethos_plugin_info_get_module ()

const gchar *       ethos_plugin_info_get_module        (EthosPluginInfo *plugin_info);

Retreives the module that implements an EthosPlugin.

plugin_info :

An EthosPluginInfo

Returns :

The module of the plugin. This value should not be modified or freed.

ethos_plugin_info_get_name ()

const gchar *       ethos_plugin_info_get_name          (EthosPluginInfo *plugin_info);

Retrieves the name of the plugin.

plugin_info :

An EthosPluginInfo

Returns :

The name of the plugin. This value should not be freed or modified.

ethos_plugin_info_get_version ()

const gchar *       ethos_plugin_info_get_version       (EthosPluginInfo *plugin_info);

Retrieves the version of the plugin

plugin_info :

An EthosPluginInfo

Returns :

the version of the plugin

ethos_plugin_info_get_website ()

const gchar *       ethos_plugin_info_get_website       (EthosPluginInfo *plugin_info);

Retrieves the website url of the plugin

plugin_info :

An EthosPluginInfo

Returns :

A string containing the website. The string should not be modified or freed.

ethos_plugin_info_has_errors ()

gboolean            ethos_plugin_info_has_errors        (EthosPluginInfo *plugin_info);

Checks whether or not the plugin has had any errors.

plugin_info :

An EthosPluginInfo

Returns :

TRUE if the plugin had an error loading.

ethos_plugin_info_load_from_data ()

gboolean            ethos_plugin_info_load_from_data    (EthosPluginInfo *plugin_info,
                                                         const gchar *group,
                                                         const gchar *data,
                                                         gsize length,
                                                         GError **error);

Loads the plugin information from a buffer of information. The data should be in GKeyFile format.

plugin_info :

A EthosPluginInfo

group :

the group to load information from

data :

a buffer of data

length :

length of buffer to use

error :

A location for a GError or NULL

Returns :

TRUE on success. error is set on failure.

ethos_plugin_info_load_from_file ()

gboolean            ethos_plugin_info_load_from_file    (EthosPluginInfo *plugin_info,
                                                         const gchar *group,
                                                         const gchar *filename,
                                                         GError **error);

Loads the plugin information found within filename. If there is an error, FALSE is returned and error will be set.

plugin_info :

An EthosPluginInfo

group :

the keyfile group to extract information from

filename :

A path to the file containing the plugin info

error :

A location for a GError or NULL

Returns :

TRUE if the data was loaded successfully

ethos_plugin_info_load_from_key_file ()

gboolean            ethos_plugin_info_load_from_key_file
                                                        (EthosPluginInfo *plugin_info,
                                                         const gchar *group,
                                                         GKeyFile *key_file,
                                                         GError **error);

Loads the plugin information from key_file. The information is loaded from the group named group within the keyfile. Therfore, if group where "Sample Plugin" then the keyfile should have a group header such as "[Sample Plugin]" within it.

Upon failure, error is set and FALSE is returned.

plugin_info :

An EthosPluginInfo

group :

the name of the group to load

key_file :

A GKeyFile

error :

A location for a GError or NULL

Returns :

TRUE on success

ethos_plugin_info_new ()

EthosPluginInfo *   ethos_plugin_info_new               (void);

Creates a new EthosPluginInfo instance.

Returns :

The newly created EthosPluginInfo instance.

ethos_plugin_info_set_active ()

void                ethos_plugin_info_set_active        (EthosPluginInfo *plugin_info,
                                                         gboolean active);

Set the active status of the EthosPluginInfo. This is useful so that gui front-ends can keep track if the plugin is currently in use.

plugin_info :

An EthosPluginInfo

active :

if the EthosPluginInfo is active

ethos_plugin_info_set_filename ()

void                ethos_plugin_info_set_filename      (EthosPluginInfo *plugin_info,
                                                         const gchar *filename);

Sets the filename used to load the plugin-info.

plugin_info :

An EthosPluginInfo

filename :

The filename

ethos_plugin_info_set_id ()

void                ethos_plugin_info_set_id            (EthosPluginInfo *plugin_info,
                                                         const gchar *id);

Sets the id of the plugin. This is typically taking from the filename of the description file.

plugin_info :

An EthosPluginInfo

id :

the id of the plugin

Property Details

The "active" property

  "active"                   gboolean              : Read

Whether or not the plugin is currently loaded.

Default value: FALSE


The "authors" property

  "authors"                  GStrv                 : Read

The list of authors that have contributed to the plugin.


The "copyright" property

  "copyright"                gchar*                : Read

The copyright the plugin is released under such as "GPL-2".

Default value: NULL


The "dependencies" property

  "dependencies"             gchar*                : Read

Dependencies that must be loaded for the plugin to load. See ethos_plugin_info_get_dependencies().

Default value: NULL


The "description" property

  "description"              gchar*                : Read

A short description of the plugin.

Default value: NULL


The "filename" property

  "filename"                 gchar*                : Read / Write

The filename that was used to load the plugin.

Default value: NULL


The "icon-name" property

  "icon-name"                gchar*                : Read

The name of the icon to display in the manager widgets.

Default value: NULL


The "id" property

  "id"                       gchar*                : Read / Write

Unique identifier for the plugin.

Default value: NULL


The "loader" property

  "loader"                   gchar*                : Read

The name of the EthosPluginLoader that should be used to load the plugin.

Default value: NULL


The "module" property

  "module"                   gchar*                : Read

The name of the module that should be used to load the plugin.

Default value: NULL


The "name" property

  "name"                     gchar*                : Read

The name of the plugin.

Default value: NULL


The "version" property

  "version"                  gchar*                : Read

The version of the plugin. See ethos_plugin_info_get_version().

Default value: NULL


The "website" property

  "website"                  gchar*                : Read

The website to find more information on the plugin.

Default value: NULL

Signal Details

The "loaded" signal

void                user_function                      (EthosPluginInfo *plugin_info,
                                                        gpointer         user_data)        : Run First

Signal emitted when a new plugin is loaded.

plugin_info :

An EthosPluginInfo

user_data :

user data set when the signal handler was connected.

The "unloaded" signal

void                user_function                      (EthosPluginInfo *plugin_info,
                                                        gpointer         user_data)        : Run First

Signal emitted when the plugin is unloaded.

plugin_info :

An EthosPluginInfo

user_data :

user data set when the signal handler was connected.