# gnome-url

## Name

gnome-url -- Display urls using appropriate viewers.

## Synopsis

    #include <libgnome/libgnome.h>

    enum        GnomeURLError;
    #define     GNOME_URL_ERROR
    gboolean    gnome_url_show                  (const char *url,
                                                 GError **error);
    gboolean    gnome_url_show_with_env         (const char *url,
                                                 char **envp,
                                                 GError **error);

## Description

A GNOME user can configure which viewers they wish to use to view certain protocols. Protocols can include http, ftp (where "view" might mean "download"), ghelp, etc. This module provides a means for application to display a url without having to worry about which viewer is going to ultimately handle the job.

## Details

### enum GnomeURLError

    typedef enum {
      GNOME_URL_ERROR_PARSE
    } GnomeURLError;

The errors that can be returned due to bad parameters being pass to gnome_url_show().

`GNOME_URL_ERROR_PARSE` | The parsing of the handler failed.

### GNOME_URL_ERROR

    #define GNOME_URL_ERROR (gnome_url_error_quark ())

The class (domain) of errors raised by this module.

### gnome_url_show ()

    gboolean    gnome_url_show                  (const char *url,
                                                 GError **error);

Displays the given URL in an appropriate viewer. The appropriate viewer is user definable. It is determined by extracting the protocol from the `url`, then seeing if the /desktop/gnome/url-handlers/<protocol>/command key exists in the configuration database. It it does, this entry is used as the template for the command.

If no protocol specific handler exists, the /desktop/gnome/url-handlers/unknown/command key is used to determine the viewer.

Once a viewer is determined, it is called with the `url` as a parameter. If any errors occur, they are returned in the `error` parameter. These errors will either be in the `GNOME_URL_ERROR`, `GNOME_SHELL_ERROR`, or `G_SPAWN_ERROR` domains.

`url` : | The url to display. Should begin with the protocol to use (e.g. "http:", "ghelp:", etc)
`error` : | Used to store any errors that result from trying to display the `url`.
Returns : | `TRUE` if everything went fine, `FALSE` otherwise (in which case `error` will contain the actual error).

### gnome_url_show_with_env ()

    gboolean    gnome_url_show_with_env         (const char *url,
                                                 char **envp,
                                                 GError **error);

Like gnome_url_show(), but the the contents of `envp` will become the url viewer's environment rather than inheriting from the parents environment.

`url` : | The url to display. Should begin with the protocol to use (e.g. "http:", "ghelp:", etc)
`envp` : | child's environment, or `NULL` to inherit parent's.
`error` : | Used to store any errors that result from trying to display the `url`.
Returns : | `TRUE` if everything went fine, `FALSE` otherwise (in which case `error` will contain the actual error).