URI
3
RAPTOR Library

# URI

URI class and relative URI computation

## Synopsis

    typedef             raptor_uri;
                        raptor_uri_handler;
    raptor_uri*         raptor_new_uri                      (unsigned char *uri_string);
    raptor_uri*         raptor_new_uri_from_uri_local_name  (raptor_uri *uri,
                                                             unsigned char *local_name);
    raptor_uri*         raptor_new_uri_relative_to_base     (raptor_uri *base_uri,
                                                             unsigned char *uri_string);
    raptor_uri*         raptor_new_uri_from_id              (raptor_uri *base_uri,
                                                             unsigned char *id);
    raptor_uri*         raptor_new_uri_for_rdf_concept      (const char *name);
    void                raptor_free_uri                     (raptor_uri *uri);
    int                 raptor_uri_compare                  (raptor_uri *uri1,
                                                             raptor_uri *uri2);
    int                 raptor_uri_equals                   (raptor_uri *uri1,
                                                             raptor_uri *uri2);
    raptor_uri*         raptor_uri_copy                     (raptor_uri *uri);
    unsigned char*      raptor_uri_as_string                (raptor_uri *uri);
    unsigned char*      raptor_uri_as_counted_string        (raptor_uri *uri,
                                                             size_t *len_p);
    raptor_uri*         raptor_new_uri_for_xmlbase          (raptor_uri *old_uri);
    raptor_uri*         raptor_new_uri_for_retrieval        (raptor_uri *old_uri);
    void                raptor_uri_resolve_uri_reference    (unsigned char *base_uri,
                                                             unsigned char *reference_uri,
                                                             unsigned char *buffer,
                                                             size_t length);
    unsigned char*      raptor_uri_filename_to_uri_string   (const char *filename);
    char*               raptor_uri_uri_string_to_filename   (unsigned char *uri_string);
    char*               raptor_uri_uri_string_to_filename_fragment
                                                            (unsigned char *uri_string,
                                                             unsigned char **fragment_p);
    int                 raptor_uri_uri_string_is_file_uri   (unsigned char *uri_string);
    int                 raptor_uri_is_file_uri              (unsigned char *uri_string);
    unsigned char*      raptor_uri_to_relative_counted_uri_string
                                                            (raptor_uri *base_uri,
                                                             raptor_uri *reference_uri,
                                                             size_t *length_p);
    unsigned char*      raptor_uri_to_relative_uri_string   (raptor_uri *base_uri,
                                                             raptor_uri *reference_uri);
    void                raptor_uri_print                    (const raptor_uri *uri,
                                                             FILE *stream);
    unsigned char*      raptor_uri_to_counted_string        (raptor_uri *uri,
                                                             size_t *len_p);
    unsigned char*      raptor_uri_to_string                (raptor_uri *uri);
    void                raptor_uri_set_handler              (const raptor_uri_handler *handler,
                                                             void *context);
    void                raptor_uri_get_handler              (const raptor_uri_handler **handler,
                                                             void **context);
    int                 raptor_iostream_write_uri           (raptor_iostream *iostr,
                                                             raptor_uri *uri);

## Description

A class for absolute URIs used inside raptor and relative URI computation utility functions used inside the main Redland librdf_uri class. Only absolute URIs are provided, with no current access to internals of URIs such as URI scheme, path, authority.

## Details

### raptor_uri

    raptor_uri* raptor_uri;

Raptor URI Class.

### raptor_uri_handler

    typedef struct {
      /* constructors - URI Interface V1 */
      raptor_new_uri_func                     new_uri;
      raptor_new_uri_from_uri_local_name_func new_uri_from_uri_local_name;
      raptor_new_uri_relative_to_base_func    new_uri_relative_to_base;
      raptor_new_uri_for_rdf_concept_func     new_uri_for_rdf_concept;
      /* destructor - URI Interface V1 */
      raptor_free_uri_func                    free_uri;
      /* methods - URI Interface V1 */
      raptor_uri_equals_func                  uri_equals;
      raptor_uri_copy_func                    uri_copy; /* well, copy constructor */
      raptor_uri_as_string_func               uri_as_string;
      raptor_uri_as_counted_string_func       uri_as_counted_string;
      int initialised;
      /* methods - URI Interface V2 */
      raptor_uri_compare_func                 uri_compare;
    } raptor_uri_handler;

