SwfdecURL
3
SWFDEC Library

# SwfdecURL

URL handling in Swfdec

## Synopsis

    #include <swfdec/swfdec.h>

                        SwfdecURL;
    SwfdecURL*          swfdec_url_new                      (const char *string);
    SwfdecURL*          swfdec_url_new_from_input           (const char *input);
    SwfdecURL*          swfdec_url_new_components           (const char *protocol,
                                                             const char *hostname,
                                                             guint port,
                                                             const char *path,
                                                             const char *query);
    SwfdecURL*          swfdec_url_new_relative             (const SwfdecURL *url,
                                                             const char *string);
    SwfdecURL*          swfdec_url_new_parent               (const SwfdecURL *url);
    SwfdecURL*          swfdec_url_copy                     (const SwfdecURL *url);
    void                swfdec_url_free                     (SwfdecURL *url);
    const char*         swfdec_url_get_protocol             (const SwfdecURL *url);
    gboolean            swfdec_url_has_protocol             (const SwfdecURL *url,
                                                             const char *protocol);
    const char*         swfdec_url_get_host                 (const SwfdecURL *url);
    guint               swfdec_url_get_port                 (const SwfdecURL *url);
    const char*         swfdec_url_get_path                 (const SwfdecURL *url);
    const char*         swfdec_url_get_query                (const SwfdecURL *url);
    const char*         swfdec_url_get_url                  (const SwfdecURL *url);
    gboolean            swfdec_url_is_local                 (const SwfdecURL *url);
    gboolean            swfdec_url_is_parent                (const SwfdecURL *parent,
                                                             const SwfdecURL *child);
    char*               swfdec_url_format_for_display       (const SwfdecURL *url);
    gboolean            swfdec_url_equal                    (gconstpointer a,
                                                             gconstpointer b);
    guint               swfdec_url_hash                     (gconstpointer url);
    gboolean            swfdec_url_path_is_relative         (const char *path);

## Description

SwfdecURL is Swfdec's way of handling URLs. You probably don't need to mess with this type unless you want to write a SwfdecLoader. In that case you will want to use `swfdec_loader_get_url()` to get its url and then use the functions in this section to access it.

`see_also`: SwfdecLoader

## Details

### SwfdecURL

    typedef struct _SwfdecURL SwfdecURL;

this is the structure used for URLs. It is a boxed type to glib's type system and it is not reference counted. It is also a static struct in that it cannot be modified after creation.

### swfdec_url_new ()

    SwfdecURL*          swfdec_url_new                      (const char *string);

Parses the given string into a URL for use in swfdec.

`string` :

  a valid utf-8 string possibly containing an URL

Returns :

  a new SwfdecURL or `NULL` if the URL was invalid

### swfdec_url_new_from_input ()

    SwfdecURL*          swfdec_url_new_from_input           (const char *input);

Tries to guess the right URL from the given `input`. This function is meant as a utility function helping to convert user input (like command line arguments) to a URL without requiring the full URL.

`input` :

  the input povided

Returns :

  a new url best matching the given `input`.

### swfdec_url_new_components ()

    SwfdecURL*          swfdec_url_new_components           (const char *protocol,
                                                             const char *hostname,
                                                             guint port,
                                                             const char *path,
                                                             const char *query);

Creates a new URL from the given components.

`protocol` :

  protocol to use

`hostname` :

  hostname or IP address or `NULL`

`port` :

  port number or 0. Must be 0 if no hostname is given

`path` :

  a path or `NULL`

`query` :

  the query string or `NULL`

Returns :

  a new url pointing to the url from the given components

### swfdec_url_new_relative ()

    SwfdecURL*          swfdec_url_new_relative             (const SwfdecURL *url,
                                                             const char *string);

Parses `string` into a new URL. If the given `string` is a relative URL, it uses `url` to resolve it to an absolute url; `url` must already contain a directory path.

`url` :

  a SwfdecURL

`string` :

  a relative or absolute URL path

Returns :

  a new SwfdecURL or `NULL` if an error was detected.

### swfdec_url_new_parent ()

    SwfdecURL*          swfdec_url_new_parent               (const SwfdecURL *url);

Creates a new url that is the parent of `url`. If the given `url` has no parent, a copy of itself is returned.

`url` :

  a SwfdecURL

Returns :

  a new url pointing to the parent of `url` or `NULL` on failure.

### swfdec_url_copy ()

    SwfdecURL*          swfdec_url_copy                     (const SwfdecURL *url);

