## SwfdecURL 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);
    guint               swfdec_url_hash                     (gconstpointer url);
    gboolean            swfdec_url_equal                    (gconstpointer a,
                                                             gconstpointer b);
    gboolean            swfdec_url_host_equal               (gconstpointer a,
                                                             gconstpointer b);
    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.

Note that URLs inside Swfdec mirror the behavior of Flash and will therefore not miror standards behavior, but the behavior of Flash.

`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.

### Note

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_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_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_host_equal ()

    gboolean            swfdec_url_host_equal               (gconstpointer a,
                                                             gconstpointer b);

Compares the 2 given URLs for equality, ignoring path. 2 URLs are considered to have equal hosts when they have the same protocol, host, and port.

`a` : | a SwfdecURL
`b` : | a SwfdecURL
Returns : | `TRUE` if the 2 given urls point to the same host, `FALSE` otherwise.

### 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