wget2  2.0.0
Plugin API for wget2

Data Structures

struct  wget_plugin_st
 
struct  wget_intercept_action
 
struct  wget_downloaded_file
 
struct  wget_plugin_vtable
 

Macros

#define WGET_EXPORT
 

Typedefs

typedef int wget_plugin_initializer_fn(wget_plugin *plugin)
 
typedef void wget_plugin_finalizer_fn(wget_plugin *plugin, int exit_status)
 
typedef int wget_plugin_option_callback(wget_plugin *plugin, const char *option, const char *value)
 
typedef void wget_plugin_url_filter_callback(wget_plugin *plugin, const wget_iri *iri, wget_intercept_action *action)
 
typedef int wget_plugin_post_processor(wget_plugin *plugin, wget_downloaded_file *file)
 

Functions

const char * wget_plugin_get_name (wget_plugin *plugin)
 
void wget_plugin_register_finalizer (wget_plugin *plugin, wget_plugin_finalizer_fn *fn)
 
void wget_plugin_register_option_callback (wget_plugin *plugin, wget_plugin_option_callback *fn)
 
void wget_intercept_action_reject (wget_intercept_action *action)
 
void wget_intercept_action_accept (wget_intercept_action *action)
 
void wget_intercept_action_set_alt_url (wget_intercept_action *action, const wget_iri *iri)
 
void wget_intercept_action_set_local_filename (wget_intercept_action *action, const char *local_filename)
 
void wget_plugin_register_url_filter_callback (wget_plugin *plugin, wget_plugin_url_filter_callback *filter_fn)
 
const wget_iriwget_downloaded_file_get_source_url (wget_downloaded_file *file)
 
const char * wget_downloaded_file_get_local_filename (wget_downloaded_file *file)
 
uint64_t wget_downloaded_file_get_size (wget_downloaded_file *file)
 
int wget_downloaded_file_get_contents (wget_downloaded_file *file, const void **data, size_t *size)
 
FILE * wget_downloaded_file_open_stream (wget_downloaded_file *file)
 
bool wget_downloaded_file_get_recurse (wget_downloaded_file *file)
 
void wget_downloaded_file_add_recurse_url (wget_downloaded_file *file, const wget_iri *iri)
 
void wget_plugin_register_post_processor (wget_plugin *plugin, wget_plugin_post_processor *fn)
 

Detailed Description

This is the plugin API for wget2.

Each plugin must define a wget_plugin_initializer() function which will be called when the plugin is loaded. See wget_plugin_initializer_t for the prototype. wget_plugin_initializer() must also be declared to be exported using WGET_EXPORT.

Macro Definition Documentation

◆ WGET_EXPORT

#define WGET_EXPORT

Mark a function to be exported. A common use for this is to mark the wget_plugin_initializer() function for plugin initialization.

WGET_EXPORT void wget_plugin_initializer(wget_plugin *plugin);

Typedef Documentation

◆ wget_plugin_initializer_fn

typedef int wget_plugin_initializer_fn(wget_plugin *plugin)

Prototype for the initializer function.

Parameters
[in]pluginThe plugin handle
Returns
Should return 0 if initialization succeeded, or any other value to indicate failure. On failure, wget2 will continue without the plugin and will not call the finalizer function even if registered.

◆ wget_plugin_finalizer_fn

typedef void wget_plugin_finalizer_fn(wget_plugin *plugin, int exit_status)

Prototype of the finalizer function.

Parameters
[in]pluginThe plugin handle
[in]exit_statusThe exit status wget will exit with

◆ wget_plugin_option_callback

typedef int wget_plugin_option_callback(wget_plugin *plugin, const char *option, const char *value)

Prototype for the function that will accept forwarded command line arguments.

Parameters
[in]pluginThe plugin handle
[in]optionOption name. If the option is "help", a help message must be printed to stdout.
[in]valueThe value of the option if provided, or NULL
Returns
Must return 0 if option and its value is valid, or any other value if invalid. In that case wget will exit.

◆ wget_plugin_url_filter_callback

typedef void wget_plugin_url_filter_callback(wget_plugin *plugin, const wget_iri *iri, wget_intercept_action *action)

Prototype for the function for intercepting URLs The function must be thread-safe.

Parameters
[in]pluginThe plugin handle
[in]iriThe URL about to be fetched
[in]actionOutput the action to be taken

◆ wget_plugin_post_processor

typedef int wget_plugin_post_processor(wget_plugin *plugin, wget_downloaded_file *file)

Prototype of the function for intercepting downloaded files. The function must be thread-safe.

Parameters
[in]pluginThe plugin handle
[in]fileDownloaded file handle
Returns
0 if further postprocessing of downloaded files should be stopped.

Function Documentation

◆ wget_plugin_get_name()

const char* wget_plugin_get_name ( wget_plugin plugin)

Gets the name the plugin is known as.

Parameters
[in]pluginThe plugin handle
Returns
the name of this plugin. The returned string is owned by wget and should not be freed or altered.

◆ wget_plugin_register_finalizer()

void wget_plugin_register_finalizer ( wget_plugin plugin,
wget_plugin_finalizer_fn fn 
)

Registers a function to be called when wget exits.

Parameters
[in]pluginThe plugin handle
[in]fnA function pointer to be called

◆ wget_plugin_register_option_callback()

