NNTPGrab

/* 

    Copyright (C) 2005-2011  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_UTILS_H_

#define _NNTPGRAB_UTILS_H_

#include "nntpgrab_types.h"

#include "nntpgrab_glib_wrapper.h"

#ifdef  __cplusplus

extern "C" {

#endif

/** 

 * NNTPGrabNZB:

 * @files:  (element-type NZBFile):     A list containing NZBFile's

 */

typedef struct _nzb {

    NGList *files;

} NNTPGrabNZB;

/** 

 * NZBFile:

 * @subject:                                    The subject of the file

 * @poster:                                     The poster of the file

 * @stamp:                                      The stamp when (the first part of) this file was posted

 * @filesize:                                   The size of the file in bytes

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

 * @segments:   (element-type NNTPGrabPart):    A list containing information of all the parts which belong to this file

 */

typedef struct _nzb_file {

    char subject[256];

    char poster[256];

    time_t stamp;

    nguint64 filesize;

    NGList *groups;

    NGList *segments;

} NNTPGrabNZBFile;

/** 

 * NZBCreatorGroup:

 * @newsgroup:              The name of the newsgroup

 * @group_id:               An identifier for this group

 */

typedef struct _nzbcreator_group {

    char newsgroup[512];

    int group_id;

} NZBCreatorGroup;

typedef enum _nzbcreator_search_only_in {

    NZBCREATOR_SEARCH_ONLY_IN_SUBJECTS,

    NZBCREATOR_SEARCH_ONLY_IN_FILENAMES,

    NZBCREATOR_SEARCH_ONLY_IN_POSTERS

} NZBCreatorSearchOnlyIn;

/** 

 * NZBCreatorMaintenanceInfo:

 * @down_for_maintenance:   If TRUE, then the NZBCreator service is currently down because of maintenance

 * @reason:                 The reason for the maintenance

 */

typedef struct _nzbcreator_maintenance_info {

    ngboolean down_for_maintenance;

    char reason[1024];

} NZBCreatorMaintenanceInfo;

/** 

 * NZBCreatorSearchOpts:

 * @query:                  The search query

 * @username:               The username which will be used to perform the search query (unused in NNTPGrab 0.7)

 * @password:               The password which will be used to perform the search query (unused in NNTPGrab 0.7)

 * @search_only_in:         Indicate what type of data needs to be searched

 * @max_age:                The maximum age of search results (in days)

 * @minimal_file_size:      The minimum size of files in bytes

 * @maximal_file_size:      The maximum size of files in bytes

 * @percentage_complete:    Only return results which are this percentage complete (0 to 100)

 * @group_to_search:        Limit searching to one specific groups (see the @group_id field from #NZBCreatorGroup)

 * @file_type:              Only search files of this type

 * @offset:                 The search result offset

 */

typedef struct _nzbcreator_search_opts {

    char query[64];

    char username[64];

    char password[64];

    NZBCreatorSearchOnlyIn search_only_in;

    int max_age;

    ngint64 minimal_file_size;

    ngint64 maximal_file_size;

    int percentage_complete;

    int group_to_search;

    NNTPFileType file_type;

    int offset;

} NZBCreatorSearchOpts;

/** 

 * NZBCreatorFile:

 * @file_id:                An identifier for this file

 * @subject:                The subject of this file

 * @poster:                 The poster of this file

 * @num_parts_found:        The number of parts which are found which belong to this file

 * @num_parts_expected:     The number of parts which are expected which belong to this file

 * @file_type:              The type of this file

 * @file_size:              The size of this file in bytes

 * @stamp:                  The stamp of the first part of this file

 * @complete_percentage:    The percentage which indicates how complete this file is

 */

typedef struct _nzbcreator_file {

    ngint64 file_id;

    char subject[256];

    char poster[256];

    int num_parts_found;

    int num_parts_expected;

    NNTPFileType file_type;

    ngint64 file_size;

    time_t stamp;

    int complete_percentage;

} NZBCreatorFile;

/** 

 * NZBCreatorCollection:

 * @collection_name:                                        The name of the collection (most frequently this is the subject of the first file in the collection)

 * @short_collection_name:                                  An abbreviated version of @collection_name

 * @newsgroup:                                              The newsgroup in which all the files from this collection are poster

 * @total_size:                                             The total size in bytes of this collection

 * @stamp:                                                  The stamp of the first part of the first file in this collection

 */

