nntpgrab_utils.h File Reference

#include "nntpgrab_types.h"

Go to the source code of this file.


Data Structures
struct   _nntpgrab_folder
struct   _nzb
struct   _nzb_file
struct   _nzbcreator_group
struct   _nzbcreator_search_opts
struct   _nzbcreator_file
struct   _nzbcreator_collection
struct   _nzbcreator_search_result

Defines
#define  ng_list_previous(list)   ((list) ? (((NGList *)(list))->prev) : NULL)
#define  ng_list_next(list)   ((list) ? (((NGList *)(list))->next) : NULL)

Typedefs
typedef void  NGFileMonitor
typedef struct _nntpgrab_folder  NNTPGrabFolder
typedef struct _nzb  NZB
typedef struct _nzb_file  NZBFile
typedef struct _nzbcreator_group  NZBCreatorGroup
typedef enum
_nzbcreator_search_only_in 		 NZBCreatorSearchOnlyIn
typedef struct
_nzbcreator_search_opts 		 NZBCreatorSearchOpts
typedef struct _nzbcreator_file  NZBCreatorFile
typedef struct
_nzbcreator_collection 		 NZBCreatorCollection
typedef struct
_nzbcreator_search_result 		 NZBCreatorSearchResult

Enumerations
enum   _nzbcreator_search_only_in { NZBCREATOR_SEARCH_ONLY_IN_SUBJECTS, NZBCREATOR_SEARCH_ONLY_IN_FILENAMES, NZBCREATOR_SEARCH_ONLY_IN_POSTERS }

Functions
void  ng_free (void *data)
  Free data allocated by NNTPGrab functions.
NGList *  ng_list_append (NGList *list, void *data)
  Append an item to a list.
NGList *  ng_list_prepend (NGList *list, void *data)
  Insert an item to the beginning of a list.
NGList *  ng_list_remove (NGList *list, void *data)
  Remove an item from a list.
unsigned int  ng_list_length (NGList *list)
  Retrieve the length of a list.
void  ng_list_free (NGList *list)
  Free a list.
void  ng_signal_connect (void *instance, const char *signal_name, NGCallback cb_handler, void *data)
  Register a signal handler.
void  ng_signal_handlers_disconnect_by_func (void *instance, NGCallback cb_handler, void *data)
  Un-register a signal handler.
void  ng_signal_handlers_block_by_func (void *instance, NGCallback cb_handler, void *data)
  Temporary disable a signal handler for a given callback function.
void  ng_signal_handlers_unblock_by_func (void *instance, NGCallback cb_handler, void *data)
  Re-enable a signal handler for a given callback function.
void  ng_event_handler_loop_run (void)
  Start the event handler loop.
void  ng_event_handler_loop_quit (void)
  Stop the event handler loop.
NGRegex *  nntpgrab_utils_regex_compile (const char *regex)
  Compile a regular expression.
void  nntpgrab_utils_regex_free (NGRegex *re)
  Free a compiled regular expression.
const char **  nntpgrab_utils_regex_match (NGRegex *re, const char *line)
  Perform a match against a compiled regular expression.
void  nntpgrab_utils_regex_matches_free (const char **matches)
  Free an array of matched items.
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)
  Strip a subject into useable pieces of data.
NNTPFileType  nntpgrab_utils_get_file_type_of_filename (const char *filename)
  Find out the file type of a given filename.
char *  nntpgrab_utils_calculate_file_size (nguint64 file_size)
  Transform a file size into a human readable notation.
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)
  Calculate the estimated time remaining to complete the given file size.
char *  nntpgrab_utils_get_readable_time_remaining (int estimated_time_remaining)
  Transform a estimated time remaining into a human readable value for the time remaining.
char *  nntpgrab_utils_get_readable_finished_time (int estimated_time_remaining)
  Transform a estimated time remaining into a human readable value for the expected time to finish.
void  nntpgrab_utils_sanitize_text (char *text, int length)
  Check whether the given text contains invalid UTF-8 characters and if they're found, replace them with something more sane.