void wget_plugin_register_option_callback ( wget_plugin plugin,
wget_plugin_option_callback fn 
)

Registers a function for command line option forwarding.

A option can be forwarded using an option following the pattern:

--plugin-opt=<plugin-name>.<option>[=<value>]
Parameters
[in]pluginThe plugin handle
[in]fnThe function pointer to register

◆ wget_intercept_action_reject()

void wget_intercept_action_reject ( wget_intercept_action action)

Marks the intercepted URL to be rejected. The URL will not be fetched by wget2 or passed to remaining plugins.

Mutually exclusive with wget_intercept_action_accept().

Parameters
actionHandle for any action taken by the plugin

◆ wget_intercept_action_accept()

void wget_intercept_action_accept ( wget_intercept_action action)

Marks the intercepted URL to be accepted. The URL will not be passed to remaining plugins. wget2 will not filter the URL by any accept or reject pattern.

Mutually exclusive with wget_intercept_action_reject().

Parameters
actionHandle for any action taken by the plugin

◆ wget_intercept_action_set_alt_url()

void wget_intercept_action_set_alt_url ( wget_intercept_action action,
const wget_iri iri 
)

Specifies an alternative URL to be fetched instead of the intercepted URL.

Parameters
actionHandle for any action taken by the plugin
iriAlternative URL to be fetched

◆ wget_intercept_action_set_local_filename()

void wget_intercept_action_set_local_filename ( wget_intercept_action action,
const char *  local_filename 
)

Specifies that the fetched data from intercepted URL should be written to an alternative file.

Parameters
actionHandle for any action taken by the plugin
local_filenameAlternative file name to use

◆ wget_plugin_register_url_filter_callback()

void wget_plugin_register_url_filter_callback ( wget_plugin plugin,
wget_plugin_url_filter_callback filter_fn 
)

Registers a plugin function for intercepting URLs

The registered function will be passed an abstract object of type wget_intercept_action_t which can be used to influence how wget will process the URL.

See also
wget_intercept_action_reject
wget_intercept_action_accept
wget_intercept_action_set_alt_url
wget_intercept_action_set_local_filename
Parameters
[in]pluginThe plugin handle
[in]filter_fnThe plugin function that will be passed the URL to be fetched

◆ wget_downloaded_file_get_source_url()

const wget_iri* wget_downloaded_file_get_source_url ( wget_downloaded_file file)

Gets the source address the file was downloaded from.

Parameters
[in]fileDownloaded file handle
Returns
The address the file was downloaded from. The returned object is owned by wget and should not be free'd.

◆ wget_downloaded_file_get_local_filename()

const char* wget_downloaded_file_get_local_filename ( wget_downloaded_file file)

Gets the file name the downloaded file was written to.

Parameters
[in]fileDownloaded file handle
Returns
The file name the file was written to. The returned string is owned by wget and should not be free'd.

◆ wget_downloaded_file_get_size()

uint64_t wget_downloaded_file_get_size ( wget_downloaded_file file)

Gets the size of the downloaded file.

Parameters
[in]fileDownloaded file handle
Returns
The size of the downloaded file

◆ wget_downloaded_file_get_contents()

int wget_downloaded_file_get_contents ( wget_downloaded_file file,
const void **  data,
size_t *  size 
)

Reads the downloaded file into memory.

Be careful, reading large files into memory can cause all sorts of problems like running out of memory. Use wget_downloaded_file_open_stream() whenever possible.

Parameters
[in]fileDownloaded file handle
[out]dataThe contents of the downloaded file. The memory is owned by wget and must not be free'd or modified.
[out]sizeSize of the downloaded file.

◆ wget_downloaded_file_open_stream()

FILE* wget_downloaded_file_open_stream ( wget_downloaded_file file)

Opens the downloaded file as a new stream.

Parameters
[in]fileDownloaded file handle
Returns
A newly opened stream for reading. The returned stream must be closed with fclose() after use.

◆ wget_downloaded_file_get_recurse()

bool wget_downloaded_file_get_recurse ( wget_downloaded_file file)

Gets whether the downloaded file should be scanned for more URLs.

Parameters
[in]fileDownloaded file handle
Returns
whether the file should be scanned for more URLs.

◆ wget_downloaded_file_add_recurse_url()

void wget_downloaded_file_add_recurse_url ( wget_downloaded_file file,
const wget_iri iri 
)

Adds a URL for recursive downloading. This function has no effect if wget_downloaded_file_get_recurse() returns false.

Parameters
[in]fileDownloaded file handle
[in]iriThe URL to be fetched.

◆ wget_plugin_register_post_processor()

void wget_plugin_register_post_processor ( wget_plugin plugin,
wget_plugin_post_processor fn 
)

Registers a plugin function for intercepting downloaded files.

The registered function will be passed an abstract object of type wget_downloaded_file_t which can be used to fetch the contents of the downloaded files and adding parsed URLs for recursive downloading.

See also
wget_downloaded_file_get_source_url
wget_downloaded_file_get_local_filename
wget_downloaded_file_get_size
wget_downloaded_file_get_contents
wget_downloaded_file_open_stream
wget_downloaded_file_get_recurse
wget_downloaded_file_add_recurse_url
Parameters
[in]pluginThe plugin handle
[in]fnThe plugin function that will be passed a handle to downloaded files.