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"             gchararray            : Read / Write
  "host"                 gchararray            : Read / Write
  "password"             gchararray            : Read / Write
  "path"                 gchararray            : Read / Write
  "port"                 guint                 : Read / Write
  "query"                gchararray            : Read / Write
  "user-name"            gchararray            : 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.
Returns :

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"             gchararray            : Read / Write

Fragment (for HTTP resources).

Default value: NULL

The "host" property

  "host"                 gchararray            : Read / Write

name of host having resource.

Default value: NULL

The "password" property

  "password"             gchararray            : Read / Write

password protecting resource.

Default value: NULL

The "path" property

  "path"                 gchararray            : 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"                gchararray            : Read / Write

Query (for HTTP resources).

Default value: NULL

The "user-name" property

  "user-name"            gchararray            : Read / Write

username for resource.

Default value: NULL