URI implementation handler structure.

raptor_new_uri_func new_uri;

  function for `raptor_new_uri()`

raptor_new_uri_from_uri_local_name_func new_uri_from_uri_local_name;

  function for `raptor_new_uri_from_uri_local_name()`

raptor_new_uri_relative_to_base_func new_uri_relative_to_base;

  function for `raptor_new_uri_relative_to_base()`

raptor_new_uri_for_rdf_concept_func new_uri_for_rdf_concept;

  function for `raptor_new_uri_for_rdf_concept()`

raptor_free_uri_func free_uri;

  function for `raptor_free_uri()`

raptor_uri_equals_func uri_equals;

  function for `raptor_uri_equals()`

raptor_uri_copy_func uri_copy;

  function for `raptor_uri_copy()`

raptor_uri_as_string_func uri_as_string;

  function for `raptor_uri_as_string()`

raptor_uri_as_counted_string_func uri_as_counted_string;

  function for `raptor_uri_as_counted_string()`

int initialised;

  API version - set to API version implemented: 1..2

raptor_uri_compare_func uri_compare;

  function for `raptor_uri_compare()`

### raptor_new_uri ()

    raptor_uri*         raptor_new_uri                      (unsigned char *uri_string);

Constructor - create a raptor URI from a UTF-8 encoded Unicode string.

`uri_string` :

  URI string.

Returns :

  a new raptor_uri object or NULL on failure.

### raptor_new_uri_from_uri_local_name ()

    raptor_uri*         raptor_new_uri_from_uri_local_name  (raptor_uri *uri,
                                                             unsigned char *local_name);

Constructor - create a raptor URI from an existing URI and a local name.

Creates a new URI from the concatenation of the `local_name` to the `uri`. This is NOT relative URI resolution, which is done by the `raptor_new_uri_relative_to_base()` constructor.

`uri` :

  existing raptor_uri

`local_name` :

  local name

Returns :

  a new raptor_uri object or NULL on failure.

### raptor_new_uri_relative_to_base ()

    raptor_uri*         raptor_new_uri_relative_to_base     (raptor_uri *base_uri,
                                                             unsigned char *uri_string);

Constructor - create a raptor URI from a base URI and a relative URI string.

`base_uri` :

  existing base URI

`uri_string` :

  relative URI string

Returns :

  a new raptor_uri object or NULL on failure.

### raptor_new_uri_from_id ()

    raptor_uri*         raptor_new_uri_from_id              (raptor_uri *base_uri,
                                                             unsigned char *id);

Constructor - create a new URI from a base URI and RDF ID.

This creates a URI equivalent to concatenating `base_uri` with ## and `id`.

`base_uri` :

  existing base URI

`id` :

  RDF ID

Returns :

  a new raptor_uri object or NULL on failure.

### raptor_new_uri_for_rdf_concept ()

    raptor_uri*         raptor_new_uri_for_rdf_concept      (const char *name);

Constructor - create a raptor URI for the RDF namespace concept name.

Example: u=raptor_new_uri_for_rdf_concept("value") creates a new URI for the rdf:value term.

`name` :

  RDF namespace concept

Returns :

  a new raptor_uri object or NULL on failure

### raptor_free_uri ()

    void                raptor_free_uri                     (raptor_uri *uri);

Destructor - destroy a raptor_uri object

`uri` :

  URI to destroy

### raptor_uri_compare ()

    int                 raptor_uri_compare                  (raptor_uri *uri1,
                                                             raptor_uri *uri2);

Compare two URIs, ala strcmp.

A NULL URI is always less than (never equal to) a non-NULL URI.

`uri1` :

  URI 1 (may be NULL)

