NNTPGrab Plugin API

NNTPGrab Plugin API

Synopsis

#define             NNTPGRAB_PLUGIN_API_VERSION
enum                NNTPGrabErrCode;
enum                NNTPGrabDecoderRes;
typedef             NGPluginCoreData;
                    NGPluginCoreFuncs;
                    NGPlugin;
void                ng_plugin_set_name                  (NGPlugin *plugin_data,
                                                         const char *name);
void                ng_plugin_set_version               (NGPlugin *plugin_data,
                                                         const char *version);
void                ng_plugin_set_author                (NGPlugin *plugin_data,
                                                         const char *author);
void                ng_plugin_set_url                   (NGPlugin *plugin_data,
                                                         const char *url);
void                ng_plugin_set_description           (NGPlugin *plugin_data,
                                                         const char *description);
ngboolean           ng_plugin_get_is_loaded             (NGPlugin *plugin_data);
ngboolean           ng_plugin_register_function         (NGPlugin *plugin_data,
                                                         const char *function_name,
                                                         NGPluginFunction impl,
                                                         GSignalCMarshaller marshaller,
                                                         GType return_type,
                                                         int num_params,
                                                         ...);
void                ng_plugin_set_required_function     (NGPlugin *plugin_data,
                                                         const char *function_name);
ngboolean           ng_plugin_call                      (NGPlugin *plugin_data,
                                                         const char *function_name,
                                                         ...);
ngboolean           ng_plugin_create_event              (NGPlugin *plugin_data,
                                                         const char *event_name,
                                                         int num_params);
void                ng_plugin_set_required_event        (NGPlugin *plugin_data,
                                                         const char *event_name);
ngboolean           ng_plugin_connect_event             (NGPlugin *plugin_data,
                                                         const char *event_name,
                                                         NGPluginFunction impl,
                                                         void *user_data);
ngboolean           ng_plugin_disconnect_event_by_func  (NGPlugin *plugin_data,
                                                         NGPluginFunction impl,
                                                         void *user_data);
ngboolean           ng_plugin_emit_event                (NGPlugin *plugin_data,
                                                         const char *event_name,
                                                         const char *params[]);
void                ng_plugin_emit_log_msg              (NGPlugin *plugin_data,
                                                         NGLogLevel log_level,
                                                         const char *format,
                                                         ...);

Object Hierarchy

  GObject
   +----NGPlugin

Description

Details

NNTPGRAB_PLUGIN_API_VERSION

#define NNTPGRAB_PLUGIN_API_VERSION       2011116

enum NNTPGrabErrCode

typedef enum {
    NNTP_ERROR_NONE,
    NNTP_ERROR_HOST_NOT_FOUND,
    NNTP_ERROR_SSL_INITIALISE,
    NNTP_ERROR_CONNECTION_REFUSED,
    NNTP_ERROR_CONNECTION_TIMEOUT,
    NNTP_ERROR_READ,
    NNTP_ERROR_WRITE,
    NNTP_ERROR_INVALID_MSG,
    NNTP_ERROR_LOGIN_FAILURE,
    NNTP_ERROR_TOO_MANY_CONNECTIONS,
    NNTP_ERROR_PART_NOT_AVAILABLE,
    NNTP_ERROR_NO_SUCH_GROUP,
    NNTP_ERROR_UNABLE_TO_SAVE_PART,
} NNTPGrabErrCode;

enum NNTPGrabDecoderRes

typedef enum {
    DECODER_RESULT_COMPLETE,
    DECODER_RESULT_INCOMPLETE,
    DECODER_RESULT_NO_PARTS_AVAIL,
    DECODER_RESULT_ERROR
} NNTPGrabDecoderRes;

NGPluginCoreData

typedef struct _ng_plugin_core_data NGPluginCoreData;

NGPluginCoreFuncs