typedef struct _nzbcreator_collection {

    ngint64 collection_id;

    char collection_name[256];

    char short_collection_name[256];

    char poster[256];

    char newsgroup[256];

    ngint64 total_size;

    time_t stamp;

    int num_parts_found;

    int num_parts_expected;

    int complete_percentage;

    int num_regular_files;

    int num_par2_files;

    ngint64 first_file_id;

} NZBCreatorCollection;

/** 

 * NZBCreatorSearchResult:

 * @number_of_hits:                                             The number of hits which were found for the given query

 * @number_of_results:                                          The number of files which were found and are part of the @collections

 * @results_per_page:                                           The number of search results per page

 * @offset:                                                     The search result offset

 * @collections:        (element-type NZBCreatorCollection):    A list containing all returned collections

 */

typedef struct _nzbcreator_search_result {

    int number_of_hits;

    int number_of_results;

    int results_per_page;

    int offset;

    NGList *collections;             // List of NZBCreatorCollection* instances

} NZBCreatorSearchResult;

/** 

 * NZBCreatorBrowseResult:

 * @number_of_results:                                          The number of collections which were returned in this result set

 * @oldest_stamp:                                               The stamp of the oldest collection in the result set

 * @newest_stamp:                                               The stamp of the newest collection in the result set

 * @collections:        (element-type NZBCreatorCollection):    A list containing all returned collections

 */

typedef struct _nzbcreator_browse_result {

    int number_of_results;

    time_t oldest_time_stamp;

    time_t newest_time_stamp;

    NGList *collections;             // List of NZBCreatorCollection* instances

} NZBCreatorBrowseResult;

#define NG_OPEN_NZB_CALLBACK(f)                   ((NGOpenNZBCallback) (f))

typedef void  (*NGOpenNZBCallback)                (const char *nzb_file, void *user_data);

#define NG_BRING_TO_FRONT_CALLBACK(f)             ((NGBringToFrontCallback) (f))

typedef void  (*NGBringToFrontCallback)           (void *user_data);

/** 

 * nntpgrab_utils_perform_base_initialization: (skip)

 *

 * Perform the initialization of the GLib system. Needs to be called before any other NNTPGrab function in non-GLib-based frontends

 */

void nntpgrab_utils_perform_base_initialization(void);

/** 

 * nntpgrab_utils_regex_compile:

 * @regex:     The (perl-compatible) regular expression which needs to be compiled

 *

 * Compile a regular expression

 *

 * Returns:    A compiled regular expression

 */

NGRegex     *nntpgrab_utils_regex_compile(const char *regex);

/** 

 * nntpgrab_utils_regex_free:

 * @re:        The compiled regular expression

 *

 * Free a compiled regular expression

 */

void         nntpgrab_utils_regex_free(NGRegex *re);

/** 

 * nntpgrab_utils_regex_match:

 * @re:        The compiled regular expression

 * @line:      The data which need to be matched against the compiled regular expression

 *

 * Perform a match against a compiled regular expression

 *

 * Returns:    A NULL-terminated array of matches items (needs to be free'd using nntpgrab_utils_regex_matches_free())

 */

const char **nntpgrab_utils_regex_match(NGRegex *re, const char *line);

/** 

 * nntpgrab_utils_regex_matches_free:

 * @param matches   The NULL-terminated array of matches as returned by the function nntpgrab_utils_regex_match()

 *

 * Free an array of matched items

 */

void         nntpgrab_utils_regex_matches_free(const char **matches);