void  nntpgrab_utils_strip_nzb_extension (char *filename)
  Remove the extension from a filename.
void  nntpgrab_utils_sanitize_collection_name (char *collection_name)
  Remove forbidden characters from the collection name.
ngboolean  nntpgrab_utils_get_folder_listing (const char *parent, NGList **folders)
  Retrieves a list containing all the sub-folders which are in the given folder.
void  nntpgrab_utils_free_folder_listing (NGList *folders)
  Free a list of sub-folders.
NZB *  nntpgrab_utils_parse_nzb_file (const char *contents, char **errmsg)
  Parse the contents of a NZB file and put the information in a structure.
void  nntpgrab_utils_nzb_file_free (NZB *nzbfile)
  Free a structure containing details about a NZB file.
NGList *  nntpgrab_utils_nzbcreator_get_all_groups (char **errmsg)
  Retrieve a list of all the usenet groups which are indexed by the NZBCreator service.
void  nntpgrab_utils_nzbcreator_free_groups (NGList *groups)
  Free the list of usenet groups which are indexed by the NZBCreator service.
NZBCreatorSearchResult *  nntpgrab_utils_nzbcreator_perform_search (NZBCreatorSearchOpts opts, char **errmsg)
  Perform a search using the NZBCreator service.
void  nntpgrab_utils_nzbcreator_free_result (NZBCreatorSearchResult *result)
  Free the NZBCreator search results.
char *  nntpgrab_utils_nzbcreator_generate_NZB (NGList *file_ids, char **errmsg)
  Generate a NZB file based on a list of file ID's.
NGFileMonitor *  nntpgrab_utils_monitor_directory (const char *path, char **errmsg)
  Start the monitoring of a directory.
void  nntpgrab_utils_cancel_directory_monitor (NGFileMonitor *monitor)
  Cancel the monitoring of a directory.

Define Documentation

#define ng_list_next ( list   )     ((list) ? (((NGList *)(list))->next) : NULL)

#define ng_list_previous ( list   )     ((list) ? (((NGList *)(list))->prev) : NULL)

Typedef Documentation

typedef void NGFileMonitor

typedef struct _nntpgrab_folder NNTPGrabFolder

typedef struct _nzb NZB

typedef struct _nzbcreator_collection NZBCreatorCollection

typedef struct _nzbcreator_file NZBCreatorFile

typedef struct _nzbcreator_group NZBCreatorGroup

typedef enum _nzbcreator_search_only_in NZBCreatorSearchOnlyIn

typedef struct _nzbcreator_search_opts NZBCreatorSearchOpts

typedef struct _nzbcreator_search_result NZBCreatorSearchResult

typedef struct _nzb_file NZBFile

Enumeration Type Documentation

enum _nzbcreator_search_only_in

Enumerator:
NZBCREATOR_SEARCH_ONLY_IN_SUBJECTS 
NZBCREATOR_SEARCH_ONLY_IN_FILENAMES 
NZBCREATOR_SEARCH_ONLY_IN_POSTERS 

Function Documentation

void ng_event_handler_loop_quit ( void   ) 

Stop the event handler loop.

Note:
This function doesn't need to be used for the GTK+ frontend as it is equivalent to gtk_main_quit()

void ng_event_handler_loop_run ( void   ) 

Start the event handler loop.

This function waits for incoming events and passes these on to all the registered event handlers

Note:
This function only returns as soon as the function ng_event_handler_loop_quit() is called from an event handler or another thread

This function doesn't need to be used for the GTK+ frontend as it is equivalent to gtk_main()

void ng_free ( void *  data  ) 

Free data allocated by NNTPGrab functions.

Parameters:
data  The data which needs to be free'd

NGList* ng_list_append ( NGList *  list,
void *  data  
)

Append an item to a list.

Parameters:
list  The list where the item needs to be added to (can be NULL to create a new list)
data  The item which needs to be added
Returns:
The (possibly) new start of the list

void ng_list_free ( NGList *  list  ) 

