NNTPGrab

/* 

    Copyright (C) 2005-2010  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_GLUE_H_

#define _NNTPGRAB_GLUE_H_

#include "nntpgrab_types.h"

#ifdef  __cplusplus

extern "C" {

#endif

#define NNTPGRAB_GLUE_VERSION    20110710

#define NNTPGRAB_TYPE_GLUE              (nntpgrab_glue_get_type ())

#define NNTPGRAB_GLUE(object)           (NG_TYPE_CHECK_INSTANCE_CAST ((object), NNTPGRAB_TYPE_GLUE, NntpgrabGlue))

#define NNTPGRAB_GLUE_CLASS(klass)      (NG_TYPE_CHECK_CLASS_CAST ((klass), NNTPGRAB_TYPE_GLUE, NntpgrabGlueClass))

#define IS_NNTPGRAB_GLUE(object)        (NG_TYPE_CHECK_INSTANCE_TYPE ((object), NNTPGRAB_TYPE_GLUE))

#define IS_NNTPGRAB_GLUE_CLASS(klass)   (NG_TYPE_CHECK_CLASS_TYPE ((klass), NNTPGRAB_TYPE_GLUE))

#define NNTPGRAB_GLUE_GET_CLASS(obj)    (NG_TYPE_INSTANCE_GET_CLASS ((obj), NNTPGRAB_TYPE_GLUE, NntpgrabGlueClass))

typedef struct NntpgrabGlue NntpgrabGlue;

typedef struct NntpgrabGlueClass NntpgrabGlueClass;

NGType nntpgrab_glue_get_type(void);

/** 

 * nntpgrab_glue_new:

 *

 * Creates a new instance of the NntpgrabGlue object. This is required for all other NNTPGrab functions

 *

 * Return value: An instance of the NntpgrabGlue which need to be used for other NNTPGrab functions

 */

NntpgrabGlue *nntpgrab_glue_new(void);

/** 

 * nntpgrab_glue_init:

 * @glue:                               An instance of the NntpgrabGlue

 * @glue_version:                       Needs to be NNTPGRAB_GLUE_VERSION, this is used to prevent version conflicts

 * @err:           (allow-none) (out):  Pointer to a char*. If an errors occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 *

 * Initialize the NNTPGrab Glue library. This function needs to be called before any other NNTPGrab function can be called

 *

 * Return value:                        TRUE on success, FALSE if an error has occured (the reason is saved in the err variable)

 */

ngboolean nntpgrab_glue_init(NntpgrabGlue *glue, int glue_version, char **err);

/** 

 * nntpgrab_glue_destroy:

 * @obj:           An instance of the NntpgrabGlue

 *

 * Cleanup the NNTPGrab Glue library. After this function is called, the NntpgrabGlue instance can't be used anymore

 */

void nntpgrab_glue_destroy(NntpgrabGlue *obj);

/** 

 * nntpgrab_glue_connect:

 * @obj:                              An instance of the NntpgrabGlue

 * @hostname:    (allow-none):        The hostname where the NNTPGrab Server is running. If this is NULL, the standalone version of NNTPGrab will be started. In that case, the contents of the fields port, username, password and use_ssl are ignored

 * @port:                             The port where the NNTPGrab Server is running

 * @username:    (allow-none):        The username of an user who is allowed to connect to the NNTPGrab Server. This feature isn't implemented yet, so keep it NULL for now

 * @password:    (allow-none):        The password of an user who is allowed to connect to the NNTPGrab Server. This feature isn't implemented yet, so keep it NULL for now

 * @use_ssl:                          Do we want to have an encrypted connection to the NNTPGrab Server. This feature isn't implemented yet, so keep it FALSE for now

 * @err:         (allow-none) (out):  Pointer to a char*. If an errors occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 * @warnings:    (allow-none) (out):  Pointer to a char*. If an (non-fatal) warning occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 *

 * Connect to an already running NNTPGrab Server OR start the standalone version of NNTPGrab

 * Note that even if this function returns TRUE, the warnings argument MAY be set

 *

 * Returns:      TRUE on success, FALSE on failure

 */

