## GskUrl

GskUrl — A Universal Resource Locator (or Identifier) object.

## Synopsis

                        GskUrl;
    enum                GskUrlScheme;
    #define             GSK_URL_RESERVED_CHARSET
    #define             GSK_URL_UNRESERVED_CHARSET
    GskUrl *            gsk_url_new                         (const char *spec,
                                                             GError **error);
    GskUrl *            gsk_url_new_in_context              (const char *spec,
                                                             GskUrlScheme context,
                                                             GError **error);
    GskUrl *            gsk_url_new_from_parts              (GskUrlScheme scheme,
                                                             const char *host,
                                                             int port,
                                                             const char *user_name,
                                                             const char *password,
                                                             const char *path,
                                                             const char *query,
                                                             const char *fragment);
    GskUrl *            gsk_url_new_relative                (GskUrl *base_url,
                                                             const char *location,
                                                             GError **error);
    char *              gsk_url_get_relative_path           (GskUrl *url);
    guint               gsk_url_get_port                    (const GskUrl *url);
    char *              gsk_url_decode                      (const char *encoded);
    char *              gsk_url_decode_http                 (const char *encoded);
    char *              gsk_url_encode                      (const char *decoded);
    char *              gsk_url_encode_http                 (const char *decoded);
    #define             gsk_url_is_valid_fragment           (str, bad_char_out)
    gboolean            gsk_url_is_valid_generic_component  (const char *str,
                                                             char *bad_char_out);
    gboolean            gsk_url_is_valid_hostname           (const char *str,
                                                             char *bad_char_out);
    #define             gsk_url_is_valid_path               (str, bad_char_out)
    #define             gsk_url_is_valid_query              (str, bad_char_out)
    char **             gsk_url_split_form_urlencoded       (const char *encoded_query);
    char *              gsk_url_to_string                   (const GskUrl *url);
    void                (*GskUrlSuccess)                    (GskStream *stream,
                                                             gpointer user_data);
    void                (*GskUrlFailure)                    (GError *error,
                                                             gpointer user_data);
    void                gsk_url_download                    (GskUrl *url,
                                                             GskUrlSuccess success_func,
                                                             GskUrlFailure failure_func,
                                                             gpointer user_data);
    GskUrl *            (*GskUrlParser)                     (GskUrlScheme scheme,
                                                             const char *url,
                                                             gpointer data);
    char *              (*GskUrlToString)                   (GskUrl *url,
                                                             gpointer data);
    GskUrlScheme        gsk_url_scheme_get_unique           (const char *url_scheme,
                                                             guint default_port,
                                                             GskUrlParser parse_func,
                                                             GskUrlToString print_func,
                                                             gpointer data);
    guint               gsk_url_hash                        (const GskUrl *url);
    gboolean            gsk_url_equal                       (const GskUrl *a,
                                                             const GskUrl *b);
                        GskUrlDownload;
    void                (*GskUrlDownloadMethod)             (GskUrlDownload *download,
                                                             gpointer download_data);
    void                gsk_url_scheme_add_dl_method        (GskUrlScheme scheme,
                                                             GskUrlDownloadMethod download_method,
                                                             gpointer download_data);
    void                gsk_url_download_success            (GskUrlDownload *download,
                                                             GskStream *stream);
    void                gsk_url_download_fail               (GskUrlDownload *download,
                                                             GError *error);
    GskUrl *            gsk_url_download_peek_url           (GskUrlDownload *download);
    void                gsk_url_download_redirect           (GskUrlDownload *download,
                                                             GskUrl *new_url);

## Object Hierarchy

      GObject
       +----GskUrl

## Properties

      "fragment"                 gchar*                : Read / Write
      "host"                     gchar*                : Read / Write
      "password"                 gchar*                : Read / Write
      "path"                     gchar*                : Read / Write
      "port"                     guint                 : Read / Write
      "query"                    gchar*                : Read / Write
      "user-name"                gchar*                : Read / Write

## Description

A URL is a pointer to content on the internet. (Well, not all types of URLs apply across the internet; especially file URLs are really quite local.)

This class provides convenient parsing and printing methods, as well as support for downloading the content of various URL types.

Also, we provide interfaces for URL encoding and decoding strings. This may be used to provide GET data from the HTTP client, amongst other things. TODO: find a reference RFC for URL encoding.

## Details

### GskUrl

    typedef struct _GskUrl GskUrl;

A URL (Universal Resource Locator). This structure contains a number of read-only, pre-parsed fields, which make it easy to use the URL from C.

It also derived from GObject, so you get the usual g_object_ref/unref and other usual benefits.