/** 

 * nntpgrab_utils_strip_subject:

 * @subject                                       The subject which need to be stripped

 * @subject_without_partnum  (allow-none) (out):  Location for the subject without any part numbers

 * @file_num                 (allow-none) (out):  Location for the number of the file in the set

 * @total_files              (allow-none) (out):  Location for the total number of files in the set

 * @filename                 (allow-none) (out):  Location for the filename

 * @extension                (allow-none) (out):  Location for the extension of the filename (as an string)

 * @file_type                (allow-none) (out):  Location for the extension of the filename (as an enumeration)

 * @par2_startnum            (allow-none) (out):  Location for the start number of the PAR2 recovery file

 * @num_par2_blocks          (allow-none) (out):  Location for the number blocks in the PAR2 recovery file

 * @part_num                 (allow-none) (out):  Location for the part number for this subject

 * @total_parts              (allow-none) (out):  Location for the number of parts for this subject

 *

 * Strip a subject into useable pieces of data

 * All the parameters (except subject) can be NULL to ignore them

 * All the char* parameters need to be free'd using ng_free()

 *

 * Returns:         TRUE is the strip was successfull

 */

ngboolean        nntpgrab_utils_strip_subject(const char *subject, char **subject_without_partnum, int *file_num, int *total_files, char **filename, char **extension, NNTPFileType *file_type, int *par2_startnum, int *num_par2_blocks, int *part_num, int *total_parts);

/** 

 * nntpgrab_utils_get_file_type_of_filename:

 * @filename:       The filename whose file type needs to be found out

 *

 * Find out the file type of a given filename

 * If the file type couldn't be found out, the value NNTP_FILE_TYPE_UNKNOWN will be returned

 *

 * Returns:         The file type (as an enumeration)

 */

NNTPFileType     nntpgrab_utils_get_file_type_of_filename(const char *filename);

/** 

 * nntpgrab_utils_calculate_file_size:

 * @file_size:                  The file size which needs to be transformed

 * @file_size_str:     (out):   Pointer to the location where the result needs to be saved

 * @file_size_str_len:          The maximum length of the file_size_str buffer

 *

 * Transform a file size into a human readable notation

 */

void nntpgrab_utils_calculate_file_size(nguint64 file_size, char *file_size_str, int file_size_str_len);

/** 

 * nntpgrab_utils_calculate_estimated_time_remaining:

 * @bytes_received1:      The number of bytes received in now() - 10

 * @bytes_received2:      The number of bytes received in now() - 9

 * @bytes_received3:      The number of bytes received in now() - 8

 * @bytes_received4:      The number of bytes received in now() - 7

 * @bytes_received5:      The number of bytes received in now() - 6

 * @bytes_received6:      The number of bytes received in now() - 5

 * @bytes_received7:      The number of bytes received in now() - 4

 * @bytes_received8:      The number of bytes received in now() - 3

 * @bytes_received9:      The number of bytes received in now() - 2

 * @bytes_received10:     The number of bytes received in now() - 1

 * @file_size:            The file size in bytes

 *

 * Calculate the estimated time remaining to complete the given file size

 * The bytes_received parameters can be retrieved from the signalhandler for the signal #NNTPGrabCore::traffic-monitor-update

 *

 * Returns:               The number of seconds in which the given @file_size can be downloaded

 */

int              nntpgrab_utils_calculate_estimated_time_remaining(int bytes_received1, int bytes_received2, int bytes_received3, int bytes_received4, int bytes_received5, int bytes_received6, int bytes_received7, int bytes_received8, int bytes_received9, int bytes_received10, nguint64 file_size);

/** 

 * nntpgrab_utils_get_readable_time_remaining:

 * @estimated_time_remaining:         The estimated time remaining (in seconds)

 * @time_remaining_str:       (out):  Pointer to the location where the human readable notation (like '3 minutes and 10 seconds') can be saved

 * @time_remaining_str_len:           The maximum length of the time_remaining_str buffer

 *

 * Transform a estimated time remaining into a human readable value for the time remaining

 */

void             nntpgrab_utils_get_readable_time_remaining(int estimated_time_remaining, char *time_remaining_str, int time_remaining_str_len);

/** 

 * nntpgrab_utils_get_readable_finished_time:

 * @estimated_time_remaining:          The estimated time remaining (in seconds)

 * @time_remaining_str:        (out):  Pointer to the location where the human readable notation (like 'Friday February 6 2009 - 22:15') can be saved

 * @time_remaining_str_len:            The maximum length of the time_remaining_str buffer

 *

 * Transform a estimated time remaining into a human readable value for the expected time to finish

 */

void             nntpgrab_utils_get_readable_finished_time(int estimated_time_remaining, char *time_remaining_str, int time_remaining_str_len);

