wget2: Plugin API for wget2

| wget2 2.0.0

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Macros | Typedefs | Functions
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_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

## ◆ 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] | 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.

## ◆ wget_plugin_finalizer_fn

typedef void wget_plugin_finalizer_fn(wget_plugin *plugin, int exit_status)

Prototype of the finalizer function.

Parameters

  [in] | plugin | The plugin handle
  [in] | exit_status | The 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] | plugin | The plugin handle
  [in] | option | Option name. If the option is "help", a help message must be printed to stdout.
  [in] | 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.

## ◆ 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] | plugin | The plugin handle
  [in] | iri | The URL about to be fetched
  [in] | action | Output 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] | plugin | The plugin handle
  [in] | file | Downloaded 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] | plugin | The 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] | plugin | The plugin handle
  [in] | fn | A 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] | plugin | The plugin handle
  [in] | fn | The 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

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

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

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

  action | Handle for any action taken by the plugin
  local_filename | Alternative 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] | plugin | The plugin handle
  [in] | filter_fn | The 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] | 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.

## ◆ 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] | 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.

## ◆ 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] | file | Downloaded 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] | file | Downloaded file handle
  [out] | data | The contents of the downloaded file. The memory is owned by wget and must not be free'd or modified.
  [out] | size | Size 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] | file | Downloaded 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] | file | Downloaded 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] | file | Downloaded file handle
  [in] | iri | The 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] | plugin | The plugin handle
  [in] | fn | The plugin function that will be passed a handle to downloaded files.