typedef struct {
    NGList *(*config_get_avail_servers) (void);
    void (*config_free_avail_servers) (NGList *servers);
    ngboolean (*config_get_server_info) (const char *servername, NGConfigServer *server);
    ngboolean (*config_add_server) (NGConfigServer new_server, char **errmsg);
    ngboolean (*config_del_server) (const char *servername, char **errmsg);
    ngboolean (*config_edit_server) (const char *servername, NGConfigServer server, char **errmsg);
    NGConfigOpts (*config_get_opts) (void);
    void (*config_set_opts) (NGConfigOpts opts);
    ngboolean (*config_save) (char **errmsg);
    ngboolean (*schedular_start) (void);
    ngboolean (*schedular_stop) (const char *reason, ngboolean wait);
    NGSchedularState (*schedular_get_state) (void);
    ngboolean (*schedular_add_file_to_queue) (const char *collection_name, const char *subject, const char *poster, time_t stamp, nguint64 file_size, NGList *groups, NGList *parts, char **errmsg);
    ngboolean (*schedular_del_file_from_queue) (const char *collection_name, const char *subject, char **errmsg);
    ngboolean (*schedular_restart_file) (const char *collection_name, const char *subject, char **errmsg);
    ngboolean (*schedular_save_queue) (char **errmsg);
    void (*schedular_foreach_file) (ForeachCollectionFunc collection_func, ForeachFileFunc file_func, ForeachGroupFunc group_func, void *data);
    ngboolean (*schedular_move_file) (const char *collection_name_src, const char *subject_src, const char *collection_name_dest, int position_dest);
    ngboolean (*schedular_move_collection) (const char *collection_name, int new_position);
    ngboolean (*schedular_mark_task_optional) (const char *collection_name, const char *subject, ngboolean is_optional);
    NGList *(*plugins_get_avail_plugins) (void);
    void (*plugins_free_avail_plugins) (NGList *plugins);
    ngboolean (*plugins_get_plugin_info) (const char *plugin_name, NNTPGrabPluginInfo *plugin_info);
    ngboolean (*plugins_load_plugin) (const char *plugin_name, char **errmsg);
    ngboolean (*plugins_unload_plugin) (const char *plugin_name, char **errmsg);
    ngboolean (*plugins_set_persistent) (const char *plugin_name, ngboolean persistent);
    void (*server_request_quit) (void);
    void (*set_emit_log_messages) (ngboolean val);
} NGPluginCoreFuncs;

Structure containing all the exported functions from the NNTPGrab Core

config_get_avail_servers ()

 Get a list of all the available usenet servers. Needs to be free'd using config_free_avail_servers

config_free_avail_servers ()

 Free a list of usenet servers returned by config_get_avail_servers

config_get_server_info ()

 Retrieve information from a configured usenet server

config_add_server ()

 Add a new usenet server to the configuration

config_del_server ()

 Delete a usenet server from the configuration

config_edit_server ()

 Change an already configured usenet server

config_get_opts ()

 Retrieve general configuration parameters

config_set_opts ()

 Change general configuration parameters

config_save ()

 Save the configuration to disk

schedular_start ()

 Start the schedular

schedular_stop ()

 Stop the schedular

schedular_get_state ()

 Retrieve the current state of the schedular

schedular_add_file_to_queue ()

 Add a file to the download queue

schedular_del_file_from_queue ()

 Remove a file from the download queue

schedular_restart_file ()

 Restart a file in the download queue

schedular_save_queue ()

 Force any changes in the download queue to be saved to disk

schedular_foreach_file ()

 Retrieve a list of all the items in the download queue (by using callback functions)

schedular_move_file ()

 Change the position of a file in the download queue

schedular_move_collection ()

 Change the position of a collection in the download queue

schedular_mark_task_optional ()

 Mark a task optional or non-optional

plugins_get_avail_plugins ()

 Retrieve a list of all the available plugins

plugins_free_avail_plugins ()

 Free a list as returned by the function plugins_get_avail_plugins

plugins_get_plugin_info ()

 Retrieve information about a specific plugin

plugins_load_plugin ()

 Load a plugin

plugins_unload_plugin ()

 Unload a plugin

plugins_set_persistent ()

 Indicate whether a plugin needs to be automatically loaded on startup

server_request_quit ()

 Give a signal to the frontend that it must quit the program

set_emit_log_messages ()

 Indicate whether log messages should be emit

NGPlugin

typedef struct _NGPlugin NGPlugin;

Structure containing plugin information

ng_plugin_set_name ()

void                ng_plugin_set_name                  (NGPlugin *plugin_data,
                                                         const char *name);

Set the name of the plugin

plugin_data :

 Structure containing plugin information

name :

 Name of the plugin. Will be used to identify plugins. Must be unique

ng_plugin_set_version ()

void                ng_plugin_set_version               (NGPlugin *plugin_data,
                                                         const char *version);

Set the version of the plugin

plugin_data :

 Structure containing plugin information

version :

 Version of the plugin

ng_plugin_set_author ()

void                ng_plugin_set_author                (NGPlugin *plugin_data,
                                                         const char *author);

Set the author of the plugin

plugin_data :

 Structure containing plugin information

author :

 The name of the author(s) of this plugin

ng_plugin_set_url ()

void                ng_plugin_set_url                   (NGPlugin *plugin_data,
                                                         const char *url);

Set the URL of the plugin

plugin_data :

 Structure containing plugin information