### enum GskUrlScheme

    typedef enum
    {
      GSK_URL_SCHEME_FILE,
      GSK_URL_SCHEME_HTTP,
      GSK_URL_SCHEME_HTTPS,
      GSK_URL_SCHEME_FTP,
      GSK_URL_SCHEME_OTHER = 0x10000,
    } GskUrlScheme;

Types of URLs that are known. (This is an extensible enum-- you can allocate new enum values using `gsk_url_scheme_get_unique()`).

`GSK_URL_SCHEME_FILE` | The URL corresponds to a local file.
`GSK_URL_SCHEME_HTTP` | The URL corresponds to HTTP-retrievable content.
`GSK_URL_SCHEME_HTTPS` | The URL corresponds to HTTPS-retrievable content. HTTPS is secure HTTP: it is just HTTP over SSL.
`GSK_URL_SCHEME_FTP` | The URL corresponds to FTP-retrievable content.
`GSK_URL_SCHEME_OTHER` | An unknown URL scheme was encountered.

### GSK_URL_RESERVED_CHARSET

    #define             GSK_URL_RESERVED_CHARSET

[From RFC 2396, section 2.2.] Characters having specific meaning within a url; these should be escaped to be passed on to the underlying scheme.

### GSK_URL_UNRESERVED_CHARSET

    #define             GSK_URL_UNRESERVED_CHARSET

[From RFC 2396, section 2.3.] Characters which do not normally need escaping within a URL.

### gsk_url_new ()

    GskUrl *            gsk_url_new                         (const char *spec,
                                                             GError **error);

Parse a URL object from a string.

`spec` : | standard string representation of the URL.
`error` : | place to store a GError if an error occurs.
Returns : | a reference to a new URL object, or NULL if an error occurred.

### gsk_url_new_in_context ()

    GskUrl *            gsk_url_new_in_context              (const char *spec,
                                                             GskUrlScheme context,
                                                             GError **error);

For places where you expect a certain type of URL, soemtimes people get lazy and drop the scheme. We support this here, by allowing a "backup scheme" to be specified.

To be fully paranoid in such a situation, you may wish to if there appears to be a scheme, use `gsk_url_new()`; otherwise call `gsk_url_new_from_scheme_specific()` directly. Alternately, it may be easier just to call `gsk_url_new_in_context()` directly all the time.

See also `gsk_url_new_relative()`.

`spec` : | rough URL specification. This may be a complete URL, or it may have an implied scheme.
`context` : | default scheme for URL's in your context.
`error` : | place to store a GError if something goes wrong.
Returns : | a newly allocated URL object.

### gsk_url_new_from_parts ()

    GskUrl *            gsk_url_new_from_parts              (GskUrlScheme scheme,
                                                             const char *host,
                                                             int port,
                                                             const char *user_name,
                                                             const char *password,
                                                             const char *path,
                                                             const char *query,
                                                             const char *fragment);

Allocate a new URL from a bunch of pieces.

`scheme` : | the type of URL being created.
`host` : | the name (or numeric address as ASCII digits and dots) of the host. This is called the Authority by RFC 2396, Section 3.2.
`port` : | the port number to use for the service, or 0 to use the default port for this type of URL scheme. For FTP, this is the control port and the data port will default to the next integer.
`user_name` : | optional username identifier from the client.
`password` : | optional password to authenticate.
`path` : | the host-relative path for the URL
`query` : | optional query string for URL.
`fragment` : | optional information about a sublocation in the resource.
Returns : | a reference to a new URL object.

### gsk_url_new_relative ()

    GskUrl *            gsk_url_new_relative                (GskUrl *base_url,
                                                             const char *location,
                                                             GError **error);

Allocate a new URL, which will be taken to be relative to `base_url` if the `location` is not obviously an absolute URL.

Note that there is some ambiguity in how relative urls are interpreted. Note especially that /foo + /bar = /bar. /foo + bar = /bar. /foo/ + bar = /foo/bar. That is, a symbol with a trailing slash is a directory, otherwise the last piece of the url is assumed to be a file.

`base_url` : | context of the `spec` found. This tells where `spec` may be relative to.
`location` : | the possibly relative spec.
`error` : | place to store a GError if something goes wrong.
Returns : | a newly allocated URL object.

### gsk_url_get_relative_path ()

    char *              gsk_url_get_relative_path           (GskUrl *url);

Obtain the path portion of a URL without the initial slash (/) character.

The query component and fragment are also returned.

`url` : | the URL to get the host-relative path from.
Returns : | the URL as a string. This must be freed by the caller.

### gsk_url_get_port ()

    guint               gsk_url_get_port                    (const GskUrl *url);

Returns the port. If the port is 0, the default port for the type of scheme is returned (80 for HTTP, 21 for FTP and 443 for HTTP/SSL). If no default exists, 0 is returned.