ngboolean nntpgrab_glue_connect(NntpgrabGlue *obj, const char *hostname, int port, const char *username, const char *password, ngboolean use_ssl, char **err, char **warnings);

/** 

 * nntpgrab_glue_get_is_connected:

 * @obj:       An instance of the NntpgrabGlue

 *

 * Find out is we are already connected to an NNTPGrab Server

 *

 * Returns:         TRUE if we are already connected, FALSE if not

 */

ngboolean nntpgrab_glue_get_is_connected(NntpgrabGlue *obj);

/** 

 * nntpgrab_glue_get_is_standalone:

 * @obj:      An instance of the NntpgrabGlue

 *

 * Find out if we are running the standalone version of NNTPGrab

 *

 * Returns:         TRUE if we are running the standalone version of NNTPGrab, FALSE if not

 */

ngboolean nntpgrab_glue_get_is_standalone(NntpgrabGlue *obj);

/** 

 * nntpgrab_glue_set_emit_log_messages:

 * @param obj           An instance of the NntpgrabGlue

 * @param val           Boolean which needs to be set to TRUE if log messages need to be emit or FALSE when they don't

 *

 * Indicate whether log messages should be emit the frontend

 */

void     nntpgrab_glue_set_emit_log_messages(NntpgrabGlue *obj, ngboolean val);

/** 

 * nntpgrab_glue_kill_server:

 * @obj:           An instance of the NntpgrabGlue

 *

 * Shutdown the NNTPGrab Server where we're connected to

 * Note: After this function is called, all communication with the NNTPGrab Server will be killed and the frontend should shutdown itself

 */

void nntpgrab_glue_kill_server(NntpgrabGlue *obj);

/** 

 * nntpgrab_glue_signal_connect:

 * @obj:           An instance of the NntpgrabGlue

 * @signal_name:   The name of the signal for which a signaler handler needs to be registered

 * @cb_handler:    The function which need to be called every time the given signal is emit

 * @data:          Data used as extra argument in the callback functions

 *

 * Register a signal handler

 * The file nntpgrab_core/marshall.list contains a list of known signals and callback function prototypes for the NntpgrabGlue

 */

void     nntpgrab_glue_signal_connect(NntpgrabGlue *obj, const char *signal_name, NGCallback cb_handler, void *data);

/** 

 * nntpgrab_glue_signal_handler_disconnect_by_func:

 * @obj:           An instance of the NntpgrabGlue

 * @cb_handler:    The callback function which need to be unregistered

 * @data:          The callback data used for the given cb_handler

 *

 * Un-register a signal handler

 */

void     nntpgrab_glue_signal_handlers_disconnect_by_func(NntpgrabGlue *obj, NGCallback cb_handler, void *data);

/** 

 * nntpgrab_glue_signal_handlers_block_by_func:

 * @obj:           An instance of the NntpgrabGlue

 * @cb_handler:    The callback function which need to be temporary blocked

 * @data:          The callback data used for the given cb_handler

 *

 * Temporary disable a signal handler for a given callback function

 */

void     nntpgrab_glue_signal_handlers_block_by_func(NntpgrabGlue *obj, NGCallback cb_handler, void *data);

/** 

 * nntpgrab_glue_signal_handlers_unlock_by_func:

 * @obj:           An instance of the NntpgrabGlue

 * @cb_handler:    The callback function which need to be un-blocked

 * @data:          The callback data used for the given cb_handler

 *

 * Re-enable a signal handler for a given callback function

 */

void     nntpgrab_glue_signal_handlers_unblock_by_func(NntpgrabGlue *obj, NGCallback cb_handler, void *data);