url :

 Location where users can find out more information about this plugin

ng_plugin_set_description ()

void                ng_plugin_set_description           (NGPlugin *plugin_data,
                                                         const char *description);

Set the description of the plugin

plugin_data :

 Structure containing plugin information

description :

 Description containing the functionality of this plugin

ng_plugin_get_is_loaded ()

ngboolean           ng_plugin_get_is_loaded             (NGPlugin *plugin_data);

Find out if the plugin is fully loaded at the moment

plugin_data :

 Structure containing plugin information

Returns :

 TRUE when the plugin is fully loaded

ng_plugin_register_function ()

ngboolean           ng_plugin_register_function         (NGPlugin *plugin_data,
                                                         const char *function_name,
                                                         NGPluginFunction impl,
                                                         GSignalCMarshaller marshaller,
                                                         GType return_type,
                                                         int num_params,
                                                         ...);

Create a new function which can be called from other plugins

plugin_data :

 Structure containing plugin information

function_name :

 The name of the function. Must be unique

impl :

 Pointer to the implementation of this function

marshaller :

 The function to translate arrays of parameter values to proper parameters

return_type :

 The return type of the function

num_params :

 The number of arguments which this function expects

... :

 A list of parameter types

Returns :

 TRUE if the function was successfully registered, FALSE if it was already registered

ng_plugin_set_required_function ()

void                ng_plugin_set_required_function     (NGPlugin *plugin_data,
                                                         const char *function_name);

Indicate that the plugin requires a function from another plugin to function properly

plugin_data :

 Structure containing plugin information

function_name :

 The name of the function which this plugin requires for proper operation

ng_plugin_call ()

ngboolean           ng_plugin_call                      (NGPlugin *plugin_data,
                                                         const char *function_name,
                                                         ...);

Call a function from another plugin

plugin_data :

 Structure containing plugin information

function_name :

 The name of the function which needs to be called

... :

 Variable number of arguments to pass on to the function. If a return value is expected, it must be the last argument

Returns :

 TRUE is the function has been called, FALSE if the function isn't registered

ng_plugin_create_event ()

ngboolean           ng_plugin_create_event              (NGPlugin *plugin_data,
                                                         const char *event_name,
                                                         int num_params);

Create a new event on which other plugins can register to

plugin_data :

 Structure containing plugin information

event_name :

 The name of the event. Must be unique

num_params :

 The number of arguments which this event expects

Returns :

 TRUE if the event was successfully created, FALSE if it was already registered

ng_plugin_set_required_event ()

void                ng_plugin_set_required_event        (NGPlugin *plugin_data,
                                                         const char *event_name);

Indicate that the plugin requires a event from another plugin to function properly

plugin_data :

 Structure containing plugin information

event_name :

 The name of the event which this plugin requires for proper operation

ng_plugin_connect_event ()

ngboolean           ng_plugin_connect_event             (NGPlugin *plugin_data,
                                                         const char *event_name,
                                                         NGPluginFunction impl,
                                                         void *user_data);

Connect to an event exported from another plugin

plugin_data :

 Structure containing plugin information

event_name :

 The name of the event

impl :

 The callback function which needs to be called when the event is emit

user_data :

 Optional callback data

Returns :

 TRUE if the event was successfully connection. FALSE if the event_name isn't known

ng_plugin_disconnect_event_by_func ()

ngboolean           ng_plugin_disconnect_event_by_func  (NGPlugin *plugin_data,
                                                         NGPluginFunction impl,
                                                         void *user_data);

Disconnect an event handler Most plugins don't need to use this function as it will be done automatically on unload

plugin_data :

 Structure containing plugin information

impl :

 The callback function

user_data :

 Optional callback data

Returns :

 TRUE if the event handler was successfully disconnected. FALSE if no connection exists

ng_plugin_emit_event ()

ngboolean           ng_plugin_emit_event                (NGPlugin *plugin_data,
                                                         const char *event_name,
                                                         const char *params[]);

Emit an event

plugin_data :

 Structure containing plugin information

event_name :

 The name of the event which needs to be emit

params :

 NULL-terminated array of arguments to pass on to the event handlers

Returns :

 TRUE if the event was successfully emit. FALSE if the event_name isn't registered yet

ng_plugin_emit_log_msg ()

void                ng_plugin_emit_log_msg              (NGPlugin *plugin_data,
                                                         NGLogLevel log_level,
                                                         const char *format,
                                                         ...);

Emit a message for logging

plugin_data :

 Structure containing plugin information

log_level :

 The log level

format :

 The format string

... :

 Variable number of arguments containing data for the given format
Generated by GTK-Doc V1.15