/** 

 * nntpgrab_utils_get_readable_time_stamp:

 * @stamp:                             The time stamp which needs to be transformed to a readable notation

 * @stamp_str:                 (out):  Pointer to the location where the human readable notation (like 'Friday February 6 2009 - 22:15') can be saved

 * @stamp_str_len:                     The maximum length of the time_remaining_str buffer

 *

 * Transform a time stamp into a human readable value

 */

void             nntpgrab_utils_get_readable_time_stamp(time_t stamp, char *stamp_str, int stamp_str_len);

/** 

 * nntpgrab_utils_sanitize_text:

 * @text:      (inout):  The text which need to be sanitized

 * @length:              The length of the text

 *

 * Check whether the given text contains invalid UTF-8 characters and if they're found, replace them with something more sane

 */

void             nntpgrab_utils_sanitize_text(char *text, int length);

/** 

 * nntpgrab_utils_strip_nzb_extension:

 * @filename:   (inout):  The filename whose extension need to be stripped

 *

 * Remove the extension from a filename

 */

void             nntpgrab_utils_strip_nzb_extension(char *filename);

/** 

 * nntpgrab_utils_sanitize_collection_name:

 * @collection_name:  (inout):  The collection name which need to be sanitized

 *

 * Remove forbidden characters from the collection name

 */

void             nntpgrab_utils_sanitize_collection_name(char *collection_name);

/** 

 * nntpgrab_utils_extract_par2set_name_from_par2_filename:

 * @par2filename:             The filename of the PAR2 file which needs to be extracted

 * @par2set:          (out):  Pointer to a location where the result can be saved

 * @par2set_length:           Size of the par2set length

 *

 * Extract the name of a PAR2 set out of a PAR2 filename

 *

 * Returns:                   TRUE of success (par2set will be set), FALSE on failure

 */

ngboolean

nntpgrab_utils_extract_par2set_name_from_par2_filename(const char *par2filename, char *par2set, int par2set_length);

/** 

 * nntpgrab_utils_get_folder_listing:

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

 * @folders:    (out) (element-type NNTPGrabFolder):     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_utils_get_folder_listing(const char *parent, NGList **folders);

/** 

 * nntpgrab_utils_free_folder_listing: (skip)

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

 *

 * Free a list of sub-folders

 */

void             nntpgrab_utils_free_folder_listing(NGList *folders);

/** 

 * nntpgrab_utils_parse_nzb_file:

 * @contents:                         The contents of the NZB file

 * @errmsg:      (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

 *

 * Parse the contents of a NZB file and put the information in a structure

 *

 * Returns:      A structure containing information about the NZB file. Needs to be free'd using the function nntpgrab_utils_nzb_file_free(). If the value NULL is returned, an error occured and errmsg will be set

 */

NNTPGrabNZB     *nntpgrab_utils_parse_nzb_file(const char *contents, char **errmsg);

/** 

 * nntpgrab_utils_nzb_file_free: (skip)

 * @nzbfile:       The structure containing information about the NZB file

 *

 * Free a structure containing details about a NZB file

 */

void             nntpgrab_utils_nzb_file_free(NNTPGrabNZB *nzbfile);

/** 

 * nntpgrab_utils_nzbcreator_check_api_version:

 * @api_okay:                          Location where the result can be saved

 * @errmsg:      (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

 *

 * Verify if this version of NNTPGrab can be used to communicate with the NZBCreator service

 *

 * Returns:      TRUE when the online search server returned a valid response (use @api_okay to find out if the API version matches)

 */

ngboolean        nntpgrab_utils_nzbcreator_check_api_version(ngboolean *api_okay, char **errmsg);

/** 

 * nntpgrab_utils_nzbcreator_free_maintenance_info: (skip)

 * @result:        The NZBCreator maintenance information

 *

 * Free the NZBCreator maintenance information

 */

void                     nntpgrab_utils_nzbcreator_free_maintenance_info(NZBCreatorMaintenanceInfo *info);