`url` : | the URL whose port is desired.
Returns : | the port as an integer, or 0 if no port could be computed.

### gsk_url_decode ()

    char *              gsk_url_decode                      (const char *encoded);

Decode characters to be passed in a URL. Basically, any `xx` string is changed to the character whose ASCII code is xx, treating xx as a hexidecimal 2-digit number.

See RFC ??, Section ??.

`encoded` : | encoded URL to convert to plaintext.
Returns : | a newly allocated string.

### gsk_url_decode_http ()

    char *              gsk_url_decode_http                 (const char *encoded);

Do what is typically thought of as "url decoding" in http-land... namely '+' maps to SPACE and `xx`, where 'x' denotes a single hex-digit, maps to the character given as hexidecimal. (warning: the resulting string is not UTF-8)

`encoded` : | the encoded url text.
Returns : | a newly allocated encoded string that the caller must free (the empty string "" when unable to decode hex).

### gsk_url_encode ()

    char *              gsk_url_encode                      (const char *decoded);

Encode characters to be passed in a URL. Basically, "unsafe" characters are converted to `xx` where 'x' is a hexidecimal digit.

See RFC 2396 Section 2.

`decoded` : | decoded data to escape.
Returns : | a newly allocated string.

### gsk_url_encode_http ()

    char *              gsk_url_encode_http                 (const char *decoded);

Do what is typically thought of as "url encoding" in http-land... namely SPACE maps to '+' and funny characters are encoded as `xx` where 'x' denotes a single hex-digit.

`decoded` : | the raw url text; this is treated as raw 8-bit data, not UTF-8.
Returns : | a newly allocated encoded string that the caller must free.

### gsk_url_is_valid_fragment()

    #define             gsk_url_is_valid_fragment(str, bad_char_out)

`str` : |
`bad_char_out` : |

### gsk_url_is_valid_generic_component ()

    gboolean            gsk_url_is_valid_generic_component  (const char *str,
                                                             char *bad_char_out);

`str` : |
`bad_char_out` : |
Returns : |

### gsk_url_is_valid_hostname ()

    gboolean            gsk_url_is_valid_hostname           (const char *str,
                                                             char *bad_char_out);

`str` : |
`bad_char_out` : |
Returns : |

### gsk_url_is_valid_path()

    #define             gsk_url_is_valid_path(str, bad_char_out)

`str` : |
`bad_char_out` : |

### gsk_url_is_valid_query()

    #define             gsk_url_is_valid_query(str, bad_char_out)

`str` : |
`bad_char_out` : |

### gsk_url_split_form_urlencoded ()

    char **             gsk_url_split_form_urlencoded       (const char *encoded_query);

`encoded_query` : |
Returns : |

### gsk_url_to_string ()

    char *              gsk_url_to_string                   (const GskUrl *url);

Convert the URL to a string.

`url` : | the URL to stringify.
Returns : | the newly allocated string.

### GskUrlSuccess ()

    void                (*GskUrlSuccess)                    (GskStream *stream,
                                                             gpointer user_data);

Function to call with an input stream if the URL download request seems to be succeeding.

`stream` : | content stream of the data referenced by the URL which was passed to `gsk_url_download()`.
`user_data` : | data passed to `gsk_url_download()`.

### GskUrlFailure ()

    void                (*GskUrlFailure)                    (GError *error,
                                                             gpointer user_data);

Function to call if the URL download seems to be failing.

`error` : | the error that preventing the URL download from starting.
`user_data` : | data passed to `gsk_url_download()`.

### gsk_url_download ()

    void                gsk_url_download                    (GskUrl *url,
                                                             GskUrlSuccess success_func,
                                                             GskUrlFailure failure_func,
                                                             gpointer user_data);

Initiate a URL download.

A caller-supplied function will be invoked when the first content is available or a different function will be called if there is a problem. Only exactly one of these functions will be called.

Either callback may be invoked before this function returns: the caller must deal with it.

`url` : | the URL to attempt to retrieve.
`success_func` : | a function to call with a stream corresponding to the content of the page.
`failure_func` : | a function to call with an error message if the url cannot be retrieved.
`user_data` : | data to pass to `success_func` or `failure_func`.

### GskUrlParser ()

    GskUrl *            (*GskUrlParser)                     (GskUrlScheme scheme,
                                                             const char *url,
                                                             gpointer data);

Function to parse a string (of a given scheme) into a GskUrl. This is used to register new types of URL. See `gsk_url_scheme_get_unique()`.

`scheme` : | the type of URL, as determined by the first characters of the URL.
`url` : | the whole URL.
`data` : | data passed to `gsk_url_scheme_get_unique()`.
Returns : | a newly allocated URL, or NULL on a parse error.

