NNTPGrab

/* 

    Copyright (C) 2005-2012  Erik van Pienbroek

    This program is free software; you can redistribute it and/or modify

    it under the terms of the GNU General Public License as published by

    the Free Software Foundation; either version 2 of the License, or

    (at your option) any later version.

    This program is distributed in the hope that it will be useful,

    but WITHOUT ANY WARRANTY; without even the implied warranty of

    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License

    along with this program; if not, write to the Free Software

    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

*/

#ifndef _NNTPGRAB_PLUGIN_H_

#define _NNTPGRAB_PLUGIN_H_

#include 

#include 

#include 

G_BEGIN_DECLS

#define NNTPGRAB_PLUGIN_API_VERSION       20111201

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;

typedef enum {

    DECODER_RESULT_COMPLETE,

    DECODER_RESULT_INCOMPLETE,

    DECODER_RESULT_NO_PARTS_AVAIL,

    DECODER_RESULT_ERROR

} NNTPGrabDecoderRes;

typedef struct _ng_plugin_core_data NGPluginCoreData;

/** 

 * NGPluginCoreFuncs:

 * @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

 * @config_get_folder_listing:     Retrieve a list containing all the sub-folders which are in the given folder. Needs to be free'd using config_free_folder_listing

 * @config_free_folder_listing:    Free a list of sub-folders

 * @config_get_config_folder:      Retrieve the folder where all configuration files can be stored. Needs to be free'd using ng_free

 * @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

 * @plugins_call_plugin_method:    Call a method of a plugin

 * @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

 *

 * Structure containing all the exported functions from the NNTPGrab Core

 *

 */

typedef struct _ng_plugin_core_funcs {

    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);

    char *(*config_get_config_folder) (void);

    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);

    NGVariant *(*plugins_call_plugin_method) (const char *plugin_name, const char *method, NGVariant *parameters, char **errmsg);

    void (*server_request_quit) (void);

    void (*set_emit_log_messages) (ngboolean val);

} NGPluginCoreFuncs;

/** 

 * NGPlugin:

 * @core_data:     Internal information for the NNTPGrab Core. Must remain untouched

 * @core_funcs:    Structure containing all the exported functions from the NNTPGrab Core

 * @priv:          Plugin-specific data can be saved in this field

 *

 * Structure containing plugin information

 */

typedef struct _ng_plugin {

    GObject parent;

    NGPluginCoreData *core_data;

    NGPluginCoreFuncs core_funcs;

    gpointer priv;

} NGPlugin;

#define NG_PLUGIN_FUNCTION(f)                 ((NGPluginFunction) (f))

typedef void (*NGPluginFunction)              (void);

/** 

 * ng_plugin_set_name:

 * @plugin_data:   Structure containing plugin information

 * @name:          Name of the plugin. Will be used to identify plugins. Must be unique

 *

 * Set the name of the plugin

 */

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

/** 

 * ng_plugin_set_version:

 * @plugin_data:   Structure containing plugin information

 * @version:       Version of the plugin

 *

 * Set the version of the plugin

 */

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

/** 

 * ng_plugin_set_author:

 * @plugin_data:   Structure containing plugin information

 * @author:        The name of the author(s) of this plugin

 *

 * Set the author of the plugin

 */

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

/** 

 * ng_plugin_set_url:

 * @plugin_data:   Structure containing plugin information

 * @url:           Location where users can find out more information about this plugin

 *

 * Set the URL of the plugin

 */

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

/** 

 * ng_plugin_set_description:

 * @plugin_data:   Structure containing plugin information

 * @description:   Description containing the functionality of this plugin

 *

 * Set the description of the plugin

 */

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

/** 

 * ng_plugin_get_is_loaded:

 * @plugin_data:   Structure containing plugin information

 *

 * Find out if the plugin is fully loaded at the moment

 *

 * Returns:        TRUE when the plugin is fully loaded

 */

ngboolean ng_plugin_get_is_loaded(NGPlugin *plugin_data);

/** 

 * ng_plugin_register_function:

 * @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

 *

 * Create a new function which can be called from other plugins

 *

 * Returns:        TRUE if the function was successfully registered, FALSE if it was already registered

 */

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

/** 

 * ng_plugin_set_required_function:

 * @plugin_data:   Structure containing plugin information

 * @function_name: The name of the function which this plugin requires for proper operation

 *

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

 */

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

/** 

 * ng_plugin_call:

 * @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

 *

 * Call a function from another plugin

 *

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

 */

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

/** 

 * ng_plugin_create_event:

 * @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

 *

 * Create a new event on which other plugins can register to

 *

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

 */

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

/** 

 * ng_plugin_set_required_event:

 * @plugin_data:   Structure containing plugin information

 * @event_name:    The name of the event which this plugin requires for proper operation

 *

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

 */

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

/** 

 * ng_plugin_connect_event:

 * @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

 *

 * Connect to an event exported from another plugin

 *

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

 */

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

/** 

 * ng_plugin_disconnect_event_by_func:

 * @plugin_data:   Structure containing plugin information

 * @impl:          The callback function

 * @user_data:     Optional callback data

 *

 * Disconnect an event handler

 * Most plugins don't need to use this function as it will be done automatically on unload

 *

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

 */

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

/** 

 * ng_plugin_emit_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

 *

 * Emit an event

 *

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

 */

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

/** 

 * ng_plugin_emit_log_msg:

 * @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

 *

 * Emit a message for logging

 */

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

G_END_DECLS

#endif /* _NNTPGRAB_PLUGIN_H_ */