/** 

 * nntpgrab_glue_config_get_avail_servers:

 * @obj:       An instance of the NntpgrabGlue

 *

 * Retrieve a list of the available usenet servers

 *

 * Return value: (transfer full) (element-type utf8): A list of all the available usenet servers. Needs to be freed using nntpgrab_config_free_avail_servers()

 */

NGList         *nntpgrab_glue_config_get_avail_servers(NntpgrabGlue *obj);

/** 

 * nntpgrab_glue_config_free_avail_servers: (skip)

 * @obj           An instance of the NntpgrabGlue

 * @servers       A list of the available usenet servers as returned from the function nntpgrab_config_get_avail_servers()

 *

 * Free the list of available usenet servers

 */

void            nntpgrab_glue_config_free_avail_servers(NntpgrabGlue *obj, NGList *servers);

/** 

 * nntpgrab_glue_config_get_server_info:

 * @obj:                  An instance of the NntpgrabGlue

 * @servername:           The name of the server whose details should be retrieved

 * @server:       (out):  The address of a ConfigServer structure which will be used to fill in the configuration details

 *

 * Get the configuration details about a specific usenet server

 *

 * Returns:               TRUE on success (server will be filled in), FALSE if the server isn't known

 */

ngboolean       nntpgrab_glue_config_get_server_info(NntpgrabGlue *obj, const char *servername, NGConfigServer *server);

/** 

 * nntpgrab_glue_config_add_server:

 * @obj:                              An instance of the NntpgrabGlue

 * @new_server:                       A structure containing the details about the new usenet server

 * @errmsg:      (allow-none) (out):  Pointer to a char*. If an errors occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 *

 * Add a new usenet server to the NNTPGrab configuration

 *

 * Returns:                           TRUE when the server was successfully added. FALSE on failure (the reason will be placed in the errmsg field)

 */

ngboolean       nntpgrab_glue_config_add_server(NntpgrabGlue *obj, NGConfigServer new_server, char **errmsg);

/** 

 * nntpgrab_glue_config_del_server:

 * @obj:                              An instance of the NntpgrabGlue

 * @servername:                       The name of the server whose entry should be removed

 * @errmsg:      (allow-none) (out):  Pointer to a char*. If an errors occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 *

 * Remove a usenet server from the NNTPGrab configuration

 *

 * Returns:                           TRUE when the server was successfully removed. FALSE on failure (the reason will be placed in the errmsg field)

 */

ngboolean       nntpgrab_glue_config_del_server(NntpgrabGlue *obj, const char *servername, char **errmsg);

/** 

 * nntpgrab_glue_config_edit_server:

 * @obj:                              An instance of the NntpgrabGlue

 * @servername:                       The name of the server whose entry should be adjusted

 * @server:                           A structure containing the new configuration details of the given servername

 * @errmsg:      (allow-none) (out):  Pointer to a char*. If an errors occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 *

 * Adjust the configuration details of an usenet server

 *

 * Returns:                           TRUE when the server was successfully adjusted. FALSE on failure (the reason will be placed in the errmsg field)

 */

ngboolean       nntpgrab_glue_config_edit_server(NntpgrabGlue *obj, const char *servername, NGConfigServer server, char **errmsg);

/** 

 * nntpgrab_glue_config_get_opts:

 * @obj:           An instance of the NntpgrabGlue

 *

 * Retrieve the general configuration options

 *

 * Returns:        A structure containing the general configuration options

 */

NGConfigOpts    nntpgrab_glue_config_get_opts(NntpgrabGlue *obj);

/** 

 * nntpgrab_glue_config_set_opts:

 * @obj:           An instance of the NNTPGrabCore

 * @opts:          A structure containing the new general configuration options

 *

 * Adjust the general configuration options

 *

 */

void            nntpgrab_glue_config_set_opts(NntpgrabGlue *obj, NGConfigOpts opts);