copies the given url.

`url` :

  a SwfdecURL

Returns :

  a new SwfdecURL

### swfdec_url_free ()

    void                swfdec_url_free                     (SwfdecURL *url);

Frees the URL and its associated ressources.

`url` :

  a SwfdecURL

### swfdec_url_get_protocol ()

    const char*         swfdec_url_get_protocol             (const SwfdecURL *url);

Gets the protocol used by this URL, such as "http" or "file".

`url` :

  a SwfdecURL

Returns :

  the protocol used or "error" if the URL is broken

### swfdec_url_has_protocol ()

    gboolean            swfdec_url_has_protocol             (const SwfdecURL *url,
                                                             const char *protocol);

Checks if the given `url` references the given `protocol`

`url` :

  a url

`protocol` :

  protocol name to check for

Returns :

  `TRUE` if both protocols match, `FALSE` otherwise

### swfdec_url_get_host ()

    const char*         swfdec_url_get_host                 (const SwfdecURL *url);

Gets the host for `url` as a lower case string.

`url` :

  a SwfdecURL

Returns :

  the host or `NULL` if none (typically for file URLs).

### swfdec_url_get_port ()

    guint               swfdec_url_get_port                 (const SwfdecURL *url);

Gets the port number specified by the given `url`. If the `url` does not specify a port number, 0 will be returned.

`url` :

  a SwfdecURL

Returns :

  the specified port or 0 if none was given.

### swfdec_url_get_path ()

    const char*         swfdec_url_get_path                 (const SwfdecURL *url);

Gets the path associated with `url`. If it contains no path, `NULL` is returned.

The returned path does not start with a slash. So in particular for files, you want to prepend the slash yourself.

`url` :

  a SwfdecURL

Returns :

  the path or `NULL` if none

### swfdec_url_get_query ()

    const char*         swfdec_url_get_query                (const SwfdecURL *url);

Gets the query string associated with `url`. If the URL does not have a query string, `NULL` is returned.

`url` :

  a SwfdecURL

Returns :

  Query string or `NULL`

### swfdec_url_get_url ()

    const char*         swfdec_url_get_url                  (const SwfdecURL *url);

Gets the whole URL.

`url` :

  a SwfdecURL

Returns :

  the complete URL as string

### swfdec_url_is_local ()

    gboolean            swfdec_url_is_local                 (const SwfdecURL *url);

Checks if the given `url` references a local resource. Local resources are treated differently by Flash, since they get a higher degree of trust.

`url` :

  the url to check

Returns :

  `TRUE` if the given url is local.

### swfdec_url_is_parent ()

    gboolean            swfdec_url_is_parent                (const SwfdecURL *parent,
                                                             const SwfdecURL *child);

Checks if the given `parent` url is a parent url of the given `child` url. The algorithm used is the same as checking policy files if hey apply. If `parent` equals `child`, `TRUE` is returned. This function does not compare query strings.

`parent` :

  the supposed parent url

`child` :

  the supposed child url

Returns :

  `TRUE` if `parent` is a parent of `child`, `FALSE` otherwise.

### swfdec_url_format_for_display ()

    char*               swfdec_url_format_for_display       (const SwfdecURL *url);

Creates a string suitable to display the given `url`. An example for using this function is to identify a currently playing Flash URL. Use `swfdec_player_get_url()` to query the player's URL and then use this function to get a displayable string.

`url` :

  the url to display

Returns :

  A new string containig a short description for this URL. `g_free()` after use.

### swfdec_url_equal ()

    gboolean            swfdec_url_equal                    (gconstpointer a,
                                                             gconstpointer b);

Compares the 2 given URLs for equality. 2 URLs are considered equal, when they point to the same resource. This function is intended to be used together with `swfdec_url_hash()` in a GHashtable.

`a` :

  a SwfdecURL

`b` :

  a SwfdecURL

Returns :

  `TRUE` if the 2 given urls point to the same resource, `FALSE` otherwise.

### swfdec_url_hash ()

    guint               swfdec_url_hash                     (gconstpointer url);

Creates a hash value for the given `url`. This function is intended to be used together with `swfdec_url_equal()` in a GHashtable.

`url` :

  a SwfdecURL

Returns :

  a hash value

### swfdec_url_path_is_relative ()

    gboolean            swfdec_url_path_is_relative         (const char *path);

Checks if the given URL is relative or absolute.

`path` :

  a string used to specify a url

Returns :

  `TRUE` if the path is a relative path, `FALSE` if it is absolute