`uri2` :

  URI 2 (may be NULL)

Returns :

  -1 if uri1 < uri2, 0 if equal, 1 if uri1 > uri2

### raptor_uri_equals ()

    int                 raptor_uri_equals                   (raptor_uri *uri1,
                                                             raptor_uri *uri2);

Check if two URIs are equal.

A NULL URI is not equal to a non-NULL URI.

`uri1` :

  URI 1 (may be NULL)

`uri2` :

  URI 2 (may be NULL)

Returns :

  non-0 if the URIs are equal

### raptor_uri_copy ()

    raptor_uri*         raptor_uri_copy                     (raptor_uri *uri);

Constructor - get a copy of a URI.

`uri` :

  URI object

Returns :

  a new raptor_uri object or NULL on failure

### raptor_uri_as_string ()

    unsigned char*      raptor_uri_as_string                (raptor_uri *uri);

Get a string representation of a URI.

Returns a shared pointer to a string representation of `uri`. This string is shared and must not be freed, otherwise see use the `raptor_uri_to_string()` or `raptor_uri_to_counted_string()` methods.

`uri` :

  raptor_uri object

Returns :

  shared string representation of URI

### raptor_uri_as_counted_string ()

    unsigned char*      raptor_uri_as_counted_string        (raptor_uri *uri,
                                                             size_t *len_p);

Get a string representation of a URI with count.

Returns a shared pointer to a string representation of `uri` along with the length of the string in `len_p`, if not NULL. This string is shared and must not be freed, otherwise see use the `raptor_uri_to_string()` or `raptor_uri_to_counted_string()` methods.

`uri` :

  URI object

`len_p` :

  address of length variable or NULL

Returns :

  shared string representation of URI

### raptor_new_uri_for_xmlbase ()

    raptor_uri*         raptor_new_uri_for_xmlbase          (raptor_uri *old_uri);

Constructor - create a URI suitable for use as an XML Base.

Takes an existing URI and ensures it has a path (default /) and has no fragment or query arguments - XML base does not use these.

`old_uri` :

  URI to transform

Returns :

  new raptor_uri object or NULL on failure.

### raptor_new_uri_for_retrieval ()

    raptor_uri*         raptor_new_uri_for_retrieval        (raptor_uri *old_uri);

Constructor - create a URI suitable for retrieval.

Takes an existing URI and ensures it has a path (default /) and has no fragment - URI retrieval does not use the fragment part.

`old_uri` :

  URI to transform

Returns :

  new raptor_uri object or NULL on failure.

### raptor_uri_resolve_uri_reference ()

    void                raptor_uri_resolve_uri_reference    (unsigned char *base_uri,
                                                             unsigned char *reference_uri,
                                                             unsigned char *buffer,
                                                             size_t length);

Resolve a URI to a base URI.

`base_uri` :

  Base URI string

`reference_uri` :

  Reference URI string

`buffer` :

  Destination buffer URI

`length` :

  Length of destination buffer

### raptor_uri_filename_to_uri_string ()

    unsigned char*      raptor_uri_filename_to_uri_string   (const char *filename);

Converts a filename to a file: URI.

Handles the OS-specific escaping on turning filenames into URIs and returns a new buffer that the caller must `free()`. Turns a space in the filname into `20` and '%' into `25`.

`filename` :

  The filename to convert

Returns :

  A newly allocated string with the URI or NULL on failure

### raptor_uri_uri_string_to_filename ()

    char*               raptor_uri_uri_string_to_filename   (unsigned char *uri_string);

Convert a file: URI to a filename.

Handles the OS-specific file: URIs to filename mappings. Returns a new buffer containing the filename that the caller must free.

`uri_string` :

  The file: URI to convert

Returns :

  A newly allocated string with the filename or NULL on failure

### raptor_uri_uri_string_to_filename_fragment ()

    char*               raptor_uri_uri_string_to_filename_fragment
                                                            (unsigned char *uri_string,
                                                             unsigned char **fragment_p);