/** 

 * nntpgrab_glue_config_get_folder_listing:

 * @obj:                                              An instance of the NntpgrabGlue

 * @parent:    (allow-none):                          The name of the directory whose sub-folders should be retrieved. When this is NULL all available drives will be returned (when the host is running Windows)

 * @folders:   (element-type NNTPGrabFolder) (out):   Pointer to a NGList*. The list of sub-folders will be placed in this field. This list needs to be free'd using the function nntpgrab_config_free_folder_listing()

 *

 * Retrieves a list containing all the sub-folders which are in the given folder

 *

 * Returns:                                           TRUE on sucess, FALSE if the given directory isn't found or readable

 */

ngboolean       nntpgrab_glue_config_get_folder_listing(NntpgrabGlue *obj, const char *parent, NGList **folders);

/** 

 * nntpgrab_glue_config_free_folder_listing: (skip)

 * @obj:           An instance of the NntpgrabGlue

 * @folders:       A list containing subfolders as returned by the function nntpgrab_config_get_folder_listing()

 *

 * Free a list of sub-folders

 */

void            nntpgrab_glue_config_free_folder_listing(NntpgrabGlue *obj, NGList *folders);

/** 

 * nntpgrab_glue_schedular_start:

 * @obj:        An instance of the NntpgrabGlue

 *

 * Start the NNTPGrab schedular

 *

 * Returns:     TRUE is the schedular was successfully started, FALSE if the schedular was already running or in the 'stopping' state

 */

ngboolean       nntpgrab_glue_schedular_start(NntpgrabGlue *obj);

/** 

 * nntpgrab_glue_schedular_stop:

 * @obj:           An instance of the NntpgrabGlue

 * @wait:          Whether this function should wait until the schedular really has stopped

 *

 * Stop the NNTPGrab schedular

 *

 * Returns:        TRUE is schedular was successfully stopped, FALSE if the schedular was already stopped or the in 'stopping' state

 */

ngboolean       nntpgrab_glue_schedular_stop(NntpgrabGlue *obj, ngboolean wait);

/** 

 * nntpgrab_glue_schedular_get_state:

 * @obj:           An instance of the NntpgrabGlue

 *

 * Retrieve the current state of the schedular

 *

 * Returns:        The current state of the schedular

 */

NGSchedularState  nntpgrab_glue_schedular_get_state(NntpgrabGlue *obj);

/** 

 * nntpgrab_glue_schedular_add_task_to_queue:

 * @obj:                                            An instance of the NntpgrabGlue

 * @collection_name:                                The name of the collection in which this task should be added. If there is no collection in the download queue with the given name, it will automatically be created

 * @subject:                                        The subject of the file

 * @poster:                                         The name of the poster

 * @stamp:                                          The UNIX timestamp of the post date

 * @file_size:                                      The size of the file in bytes

 * @groups:           (element-type utf8):          A list containing the newsgroups in which this file is posted

 * @parts:            (element-type NNTPGrabPart):  A list containing the message-id's of all the individual parts belonging to this file

 * @errmsg:           (allow-none) (out):           Pointer to a char*. If an errors occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 *

 * Add a new task to the download queue

 *

 * Returns:               TRUE if the task was succesfully added, FALSE if an error occured (errmsg will be set)

 */

ngboolean       nntpgrab_glue_schedular_add_task_to_queue(NntpgrabGlue *obj, const char *collection_name, const char *subject, const char *poster, time_t stamp, nguint64 file_size, NGList *groups, NGList *parts, char **errmsg);

/** 

 * nntpgrab_glue_schedular_del_task_from_queue:

 * @obj:                                    An instance of the NntpgrabGlue

 * @collection_name:                        The name of the collection in which the task resides

 * @subject:                                The subject of the file

 * @errmsg:           (allow-none) (out):   Pointer to a char*. If an errors occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 *

 * Remove a task from the download queue

 *

 * Returns:                                 TRUE if the task was successfully removed, FALSE if an error occured (errmsg will be set)

 */