/** 

 * nntpgrab_utils_nzbcreator_get_maintenance_info:

 * @errmsg:      (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

 *

 * Retrieve information whether the NZBCreator service is currently under maintenance

 *

 * Returns:                             A structure containing maintenance information. Needs to be free'd using nntpgrab_utils_nzbcreator_free_maintenance_info(). If an error occurs, the value NULL will be returned and errmsg will be set

 */

NZBCreatorMaintenanceInfo   *nntpgrab_utils_nzbcreator_get_maintenance_info(char **errmsg);

/** 

 * nntpgrab_utils_nzbcreator_get_all_groups:

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

 *

 * Retrieve a list of all the usenet groups which are indexed by the NZBCreator service

 *

 * Returns:     (element-type NZBCreatorGroup):   A list of all the indexed usenet groups. Needs to be free'd using nntpgrab_utils_nzbcreator_free_groups(). If an error occures, the value NULL will be returned and errmsg will be set

 */

NGList                  *nntpgrab_utils_nzbcreator_get_all_groups(char **errmsg);

/** 

 * nntpgrab_utils_nzbcreator_free_groups: (skip)

 * @groups:        A list of all the indexed usenet groups

 *

 * Free the list of usenet groups which are indexed by the NZBCreator service

 */

void                     nntpgrab_utils_nzbcreator_free_groups(NGList *groups);

/** 

 * nntpgrab_utils_nzbcreator_perform_search:

 * @opts:                                               A structure containing information about the requested search

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

 *

 * Perform a search using the NZBCreator service

 *

 * Returns:                                             A structure containing the search results. Needs to be free'd using nntpgrab_utils_nzbcreator_free_result(). If an error occurs, the value NULL will be returned and errmsg will be set

 */

NZBCreatorSearchResult  *nntpgrab_utils_nzbcreator_perform_search(NZBCreatorSearchOpts opts, char **errmsg);

/** 

 * nntpgrab_utils_nzbcreator_free_result: (skip)

 * @result:        The NZBCreator search results

 *

 * Free the NZBCreator search results

 */

void                     nntpgrab_utils_nzbcreator_free_result(NZBCreatorSearchResult *result);

/** 

 * nntpgrab_utils_nzbcreator_retrieve_collection_details:

 * @collection_id:                                  The id of the collection whose details need to be retrieved

 * @stamp:                                          The stamp belonging to the collection id

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

 *

 * Retrieve a list of files belonging to a collection

 *

 * Returns:         (element-type NZBCreatorFile):  A list containing NZBCreatorFile's. Needs to be free'd using nntpgrab_utils_nzbcreator_free_collection_details(). If an error occurs, the value NULL will be returned and errmsg will be set

 */

NGList *nntpgrab_utils_nzbcreator_retrieve_collection_details(ngint64 collection_id, time_t stamp, char **errmsg);

/** 

 * nntpgrab_utils_nzbcreator_free_collection_details: (skip)

 * @files:          The list of files as returned by nntpgrab_utils_nzbcreator_retrieve_collection_details()

 *

 * Free the list with collection details

 */

void nntpgrab_utils_nzbcreator_free_collection_details(NGList *files);

/** 

 * nntpgrab_utils_nzbcreator_generate_NZB:

 * @file_ids:       (element-type int):  A list containing file ID's of all the files which needs to be retrieved

 * @oldest_stamp:                        The timestamp of the oldest file in the collection

 * @newest_stamp:                        The timestamp of the newest file in the collection

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

 *

 * Generate a NZB file based on a list of file ID's

 *

 * Returns:    The contents of the NZB file containing all the details of the given file_ids. Needs to be free'd using ng_free(). If an error occurs, the value NULL will be returned and errmsg will be set

 */

char                    *nntpgrab_utils_nzbcreator_generate_NZB(NGList *file_ids, time_t oldest_stamp, time_t newest_stamp, char **errmsg);

/** 

 * nntpgrab_utils_nzbcreator_perform_browse:

 * @newsgroup_id:                       The ID of the newsgroup which needs to be browsed

 * @older_than_stamp:                   Return only files older than this stamp (can be 0)

 * @newer_than_stamp:                   Return only files newer than this stamp (can be 0)

 * @username:                           The username to use to communicate with the server. Unused in NNTPGrab 0.8

 * @password:                           The password to use to communicate with the server. Unused in NNTPGrab 0.8

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

 *

 * Browse a newsgroup using the NZBCreator service

 *

 * Returns:                             A structure containing the search results. Needs to be free'd using nntpgrab_utils_nzbcreator_free_result(). If an error occurs, the value NULL will be returned and errmsg will be set

 */

