nntpgrab.h File Reference

#include "nntpgrab_types.h"

Go to the source code of this file.

Defines
#define	NNTPGRAB_API_VERSION   20090505
Typedefs
typedef struct NNTPGrabCore	NNTPGrabCore
typedef struct NNTPGrabCoreClass	NNTPGrabCoreClass
Functions
NNTPGrabCore *	nntpgrab_core_init (int version, char **err, char **warnings)
	Initialize the NNTPGrab Core library.
void	nntpgrab_core_cleanup (NNTPGrabCore *obj)
	Cleanup the NNTPGrab Core library.
NGList *	nntpgrab_core_config_get_avail_servers (NNTPGrabCore *obj)
	Retrieve a list of the available usenet servers.
void	nntpgrab_core_config_free_avail_servers (NNTPGrabCore *obj, NGList *servers)
	Free the list of available usenet servers.
ngboolean	nntpgrab_core_config_get_server_info (NNTPGrabCore *obj, const char *servername, ConfigServer *server)
	Get the configuration details about a specific usenet server.
ngboolean	nntpgrab_core_config_add_server (NNTPGrabCore *obj, ConfigServer new_server, char **errmsg)
	Add a new usenet server to the NNTPGrab configuration.
ngboolean	nntpgrab_core_config_del_server (NNTPGrabCore *obj, const char *servername, char **errmsg)
	Remove a usenet server from the NNTPGrab configuration.
ngboolean	nntpgrab_core_config_edit_server (NNTPGrabCore *obj, const char *servername, ConfigServer server, char **errmsg)
	Adjust the configuration details of an usenet server.
ConfigOpts	nntpgrab_core_config_get_opts (NNTPGrabCore *obj)
	Retrieve the general configuration options.
void	nntpgrab_core_config_set_opts (NNTPGrabCore *obj, ConfigOpts opts)
	Adjust the general configuration options.
ngboolean	nntpgrab_core_config_get_folder_listing (NNTPGrabCore *obj, const char *parent, NGList **folders)
	Retrieves a list containing all the sub-folders which are in the given folder.
void	nntpgrab_core_config_free_folder_listing (NNTPGrabCore *obj, NGList *folders)
	Free a list of sub-folders.
ngboolean	nntpgrab_core_schedular_start (NNTPGrabCore *obj)
	Start the NNTPGrab schedular.
ngboolean	nntpgrab_core_schedular_stop (NNTPGrabCore *obj, ngboolean wait)
	Stop the NNTPGrab schedular.
SchedularState	nntpgrab_core_schedular_get_state (NNTPGrabCore *obj)
	Retrieve the current state of the schedular.
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)
	Add a new task to the download queue.
ngboolean	nntpgrab_core_schedular_del_task_from_queue (NNTPGrabCore *obj, const char *collection_name, const char *subject, char **errmsg)
	Remove a task from the download queue.
ngboolean	nntpgrab_core_schedular_restart_task (NNTPGrabCore *obj, const char *collection_name, const char *subject, char **errmsg)
	Restart a task in the download queue.
ngboolean	nntpgrab_core_schedular_save_queue (NNTPGrabCore *obj, char **errmsg)
	Save any recent changes in the download queue to the disk.
void	nntpgrab_core_schedular_foreach_task (NNTPGrabCore *obj, ForeachCollectionFunc collection_func, ForeachFileFunc file_func, ForeachGroupFunc group_func, void *data)
	Retrieve a list of all the items in the download queue (using callback functions).
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)
	Move a task in the download queue.
ngboolean	nntpgrab_core_schedular_move_collection (NNTPGrabCore *obj, const char *collection_name, int new_position)
	Move the position of a collection in the download queue.

---

Define Documentation

#define NNTPGRAB_API_VERSION   20090505

---

Typedef Documentation

typedef struct NNTPGrabCore NNTPGrabCore

typedef struct NNTPGrabCoreClass NNTPGrabCoreClass

---

Function Documentation

void nntpgrab_core_cleanup

(

NNTPGrabCore *

obj

)

Cleanup the NNTPGrab Core library.

After this function is called, the NNTPGrabCore instance can't be used anymore

Parameters:

obj

An instance of the NNTPGrabCore

ngboolean nntpgrab_core_config_add_server	(	NNTPGrabCore *	obj,
		ConfigServer	new_server,
		char **	errmsg
	)

Add a new usenet server to the NNTPGrab configuration.

Parameters:

	obj	An instance of the NNTPGrabCore
	new_server	A structure containing the details about the new usenet server
	errmsg	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

Returns:

TRUE when the server was successfully added. 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
	)

Remove a usenet server from the NNTPGrab configuration.

Parameters:

	obj	An instance of the NNTPGrabCore
	servername	The name of the server whose entry should be removed
	errmsg	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

Returns:

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

ngboolean nntpgrab_core_config_edit_server	(	NNTPGrabCore *	obj,
		const char *	servername,
		ConfigServer	server,
		char **	errmsg
	)

Adjust the configuration details of an usenet server.

Parameters:

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

Returns:

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

void nntpgrab_core_config_free_avail_servers	(	NNTPGrabCore *	obj,
		NGList *	servers
	)