ngboolean       nntpgrab_glue_schedular_del_task_from_queue(NntpgrabGlue *obj, const char *collection_name, const char *subject, char **errmsg);

/** 

 * nntpgrab_glue_schedular_restart_task:

 * @obj:                                    An instance of the NntpgrabGlue

 * @collection_name:                        The name of the collection in which the task resides

 * @subject:                                The subject of the file

 * @errmsg:           (allow-none) (out):   Pointer to a char*. If an errors occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 *

 * Restart a task in the download queue

 *

 * Returns:                                 TRUE if the task was successfully removed, FALSE if an error occured (errmsg will be set)

 */

ngboolean       nntpgrab_glue_schedular_restart_task(NntpgrabGlue *obj, const char *collection_name, const char *subject, char **errmsg);

/** 

 * nntpgrab_glue_schedular_save_queue:

 * @obj:                            An instance of the NntpgrabGlue

 * @errmsg:    (allow-none) (out):  Pointer to a char*. If an errors occurs, the reason will be placed in this field. Needs to be freed using ngfree(). Can be NULL to ignore errors

 *

 * Save any recent changes in the download queue to the disk.

 * The download queue will automatically be saved every now and then by the NNTPGrab Core, but it is recommended to perform a manual save as soon as a lot of file have been added to the download queue (like directly after an NZB import)

 *

 * Returns:                         TRUE if the task was successfully removed, FALSE if an error occured (errmsg will be set)

 */

ngboolean       nntpgrab_glue_schedular_save_queue(NntpgrabGlue *obj, char **errmsg);

/** 

 * nntpgrab_glue_schedular_foreach_task:

 * @obj:                             An instance of the NntpgrabGlue

 * @collection_func:  (allow-none):  The function which should be called for every collection in the download queue

 * @file_func:        (allow-none):  The function which should be called for every file in the download queue

 * @group_func:       (allow-none):  The function which should be called for every group in every file in the download queue

 * @data:             (allow-none):  Pointer to some data which will be made available in the callback functions

 *

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

 */

void            nntpgrab_glue_schedular_foreach_task(NntpgrabGlue *obj, ForeachCollectionFunc collection_func, ForeachFileFunc file_func, ForeachGroupFunc group_func, void *data);

/** 

 * nntpgrab_glue_schedular_move_task:

 * @obj:                                 An instance of the NntpgrabGlue

 * @collection_name_src:                 The name of the collection where the subject is part of

 * @subject_src:                         The name of the subject which needs to be moved

 * @collection_name_dest: (allow-none):  The name of the collection where the subject needs to be moved to (if NULL, the task will stay in the same collection as it is now)

 * @position_dest:                       The position in collection_name_dest where the task needs to be placed at

 *

 * Move a task in the download queue

 *

 * Returns:                              TRUE on success, FALSE if the collection_name_src or subject_src could not be found

 */

ngboolean       nntpgrab_glue_schedular_move_task(NntpgrabGlue *obj, const char *collection_name_src, const char *subject_src, const char *collection_name_dest, int position_dest);

/** 

 * nntpgrab_glue_schedular_move_collection:

 * @obj:               An instance of the NntpgrabGlue

 * @collection_name:   The name of the collection which needs to be moved

 * @new_position:      The position in the download queue where the collection needs to be moved to

 *

 * Move the position of a collection in the download queue

 *

 * Returns:           TRUE on success, FALSE is the collection_name could not be found

 */

ngboolean       nntpgrab_glue_schedular_move_collection(NntpgrabGlue *obj, const char *collection_name, int new_position);

