libwget-plugin(3)

NAME
libwget-plugin - Plugin API for wget2

SYNOPSIS

  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_iri * wget_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

  #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

  typedef int wget_plugin_initializer_fn(wget_plugin *plugin)
Prototype for the initializer function.

Parameters
    plugin The 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.

  typedef void wget_plugin_finalizer_fn(wget_plugin *plugin, int exit_status)
Prototype of the finalizer function.

Parameters
    plugin The plugin handle
    exit_status The exit status wget will exit with

  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
    plugin The plugin handle
    option Option name. If the option is 'help', a help message must be printed to stdout.
    value The 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.

  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
    plugin The plugin handle
    iri The URL about to be fetched
    action Output the action to be taken

  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
    plugin The plugin handle
    file Downloaded file handle

Returns
    0 if further postprocessing of downloaded files should be stopped.

Function Documentation

  const char * wget_plugin_get_name (wget_plugin * plugin)
Gets the name the plugin is known as.

Parameters
    plugin The plugin handle

Returns
    the name of this plugin. The returned string is owned by wget and should not be freed or altered.

  void wget_plugin_register_finalizer (wget_plugin * plugin, wget_plugin_finalizer_fn * fn)
Registers a function to be called when wget exits.

Parameters
    plugin The plugin handle
    fn A function pointer to be called

  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
    plugin The plugin handle
    fn The function pointer to register

  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
    action Handle for any action taken by the plugin

  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
    action Handle for any action taken by the plugin

  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
    action Handle for any action taken by the plugin
    iri Alternative URL to be fetched

  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
    action Handle for any action taken by the plugin
    local_filename Alternative file name to use

  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
    plugin The plugin handle
    filter_fn The plugin function that will be passed the URL to be fetched

  const wget_iri * wget_downloaded_file_get_source_url (wget_downloaded_file * file)
Gets the source address the file was downloaded from.

Parameters
    file Downloaded file handle

Returns
    The address the file was downloaded from. The returned object is owned by wget and should not be free'd.

  const char * wget_downloaded_file_get_local_filename (wget_downloaded_file * file)
Gets the file name the downloaded file was written to.

Parameters
    file Downloaded file handle

Returns
    The file name the file was written to. The returned string is owned by wget and should not be free'd.

  uint64_t wget_downloaded_file_get_size (wget_downloaded_file * file)
Gets the size of the downloaded file.

Parameters
    file Downloaded file handle

Returns
    The size of the downloaded file

  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
    file Downloaded file handle
    data The contents of the downloaded file. The memory is owned by wget and must not be free'd or modified.
    size Size of the downloaded file.

  FILE * wget_downloaded_file_open_stream (wget_downloaded_file * file)
Opens the downloaded file as a new stream.

Parameters
    file Downloaded file handle

Returns
    A newly opened stream for reading. The returned stream must be closed with fclose() after use.

  bool wget_downloaded_file_get_recurse (wget_downloaded_file * file)
Gets whether the downloaded file should be scanned for more URLs.

Parameters
    file Downloaded file handle

Returns
    whether the file should be scanned for more URLs.

  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
    file Downloaded file handle
    iri The URL to be fetched.

  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
    plugin The plugin handle
    fn The plugin function that will be passed a handle to downloaded files.

Author

Generated automatically by Doxygen for wget2 from the source code.