Free a list.

Parameters:
list  The list which needs to be free'd
Note:
This function only free's the list itself, NOT the items which were in it!

unsigned int ng_list_length ( NGList *  list  ) 

Retrieve the length of a list.

Parameters:
list  The list of which the length must be returned
Returns:
The length of the list

NGList* ng_list_prepend ( NGList *  list,
void *  data  
)

Insert an item to the beginning of a list.

Parameters:
list  The list where the item needs to be added to (can be NULL to create a new list)
data  The item which needs to be added
Returns:
The (possibly) new start of the list

NGList* ng_list_remove ( NGList *  list,
void *  data  
)

Remove an item from a list.

Parameters:
list  The list where the item needs to be removed from
data  The item which needs to be removed
Returns:
The (possibly) new start of the list
Note:
If data isn't part of the list, this function will do nothing

void ng_signal_connect ( void *  instance,
const char *  signal_name,
NGCallback  cb_handler,
void *  data  
)

Register a signal handler.

Parameters:
instance  The instance of an GObject, for example NNTPGrabCore or NNTPGrabAutoImport
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
Note:
The file nntpgrab_core/marshall.list contains a list of known signals and callback function prototypes for the NNTPGrabCore

void ng_signal_handlers_block_by_func ( void *  instance,
NGCallback  cb_handler,
void *  data  
)

Temporary disable a signal handler for a given callback function.

Parameters:
instance  The instance of an GObject, for example NNTPGrabCore or NNTPGrabAutoImport
cb_handler  The callback function which need to be temporary blocked
data  The callback data used for the given cb_handler

void ng_signal_handlers_disconnect_by_func ( void *  instance,
NGCallback  cb_handler,
void *  data  
)

Un-register a signal handler.

Parameters:
instance  The instance of an GObject, for example NNTPGrabCore or NNTPGrabAutoImport
cb_handler  The callback function which need to be unregistered
data  The callback data used for the given cb_handler

void ng_signal_handlers_unblock_by_func ( void *  instance,
NGCallback  cb_handler,
void *  data  
)

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

Parameters:
instance  The instance of an GObject, for example NNTPGrabCore or NNTPGrabAutoImport
cb_handler  The callback function which need to be un-blocked
data  The callback data used for the given cb_handler

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  
)

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

Parameters:
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
Returns:
The number of seconds in which the given file_size can be downloaded
Note:
The bytes_received parameters can be retrieved from the signalhandler for the signal 'traffic_monitor_update'

char* nntpgrab_utils_calculate_file_size ( nguint64  file_size  ) 

Transform a file size into a human readable notation.

Parameters:
file_size  The file size which needs to be transformed
Returns:
The human readable notation for the file size. Needs to be free'd using ng_free()

void nntpgrab_utils_cancel_directory_monitor ( NGFileMonitor *  monitor  ) 

Cancel the monitoring of a directory.

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

void nntpgrab_utils_free_folder_listing ( NGList *  folders  ) 

Free a list of sub-folders.

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

NNTPFileType nntpgrab_utils_get_file_type_of_filename ( const char *  filename  ) 

Find out the file type of a given filename.

Parameters:
filename  The filename whose file type needs to be found out
Returns:
The file type (as an enumeration)
Note:
If the file type couldn't be found out, the value NNTP_FILE_TYPE_UNKNOWN will be returned

ngboolean nntpgrab_utils_get_folder_listing ( const char *  parent,
NGList **  folders  
)

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

Parameters:
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
Retrieves a list containing all the sub-folders which are in the given folder.

Parameters:
parent  The path whose belonging folders should be looked up. If NULL, all the drive letters will be returned (on Win32) or "/" is returned (*nix/osx)
folders  Return address for a list containing g_slice_new'ed ConfigFolder structures containing the requested info
Returns:
FALSE when the given parent is invalid

char* nntpgrab_utils_get_readable_finished_time ( int  estimated_time_remaining  ) 

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