/** 

 * nntpgrab_glue_schedular_mark_task_optional:

 * @obj:               An instance of the NntpgrabGlue

 * @collection_name:   The name of the collection in which the task resides

 * @subject:           The subject of the task

 * @is_optional:       TRUE if the task needs to be marked optional, FALSE is the task needs to be marked non-optional

 *

 * Mark a task in the download queue optional or non-optional

 *

 * Returns:            TRUE if the task was successfully updated, FALSE if the task wasn't found

 */

ngboolean       nntpgrab_glue_schedular_mark_task_optional(NntpgrabGlue *obj, const char *collection_name, const char *subject, ngboolean is_optional);

/** 

 * nntpgrab_glue_plugins_get_avail_plugins:

 * @obj:             An instance of the NntpgrabGlue

 *

 * Retrieve a list of all the available plugins

 *

 * Returns:          A list containing all the available plugins (const char* items). Needs to be free'd using nntpgrab_plugins_free_avail_plugins()

 */

NGList         *nntpgrab_glue_plugins_get_avail_plugins(NntpgrabGlue *obj);

/** 

 * nntpgrab_glue_plugins_free_avail_plugins: (skip)

 * @obj:               An instance of the NNTPGrabCore

 * @plugins:           The list of available plugins

 *

 * Free a list as returned by the function nntpgrab_plugins_get_avail_plugins()

 */

void            nntpgrab_glue_plugins_free_avail_plugins(NntpgrabGlue *obj, NGList *plugins);

/** 

 * nntpgrab_glue_plugins_get_plugin_info:

 * @obj:                   An instance of the NntpgrabGlue

 * @plugin_name:           The name of the plugin whose information needs to be retrieved

 * @plugin_info:  (out):   Pointer to an NNTPGrabPluginInfo structure where the plugin information can be saved

 *

 * Retrieve information about a specific plugin

 *

 * Returns:                TRUE on success, FALSE if the given plugin_name is unknown

 */

ngboolean       nntpgrab_glue_plugins_get_plugin_info(NntpgrabGlue *obj, const char *plugin_name, NNTPGrabPluginInfo *plugin_info);

/** 

 * nntpgrab_glue_plugins_load_plugin:

 * @obj:                                An instance of the NntpgrabGlue

 * @plugin_name:                        The name of the plugin which needs to be loaded

 * @errmsg:       (allow-none) (out):   Pointer to a location where an error message can be saved. Needs to be free'd using ng_free()

 *

 * Load a plugin

 *

 * Returns:                             TRUE on success, FALSE is the given plugin_name is unknown or an error occured while loading the plugin

 */

ngboolean       nntpgrab_glue_plugins_load_plugin(NntpgrabGlue *obj, const char *plugin_name, char **errmsg);

/** 

 * nntpgrab_glue_plugins_unload_plugin:

 * @obj:                                An instance of the NntpgrabGlue

 * @plugin_name:                        The name of the plugin which needs to be unloaded

 * @errmsg:       (allow-none) (out):   Pointer to a location where an error message can be saved. Needs to be free'd using ng_free()

 *

 * Unload a plugin

 *

 * Returns:                             TRUE on success, FALSE is the given plugin_name is unknown or an error occured while unloading the plugin

 */

ngboolean       nntpgrab_glue_plugins_unload_plugin(NntpgrabGlue *obj, const char *plugin_name, char **errmsg);

/** 

 * nntpgrab_glue_plugins_set_persistent:

 * @obj:               An instance of the NntpgrabGlue

 * @plugin_name:       The name of the plugin

 * @persistent:        Flag to indicate whether this plugin needs to be automatically loaded or not

 *

 * Indicate whether a plugin needs to be automatically loaded on startup

 * This API function is unused in NNTPGrab 0.6

 *

 * Returns:            TRUE on success, FALSE is the given plugin_name is unknown

 */

ngboolean       nntpgrab_glue_plugins_set_persistent(NntpgrabGlue *obj, const char *plugin_name, ngboolean persistent);

#ifdef  __cplusplus

}

#endif

#endif /* _NNTPGRAB_GLUE_H_ */