Convert a file: URI to a filename and fragment.

Handles the OS-specific file: URIs to filename mappings. Returns a new buffer containing the filename that the caller must free.

If `fragment_p` is given, a new string containing the URI fragment is returned, or NULL if none is present

`uri_string` :

  The file: URI to convert

`fragment_p` :

  Address of pointer to store any URI fragment or NULL

Returns :

  A newly allocated string with the filename or NULL on failure

### raptor_uri_uri_string_is_file_uri ()

    int                 raptor_uri_uri_string_is_file_uri   (unsigned char *uri_string);

Check if a URI string is a file: URI.

`uri_string` :

  The URI string to check

Returns :

  Non zero if URI string is a file: URI

### raptor_uri_is_file_uri ()

    int                 raptor_uri_is_file_uri              (unsigned char *uri_string);

`raptor_uri_is_file_uri` is deprecated and should not be used in newly-written code.

Check if a URI string is a file: URI.

`deprecated`: use `raptor_uri_uri_string_is_file_uri()` instead

`uri_string` :

  The URI string to check

Returns :

  Non zero if URI string is a file: URI

### raptor_uri_to_relative_counted_uri_string ()

    unsigned char*      raptor_uri_to_relative_counted_uri_string
                                                            (raptor_uri *base_uri,
                                                             raptor_uri *reference_uri,
                                                             size_t *length_p);

Get the counted relative URI string of a URI against a base URI.

`base_uri` :

  The base absolute URI to resolve against (or NULL)

`reference_uri` :

  The reference absolute URI to use

`length_p` :

  Location to store the length of the relative URI string or NULL

Returns :

  A newly allocated relative URI string or NULL on failure

### raptor_uri_to_relative_uri_string ()

    unsigned char*      raptor_uri_to_relative_uri_string   (raptor_uri *base_uri,
                                                             raptor_uri *reference_uri);

Get the relative URI string of a URI against a base URI.

`base_uri` :

  The base absolute URI to resolve against

`reference_uri` :

  The reference absolute URI to use

Returns :

  A newly allocated relative URI string or NULL on failure

### raptor_uri_print ()

    void                raptor_uri_print                    (const raptor_uri *uri,
                                                             FILE *stream);

Print a URI to a file handle.

`uri` :

  URI to print

`stream` :

  The file handle to print to

### raptor_uri_to_counted_string ()

    unsigned char*      raptor_uri_to_counted_string        (raptor_uri *uri,
                                                             size_t *len_p);

Get a new counted string for a URI.

If `len_p` is not NULL, the length of the string is stored in it.

The memory allocated must be freed by the caller and `raptor_free_memory()` should be used for best portability.

`uri` :

  raptor_uri object

`len_p` :

  Pointer to length (or NULL)

Returns :

  new string or NULL on failure

### raptor_uri_to_string ()

    unsigned char*      raptor_uri_to_string                (raptor_uri *uri);

Get a new string for a URI.

The memory allocated must be freed by the caller and `raptor_free_memory()` should be used for best portability.

`uri` :

  raptor_uri object

Returns :

  new string or NULL on failure

### raptor_uri_set_handler ()

    void                raptor_uri_set_handler              (const raptor_uri_handler *handler,
                                                             void *context);

Change the URI class implementation to the functions provided by the

The URI interface in `handler->initialised` should be either 1 or 2 (if raptor_uri_compare_func is implemented).

`handler` :

  URI handler structure

`context` :

  URI handler context

### raptor_uri_get_handler ()

    void                raptor_uri_get_handler              (const raptor_uri_handler **handler,
                                                             void **context);

Return the current raptor URI class implementation `handler` and `context`

`handler` :

  URI handler to return

`context` :

  URI context to return

### raptor_iostream_write_uri ()

    int                 raptor_iostream_write_uri           (raptor_iostream *iostr,
                                                             raptor_uri *uri);

Write a raptor URI to the iostream.

`iostr` :

  raptor iostream

`uri` :

  URI

Returns :

  non-0 on failure