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_H_

#define _NNTPGRAB_H_

#include "nntpgrab_types.h"

#ifdef  __cplusplus

extern "C" {

#endif

#define NNTPGRAB_API_VERSION    20110710

#define NNTPGRAB_TYPE_CORE              (nntpgrab_core_get_type ())

#define NNTPGRAB_CORE(object)           (NG_TYPE_CHECK_INSTANCE_CAST ((object), NNTPGRAB_TYPE_CORE, NntpgrabCore))

#define NNTPGRAB_CORE_CLASS(klass)      (NG_TYPE_CHECK_CLASS_CAST ((klass), NNTPGRAB_TYPE_CORE, NntpgrabCoreClass))

#define IS_NNTPGRAB_CORE(object)        (NG_TYPE_CHECK_INSTANCE_TYPE ((object), NNTPGRAB_TYPE_CORE))

#define IS_NNTPGRAB_CORE_CLASS(klass)   (NG_TYPE_CHECK_CLASS_TYPE ((klass), NNTPGRAB_TYPE_CORE))

#define NNTPGRAB_CORE_GET_CLASS(obj)    (NG_TYPE_INSTANCE_GET_CLASS ((obj), NNTPGRAB_TYPE_CORE, NntpgrabCoreClass))

typedef struct NntpgrabCore NntpgrabCore;

typedef struct NntpgrabCoreClass NntpgrabCoreClass;

NGType nntpgrab_core_get_type(void);

/** 

 * nntpgrab_core_new:

 *

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

 *

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

 */

NntpgrabCore   *nntpgrab_core_new(void);

/** 

 * nntpgrab_core_init:

 * @obj:                          An instance of the NntpgrabCore

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

 * @err:      (out) (allow-none): 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: (out) (allow-none): 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

 *

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

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

 *

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

 */

ngboolean        nntpgrab_core_init(NntpgrabCore *obj, int version, char **err, char **warnings);

/** 

 * nntpgrab_core_destroy: (skip)

 * @obj:        An instance of the NntpgrabCore

 *

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

 */

void            nntpgrab_core_destroy(NntpgrabCore *obj);

/** 

 * nntpgrab_core_config_get_avail_servers:

 * @obj:        An instance of the NntpgrabCore

 *

 * 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_core_config_get_avail_servers(NntpgrabCore *obj);

/** 

 * nntpgrab_core_config_free_avail_servers: (skip)

 * @obj:           An instance of the NntpgrabCore

 * @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_core_config_free_avail_servers(NntpgrabCore *obj, NGList *servers);

/** 

 * nntpgrab_core_config_get_server_info:

 * @obj:                An instance of the NntpgrabCore

 * @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_core_config_get_server_info(NntpgrabCore *obj, const char *servername, NGConfigServer *server);

/** 

 * nntpgrab_core_config_add_server:

 * @obj:                             An instance of the NntpgrabCore

 * @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_core_config_add_server(NntpgrabCore *obj, NGConfigServer new_server, char **errmsg);

/** 

 * nntpgrab_core_config_del_server:

 * @obj:                            An instance of the NntpgrabCore

 * @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_core_config_del_server(NntpgrabCore *obj, const char *servername, char **errmsg);

/** 

 * nntpgrab_core_config_edit_server:

 * @obj:                             An instance of the NntpgrabCore

 * @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_core_config_edit_server(NntpgrabCore *obj, const char *servername, NGConfigServer server, char **errmsg);

/** 

 * nntpgrab_core_config_get_opts:

 * @obj:           An instance of the NntpgrabCore

 *

 * Retrieve the general configuration options

 *

 * Returns:        A structure containing the general configuration options

 */

NGConfigOpts    nntpgrab_core_config_get_opts(NntpgrabCore *obj);

/** 

 * nntpgrab_core_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_core_config_set_opts(NntpgrabCore *obj, NGConfigOpts opts);

/** 

 * nntpgrab_core_schedular_start:

 * @obj:    An instance of the NntpgrabCore

 *

 * 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_core_schedular_start(NntpgrabCore *obj);

/** 

 * nntpgrab_core_schedular_stop:

 * @obj:     An instance of the NntpgrabCore

 * @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_core_schedular_stop(NntpgrabCore *obj, ngboolean wait);

/** 

 * nntpgrab_core_schedular_get_state:

 * @obj:     An instance of the NntpgrabCore

 *

 * Retrieve the current state of the schedular

 *

 * Returns:  The current state of the schedular

 */

NGSchedularState nntpgrab_core_schedular_get_state(NntpgrabCore *obj);

/** 

 * nntpgrab_core_schedular_add_task_to_queue:

 * @obj:                                          An instance of the NntpgrabCore

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

 * @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_core_schedular_add_task_to_queue(NntpgrabCore *obj, const char *collection_name, const char *subject, const char *poster, time_t stamp, nguint64 file_size, NGList *groups, NGList *parts, char **errmsg);

/** 

 * nntpgrab_core_schedular_del_task_from_queue:

 * @obj:                                   An instance of the NntpgrabCore

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

 * @subject:          (allow-none):        The subject of the task

 * @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_core_schedular_del_task_from_queue(NntpgrabCore *obj, const char *collection_name, const char *subject, char **errmsg);

/** 

 * nntpgrab_core_schedular_restart_task:

 * @obj:                                   An instance of the NntpgrabCore

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

 * @subject:          (allow-none):        The subject of the task

 * @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_core_schedular_restart_task(NntpgrabCore *obj, const char *collection_name, const char *subject, char **errmsg);

/** 

 * nntpgrab_core_schedular_save_queue:

 * @obj:                          An instance of the NntpgrabCore

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

 * Note that 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_core_schedular_save_queue(NntpgrabCore *obj, char **errmsg);

/** 

 * nntpgrab_core_schedular_foreach_task:

 * @obj:                              An instance of the NntpgrabCore

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

 * @user_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_core_schedular_foreach_task(NntpgrabCore *obj, ForeachCollectionFunc collection_func, ForeachFileFunc file_func, ForeachGroupFunc group_func, void *user_data);

/** 

 * nntpgrab_core_schedular_move_task:

 * @obj:                                  An instance of the NntpgrabCore

 * @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_core_schedular_move_task(NntpgrabCore *obj, const char *collection_name_src, const char *subject_src, const char *collection_name_dest, int position_dest);

/** 

 * nntpgrab_core_schedular_move_collection:

 * @obj:              An instance of the NntpgrabCore

 * @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_core_schedular_move_collection(NntpgrabCore *obj, const char *collection_name, int new_position);

/** 

 * nntpgrab_core_schedular_mark_task_optional:

 * @obj:              An instance of the NntpgrabCore

 * @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_core_schedular_mark_task_optional(NntpgrabCore *obj, const char *collection_name, const char *subject, ngboolean is_optional);

/** 

 * nntpgrab_core_plugins_get_avail_plugins:

 * @obj:    An instance of the NntpgrabCore

 *

 * Retrieve a list of all the available plugins

 *

 * Returns: (transfer full) (element-type utf8):  A list containing all the available plugins (const char* items). Needs to be free'd using nntpgrab_core_plugins_free_avail_plugins()

 */

NGList         *nntpgrab_core_plugins_get_avail_plugins(NntpgrabCore *obj);

/** 

 * nntpgrab_core_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_core_plugins_get_avail_plugins()

 */

void            nntpgrab_core_plugins_free_avail_plugins(NntpgrabCore *obj, NGList *plugins);

/** 

 * nntpgrab_core_plugins_get_plugin_info:

 * @obj:                 An instance of the NntpgrabCore

 * @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_core_plugins_get_plugin_info(NntpgrabCore *obj, const char *plugin_name, NNTPGrabPluginInfo *plugin_info);

/** 

 * nntpgrab_core_plugins_load_plugin:

 * @obj:                               An instance of the NntpgrabCore

 * @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_core_plugins_load_plugin(NntpgrabCore *obj, const char *plugin_name, char **errmsg);

/** 

 * nntpgrab_core_plugins_unload_plugin:

 * @obj:                               An instance of the NntpgrabCore

 * @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_core_plugins_unload_plugin(NntpgrabCore *obj, const char *plugin_name, char **errmsg);

/** 

 * nntpgrab_core_plugins_set_persistent:

 * @obj:          An instance of the NntpgrabCore

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

 * Note that this API function is unused in NNTPGrab 0.6

 *

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

 */

ngboolean       nntpgrab_core_plugins_set_persistent(NntpgrabCore *obj, const char *plugin_name, ngboolean persistent);

/** 

 * nntpgrab_core_embedded_server_start:

 * @obj:                          An instance of the NntpgrabCore

 * @port:                         The port on which the embedded webserver needs to listen

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

 *

 * Start the embedded server on the specified port (even if it's disabled in the configuration)

 * Note that this API function is implemented temporary for NNTPGrab 0.6. For future versions it needs to be moved to a more generic API function

 *

 * Returns:                       TRUE on success, FALSE if an error occured (errmsg will be set)

 */

ngboolean       nntpgrab_core_embedded_server_start(NntpgrabCore *obj, int port, char **errmsg);

/** 

 * nntpgrab_core_set_emit_log_messages:

 * @obj:           An instance of the NntpgrabCore

 * @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_core_set_emit_log_messages(NntpgrabCore *obj, ngboolean val);

#ifdef  __cplusplus

}

#endif

#endif /* _NNTPGRAB_H_ */