### GskUrlToString ()

    char *              (*GskUrlToString)                   (GskUrl *url,
                                                             gpointer data);

Function to convert a GskUrl into a NUL-terminated string. This is used to register new types of URL. See `gsk_url_scheme_get_unique()`.

`url` : | the URL to print.
`data` : | data passed to `gsk_url_scheme_get_unique()`.
Returns : | a newly allocated C string, or NULL on error.

### gsk_url_scheme_get_unique ()

    GskUrlScheme        gsk_url_scheme_get_unique           (const char *url_scheme,
                                                             guint default_port,
                                                             GskUrlParser parse_func,
                                                             GskUrlToString print_func,
                                                             gpointer data);

`url_scheme` : |
`default_port` : |
`parse_func` : |
`print_func` : |
`data` : |
Returns : |

### gsk_url_hash ()

    guint               gsk_url_hash                        (const GskUrl *url);

Compute a randomish hash code based on the URL.

You can create a GHashTable that's keyed off of URLs with: g_hash_table_new((GHashFunc)gsk_url_hash, (GEqualFunc)gsk_url_equal);

`url` : | a url.
Returns : | the hash code.

### gsk_url_equal ()

    gboolean            gsk_url_equal                       (const GskUrl *a,
                                                             const GskUrl *b);

Test to see if two URLs are the same.

`a` : | a url.
`b` : | another url.
Returns : | whether the URLs are the same.

### GskUrlDownload

    typedef struct _GskUrlDownload GskUrlDownload;

### GskUrlDownloadMethod ()

    void                (*GskUrlDownloadMethod)             (GskUrlDownload *download,
                                                             gpointer download_data);

Function to begin downloading a given URL.

A function which must eventually call `gsk_url_download_fail()` or `gsk_url_download_success()`. (Note: it may happen long after this function returns, but it is allowed to call these functions before returning as well).

This function type is only used to register new methods for downloading URLs.

`download` : | the object representing the download.
`download_data` : | data passed in to `gsk_url_scheme_add_dl_method()`.

### gsk_url_scheme_add_dl_method ()

    void                gsk_url_scheme_add_dl_method        (GskUrlScheme scheme,
                                                             GskUrlDownloadMethod download_method,
                                                             gpointer download_data);

Register a new method for downloading a URL of a particular scheme.

The callback `download_method` will be run with each new requested URL. Each call to `download_method` must cause it to eventually call `gsk_url_download_success()` or `gsk_url_download_fail()`; furthermore, it may call those functions before returning.

`scheme` : | the URL scheme which this download method can handle.
`download_method` : | function to call to initiate the URL download.
`download_data` : | data to be passed to download_method.

### gsk_url_download_success ()

    void                gsk_url_download_success            (GskUrlDownload *download,
                                                             GskStream *stream);

Give a stream to the user which requested it via `gsk_url_download()`.

This function should only be used for implementing handlers for new URL schemes.

`download` : | the download object.
`stream` : | the content stream to return to the caller who requested the download.

### gsk_url_download_fail ()

    void                gsk_url_download_fail               (GskUrlDownload *download,
                                                             GError *error);

Give a failure notice to the user which requested a url download via `gsk_url_download()`.

This function should only be used for implementing handlers for new URL schemes.

`download` : | the download object.
`error` : | an error to return.

### gsk_url_download_peek_url ()

    GskUrl *            gsk_url_download_peek_url           (GskUrlDownload *download);

Get the URL that you are supposed to download.

`download` : | the download object to query.
Returns : | the URL for downloading.

### gsk_url_download_redirect ()

    void                gsk_url_download_redirect           (GskUrlDownload *download,
                                                             GskUrl *new_url);

Indicate that retrieving one URL lead to a message saying that the content is at a different URL. The new URL should be retrieved, just like if it has been the original requestor.

This function should only be used for implementing handlers for new URL schemes.

`download` : | the download whose URL has been redirected.
`new_url` : | the new URL to download.

## Property Details

### The `"fragment"` property

      "fragment"                 gchar*                : Read / Write

Fragment (for HTTP resources).

Default value: NULL

### The `"host"` property

      "host"                     gchar*                : Read / Write

name of host having resource.

Default value: NULL

### The `"password"` property

      "password"                 gchar*                : Read / Write

password protecting resource.

Default value: NULL

### The `"path"` property

      "path"                     gchar*                : Read / Write

Path on the server to the resource.

Default value: NULL

### The `"port"` property

      "port"                     guint                 : Read / Write

port for resource (or 0 for default).

Allowed values: <= 65536

Default value: 0

### The `"query"` property

      "query"                    gchar*                : Read / Write

Query (for HTTP resources).

Default value: NULL

### The `"user-name"` property

      "user-name"                gchar*                : Read / Write

username for resource.

Default value: NULL