NZBCreatorBrowseResult *nntpgrab_utils_nzbcreator_perform_browse(int newsgroup_id, time_t older_than_stamp, time_t newer_than_stamp, char *username, char *password, char **errmsg);

/** 

 * nntpgrab_utils_nzbcreator_free_browse_result: (skip)

 * @result:        The NZBCreator browse results

 *

 * Free the NZBCreator browse results

 */

void

nntpgrab_utils_nzbcreator_free_browse_result(NZBCreatorBrowseResult *result);

/** 

 * nntpgrab_utils_monitor_directory:

 * @path:                         The directory which needs to be monitored for changes

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

 *

 * Start the monitoring of a directory

 * The NGFileMonitor is an GObject where the event 'changed' can be caught using ng_signal_connect()

 *

 * Returns:                       An instance of a NGFileMonitor or NULL in case an error occured (errmsg will be set)

 */

NGFileMonitor   *nntpgrab_utils_monitor_directory(const char *path, char **errmsg);

/** 

 * nntpgrab_utils_cancel_directory_monitor:

 * @monitor:       The instance of the NGFileMonitor which needs to be stopped

 *

 * Cancel the monitoring of a directory

 */

void             nntpgrab_utils_cancel_directory_monitor(NGFileMonitor *monitor);

/** 

 * nntpgrab_utils_test_is_server_already_running:

 *

 * Find out if the NNTPGrab Server is already running on this computer

 *

 * Returns: TRUE when a running NNTPGrab Server has been detected on this computer

 */

ngboolean        nntpgrab_utils_test_is_server_already_running(void);

/** 

 * nntpgrab_utils_test_is_frontend_already_running:

 * @is_running:                     This flag will be set to TRUE when an already running frontend was detected

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

 *

 * Find out if a NNTPGrab frontend is already running on this computer

 *

 * Returns: TRUE when the check has completed successfully, check the is_running variable for the real status

 */

ngboolean       nntpgrab_utils_test_is_frontend_already_running(ngboolean *is_running, char **errmsg);

/** 

 * nntpgrab_utils_register_frontend:

 * @open_nzb_callback:              Function which needs to be called when a 'open NZB' request is received

 * @bring_to_front_callback:        Function which needs to be called when a 'bring to front' request is received

 * @user_data:                      Optional data to use with the callback function

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

 *

 * Allow this frontend to receive 'open NZB' and 'bring to front' requests using the given handlers

 *

 * Returns: TRUE when the registration succeeded succesfully

 */

ngboolean       nntpgrab_utils_register_frontend(NGOpenNZBCallback open_nzb_callback, NGBringToFrontCallback bring_to_front_callback, void *user_data, char **errmsg);

/** 

 * nntpgrab_utils_unregister_frontend:

 *

 * Indicate that this frontend doesn't want to receive 'open NZB' requests anymore

 */

void            nntpgrab_utils_unregister_frontend(void);

/** 

 * nntpgrab_utils_send_open_nzb_file_request:

 * @nzb_file:                       The location of the NZB file which needs to be opened

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

 *

 * Send a request to an already running NNTPGrab frontend to open an NZB file

 *

 * Returns: TRUE when the request was sent succesfully

 */

ngboolean       nntpgrab_utils_send_open_nzb_file_request(const char *nzb_file, char **errmsg);

/** 

 * nntpgrab_utils_send_bring_to_front_request:

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

 *

 * Send a request to an already running NNTPGrab frontend to present itself

 *

 * Returns: TRUE when the request was sent succesfully

 */

ngboolean       nntpgrab_utils_send_bring_to_front_request(char **errmsg);

/** 

 * nntpgrab_utils_perform_shutdown:

 *

 * Shut down the system

 *

 * Returns: TRUE when a shutdown command has been executed successfully

 */

ngboolean        nntpgrab_utils_perform_shutdown(void);

#ifdef  __cplusplus

}

#endif

#endif /* _NNTPGRAB_UTILS_H_ */