Free the list of available usenet servers.

Parameters:

	obj	An instance of the NNTPGrabCore
	servers	A list of the available usenet servers as returned from the function nntpgrab_config_get_avail_servers()

void nntpgrab_core_config_free_folder_listing	(	NNTPGrabCore *	obj,
		NGList *	folders
	)

Free a list of sub-folders.

Parameters:

	obj	An instance of the NNTPGrabCore
	folders	A list containing subfolders as returned by the function nntpgrab_config_get_folder_listing()

NGList* nntpgrab_core_config_get_avail_servers

(

NNTPGrabCore *

obj

)

Retrieve a list of the available usenet servers.

Parameters:

obj

An instance of the NNTPGrabCore

Returns:

A list of all the available usenet servers. Needs to be freed using nntpgrab_config_free_avail_servers()

ngboolean nntpgrab_core_config_get_folder_listing	(	NNTPGrabCore *	obj,
		const char *	parent,
		NGList **	folders
	)

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

Parameters:

	obj	An instance of the NNTPGrabCore
	parent	The name of the directory whose sub-folders should be retrieved
	folders	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()

Returns:

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

ConfigOpts nntpgrab_core_config_get_opts

(

NNTPGrabCore *

obj

)

Retrieve the general configuration options.

Parameters:

obj

An instance of the NNTPGrabCore

Returns:

A structure containing the general configuration options

ngboolean nntpgrab_core_config_get_server_info	(	NNTPGrabCore *	obj,
		const char *	servername,
		ConfigServer *	server
	)

Get the configuration details about a specific usenet server.

Parameters:

	obj	An instance of the NNTPGrabCore
	servername	The name of the server whose details should be retrieved
	server	The address of a ConfigServer structure which will be used to fill in the configuration details

Returns:

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

void nntpgrab_core_config_set_opts	(	NNTPGrabCore *	obj,
		ConfigOpts	opts
	)

Adjust the general configuration options.

Parameters:

	obj	An instance of the NNTPGrabCore
	opts	A structure containing the new general configuration options

NNTPGrabCore* nntpgrab_core_init	(	int	version,
		char **	err,
		char **	warnings
	)

Initialize the NNTPGrab Core library.

This function needs to be called before any other NNTPGrab function can be called

Parameters:

	version	Needs to be NNTPGRAB_API_VERSION, this is used to prevent version conflicts
	err	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	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

Returns:

An instance of the NNTPGrabCore which need to be used for other NNTPGrab functions. If this value is NULL, an error has occured (the reason is saved in the err variable)

Note:

Even if this function returns non-NULL, the warnings argument MAY 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
	)

Add a new task to the download queue.

Parameters:

	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	A list containing the newsgroups in which this file is posted
	parts	A list containing the message-id's of all the individual parts belonging to this file
	errmsg	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

Returns:

TRUE if the task was succesfully added, 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
	)

Remove a task from the download queue.

Parameters:

	obj	An instance of the NNTPGrabCore
	collection_name	The name of the collection in which the task resides
	subject	The subject of the file
	errmsg	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

Returns:

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

void nntpgrab_core_schedular_foreach_task	(	NNTPGrabCore *	obj,
		ForeachCollectionFunc	collection_func,
		ForeachFileFunc	file_func,
		ForeachGroupFunc	group_func,
		void *	data
	)

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

Parameters:

	obj	An instance of the NNTPGrabCore
	collection_func	The function which should be called for every collection in the download queue
	file_func	The function which should be called for every file in the download queue
	group_func	The function which should be called for every group in every file in the download queue
	data	Pointer to some data which will be made available in the callback functions

SchedularState nntpgrab_core_schedular_get_state

(

NNTPGrabCore *

obj

)

Retrieve the current state of the schedular.

Parameters:

obj

An instance of the NNTPGrabCore

Returns:

The current state of the schedular

ngboolean nntpgrab_core_schedular_move_collection	(	NNTPGrabCore *	obj,
		const char *	collection_name,
		int	new_position
	)

Move the position of a collection in the download queue.

Parameters:

	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

Returns:

TRUE on success, FALSE is the collection_name 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
	)

Move a task in the download queue.

Parameters:

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

Returns:

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

ngboolean nntpgrab_core_schedular_restart_task	(	NNTPGrabCore *	obj,
		const char *	collection_name,
		const char *	subject,
		char **	errmsg
	)

Restart a task in the download queue.

Parameters:

	obj	An instance of the NNTPGrabCore
	collection_name	The name of the collection in which the task resides
	subject	The subject of the file
	errmsg	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

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
	)

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

Parameters:

	obj	An instance of the NNTPGrabCore
	errmsg	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

Returns:

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

Note:

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)

ngboolean nntpgrab_core_schedular_start

(

NNTPGrabCore *

obj

)

Start the NNTPGrab schedular.

Parameters:

obj

An instance of the NNTPGrabCore

Returns:

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

ngboolean nntpgrab_core_schedular_stop	(	NNTPGrabCore *	obj,
		ngboolean	wait
	)

Stop the NNTPGrab schedular.

Parameters:

	obj	An instance of the NNTPGrabCore
	wait	Whether this function should wait until the schedular really has stopped

Returns:

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

---