Parameters:
estimated_time_remaining  The estimated time remaining (in seconds)
Returns:
The human readable notation (like 'Friday Februari 6 2009 - 22:15'). Needs to be free'd using ng_free()

char* nntpgrab_utils_get_readable_time_remaining ( int  estimated_time_remaining  ) 

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

Parameters:
estimated_time_remaining  The estimated time remaining (in seconds)
Returns:
The human readable notation (like '3 minutes and 10 seconds'). Needs to be free'd using ng_free()

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

Start the monitoring of a directory.

Parameters:
path  The directory which needs to be monitored for changes
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:
An instance of a NGFileMonitor or NULL in case an error occured (errmsg will be set)
Note:
The NGFileMonitor is an GObject where the event 'changed' can be caught using ng_signal_connect()

void nntpgrab_utils_nzb_file_free ( NZB *  nzbfile  ) 

Free a structure containing details about a NZB file.

Parameters:
nzbfile  The structure containing information about the NZB file

void nntpgrab_utils_nzbcreator_free_groups ( NGList *  groups  ) 

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

Parameters:
groups  A list of all the indexed usenet groups

void nntpgrab_utils_nzbcreator_free_result ( NZBCreatorSearchResult *  result  ) 

Free the NZBCreator search results.

Parameters:
result  The NZBCreator search results

char* nntpgrab_utils_nzbcreator_generate_NZB ( NGList *  file_ids,
char **  errmsg  
)

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

Parameters:
file_ids  A list containing file ID's of all the files which needs to be retrieved
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:
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

NGList* nntpgrab_utils_nzbcreator_get_all_groups ( char **  errmsg  ) 

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

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

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

Perform a search using the NZBCreator service.

Parameters:
opts  A structure containing information about the requested search
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:
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

NZB* nntpgrab_utils_parse_nzb_file ( const char *  contents,
char **  errmsg  
)

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

Parameters:
contents  The contents of the NZB 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:
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

NGRegex* nntpgrab_utils_regex_compile ( const char *  regex  ) 

Compile a regular expression.

Parameters:
regex  The (perl-compatible) regular expression which needs to be compiled
Returns:
A compiled regular expression

void nntpgrab_utils_regex_free ( NGRegex *  re  ) 

Free a compiled regular expression.

Parameters:
re  The compiled regular expression

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

Perform a match against a compiled regular expression.

Parameters:
re  The compiled regular expression
line  The data which need to be matched against the compiled regular expression
Returns:
A NULL-terminated array of matches items (needs to be free'd using nntpgrab_utils_regex_matches_free())

void nntpgrab_utils_regex_matches_free ( const char **  matches  ) 

Free an array of matched items.

Parameters:
matches  The NULL-terminated array of matches as returned by the function nntpgrab_utils_regex_match()

void nntpgrab_utils_sanitize_collection_name ( char *  collection_name  ) 

Remove forbidden characters from the collection name.

Parameters:
collection_name  The collection name which need to be sanitized

void nntpgrab_utils_sanitize_text ( char *  text,
int  length  
)

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

Parameters:
text  The text which need to be sanitized
length  The length of the text

void nntpgrab_utils_strip_nzb_extension ( char *  filename  ) 

Remove the extension from a filename.

Parameters:
filename  The filename whose extension need to be stripped

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  
)

Strip a subject into useable pieces of data.

Parameters:
subject  The subject which need to be stripped
subject_without_partnum  Location for the subject without any part numbers
file_num  Location for the number of the file in the set
total_files  Location for the total number of files in the set
filename  Location for the filename
extension  Location for the extension of the filename (as an string)
file_type  Location for the extension of the filename (as an enumeration)
par2_startnum  Location for the start number of the PAR2 recovery file
num_par2_blocks  Location for the number blocks in the PAR2 recovery file
part_num  Location for the part number for this subject
total_parts  Location for the number of parts for this subject
Returns:
TRUE is the strip was successfull
Note:
All the parameters (except subject) can be NULL to ignore them

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

Generated on Wed May 20 22:37:09 2009 for NNTPGrab by  1.5.4