ide-uri: Builder SDK Reference

## ide-uri ide-uri |

## Functions

IdeUri * | ide_uri_new ()
IdeUri * | ide_uri_new_relative ()
IdeUri * | ide_uri_new_from_file ()
char * | ide_uri_to_string ()
IdeUri * | ide_uri_copy ()
IdeUri * | ide_uri_ref ()
void | ide_uri_unref ()
const gchar * | ide_uri_get_scheme ()
void | ide_uri_set_scheme ()
const gchar * | ide_uri_get_user ()
void | ide_uri_set_user ()
const gchar * | ide_uri_get_password ()
void | ide_uri_set_password ()
const gchar * | ide_uri_get_auth_params ()
void | ide_uri_set_auth_params ()
const gchar * | ide_uri_get_host ()
void | ide_uri_set_host ()
gushort | ide_uri_get_port ()
void | ide_uri_set_port ()
const gchar * | ide_uri_get_path ()
void | ide_uri_set_path ()
const gchar * | ide_uri_get_query ()
void | ide_uri_set_query ()
const gchar * | ide_uri_get_fragment ()
void | ide_uri_set_fragment ()
void | ide_uri_split ()
GHashTable * | ide_uri_parse_params ()
gboolean | ide_uri_parse_host ()
gchar * | ide_uri_build ()
gboolean | ide_uri_is_file ()
GFile * | ide_uri_to_file ()
GQuark | ide_uri_error_quark ()

## Types and Values

enum | IdeUriParseFlags
enum | IdeUriToStringFlags
#define | IDE_URI_ERROR
enum | IdeUriError

## Object Hierarchy

        GBoxed
        ╰── IdeUri

## Description

## Functions

### ide_uri_new ()

    IdeUri *
    ide_uri_new (const gchar *uri_string,
                 IdeUriParseFlags flags,
                 GError **error);

Parses `uri_string` according to `flags` . If the result is not a valid absolute URI, it will be discarded, and an error returned.

#### Parameters

uri_string | a string representing an absolute URI |
flags | flags describing how to parse `uri_string` |
error | GError for error reporting, or `NULL` to ignore. |

#### Returns

a new IdeUri.

### ide_uri_new_relative ()

    IdeUri *
    ide_uri_new_relative (IdeUri *base_uri,
                          const gchar *uri_string,
                          IdeUriParseFlags flags,
                          GError **error);

Parses `uri_string` according to `flags` and, if it is a relative URI, merges it with `base_uri` . If the result is not a valid absolute URI, it will be discarded, and an error returned.

#### Parameters

base_uri | a base URI. | [allow-none]
uri_string | a string representing a relative or absolute URI |
flags | flags describing how to parse `uri_string` |
error | GError for error reporting, or `NULL` to ignore. |

#### Returns

a new IdeUri.

### ide_uri_new_from_file ()

    IdeUri *
    ide_uri_new_from_file (GFile *file);

Creates a new IdeUri from the uri provided by `file` .

#### Parameters

file | a GFile. |

#### Returns

A newly allcoated IdeUri.

[transfer full]

### ide_uri_to_string ()

    char *
    ide_uri_to_string (IdeUri *uri,
                       IdeUriToStringFlags flags);

Returns a string representing `uri` .

#### Parameters

uri | a IdeUri |
flags | flags describing how to convert `uri` |

#### Returns

a string representing `uri` , which the caller must free.

### ide_uri_copy ()

    IdeUri *
    ide_uri_copy (IdeUri *uri);

Copies `uri`

#### Parameters

uri | a IdeUri |

#### Returns

a copy of `uri`

### ide_uri_ref ()

    IdeUri *
    ide_uri_ref (IdeUri *uri);

Increments the reference count of `uri` by one.

#### Parameters

uri | An IdeUri |

#### Returns

uri.

[transfer full]

### ide_uri_unref ()

    void
    ide_uri_unref (IdeUri *uri);

Decrements the reference count of `uri` by 1. If the reference count reaches zero, the structure will be freed.

#### Parameters

uri | a IdeUri |

### ide_uri_get_scheme ()

    const gchar *
    ide_uri_get_scheme (IdeUri *uri);

Gets `uri` 's scheme.

#### Parameters

uri | a IdeUri |

#### Returns

`uri` 's scheme.

### ide_uri_set_scheme ()

    void
    ide_uri_set_scheme (IdeUri *uri,
                        const gchar *scheme);

Sets `uri` 's scheme to `scheme` .

#### Parameters

uri | a IdeUri |
scheme | the URI scheme |

### ide_uri_get_user ()

    const gchar *
    ide_uri_get_user (IdeUri *uri);

Gets `uri` 's user. If `uri` was parsed with `IDE_URI_PARSE_PASSWORD` or `IDE_URI_PARSE_AUTH_PARAMS`, this is the string that appears before the password and parameters in the userinfo. If not, then the entire userinfo is considered the user.

#### Parameters

uri | a IdeUri |

#### Returns

`uri` 's user.

### ide_uri_set_user ()

    void
    ide_uri_set_user (IdeUri *uri,
                      const gchar *user);

Sets `uri` 's user to `user` . See `ide_uri_get_user()` for a description of how this interacts with various parsing flags.

#### Parameters

uri | a IdeUri |
user | the username, or `NULL` |

### ide_uri_get_password ()

    const gchar *
    ide_uri_get_password (IdeUri *uri);

Gets `uri` 's password. If `uri` was not parsed with `IDE_URI_PARSE_PASSWORD`, this will always be `NULL`.

#### Parameters

uri | a IdeUri |

#### Returns

`uri` 's password.

### ide_uri_set_password ()

    void
    ide_uri_set_password (IdeUri *uri,
                          const gchar *password);

Sets `uri` 's password to `password` .

#### Parameters

uri | a IdeUri |
password | the password, or `NULL` |

### ide_uri_get_auth_params ()

    const gchar *
    ide_uri_get_auth_params (IdeUri *uri);

Gets `uri` 's authentication parameters. Depending on the URI scheme, `ide_uri_parse_params()` may be useful for further parsing this information.

#### Parameters

uri | a IdeUri |

#### Returns

`uri` 's authentication parameters.

### ide_uri_set_auth_params ()

    void
    ide_uri_set_auth_params (IdeUri *uri,
                             const gchar *auth_params);

Sets `uri` 's authentication parameters to `auth_params` .

#### Parameters

uri | a IdeUri |
auth_params | the authentication parameters, or `NULL` |

### ide_uri_get_host ()

    const gchar *
    ide_uri_get_host (IdeUri *uri);

Gets `uri` 's host. If `uri` contained an IPv6 address literal, this value will not include the brackets that are required by the URI syntax.

#### Parameters

uri | a IdeUri |

#### Returns

`uri` 's host.

### ide_uri_set_host ()

    void
    ide_uri_set_host (IdeUri *uri,
                      const gchar *host);

Sets `uri` 's host to `host` .

If `host` is an IPv6 IP address, it should not include the brackets required by the URI syntax; they will be added automatically when converting `uri` to a string.

#### Parameters

uri | a IdeUri |
host | the hostname or IP address, or `NULL` |

### ide_uri_get_port ()

    gushort
    ide_uri_get_port (IdeUri *uri);

Gets `uri` 's port.

#### Parameters

uri | a IdeUri |

#### Returns

`uri` 's port, or `0` if it was unset

### ide_uri_set_port ()

    void
    ide_uri_set_port (IdeUri *uri,
                      gushort port);

Sets `uri` 's port to `port` . If `port` is 0, it will not be output when calling `ide_uri_to_string()`.

#### Parameters

uri | a IdeUri |
port | the port, or `0` |

### ide_uri_get_path ()

    const gchar *
    ide_uri_get_path (IdeUri *uri);

Gets `uri` 's path, which may contain %-encoding, depending on the flags with which `uri` was parsed.

#### Parameters

uri | a IdeUri |

#### Returns

`uri` 's path.

### ide_uri_set_path ()

    void
    ide_uri_set_path (IdeUri *uri,
                      const gchar *path);

Sets `uri` 's path to `path` , which is assumed to have been appropriately %-encoded. In particular, this means that if you want to include a literal percent sign the path, you must write it as "%25". That being said, if `path` contains an unencoded '?' or '#' character, it will get encoded, since otherwise converting `uri` to a string and then back to a IdeUri again would give a different result.

#### Parameters

uri | a IdeUri |
path | the (%-encoded) path |

### ide_uri_get_query ()

    const gchar *
    ide_uri_get_query (IdeUri *uri);

Gets `uri` 's query, which may contain %-encoding, depending on the flags with which `uri` was parsed.

For queries consisting of a series of "name=value" parameters, `ide_uri_parse_params()` may be useful.

#### Parameters

uri | a IdeUri |

#### Returns

`uri` 's query.

### ide_uri_set_query ()

    void
    ide_uri_set_query (IdeUri *uri,
                       const gchar *query);

Sets `uri` 's query to `query` , which is assumed to have been %-encoded by the caller. See `ide_uri_set_path()` for more details.

#### Parameters

uri | a IdeUri |
query | the (%-encoded) query |

### ide_uri_get_fragment ()

    const gchar *
    ide_uri_get_fragment (IdeUri *uri);

Gets `uri` 's fragment, which may contain %-encoding, depending on the flags with which `uri` was parsed.

#### Parameters

uri | a IdeUri |

#### Returns

`uri` 's fragment.

### ide_uri_set_fragment ()

    void
    ide_uri_set_fragment (IdeUri *uri,
                          const gchar *fragment);

Sets `uri` 's fragment to `fragment` , which is assumed to have been %-encoded by the caller. See `ide_uri_set_path()` for more details.

#### Parameters

uri | a IdeUri |
fragment | the (%-encoded) fragment |

### ide_uri_split ()

    void
    ide_uri_split (const gchar *uri_string,
                   gboolean strict,
                   gchar **scheme,
                   gchar **userinfo,
                   gchar **host,
                   gchar **port,
                   gchar **path,
                   gchar **query,
                   gchar **fragment);

Parses `uri_string` more-or-less according to the generic grammar of RFC 3986 ("more" if `strict` is `TRUE`, "less" if `FALSE`), and outputs the pieces into the provided variables. This is a low-level method that does not do any pre- or post-processing of `uri_string` , and is "garbage in, garbage out"; it just splits `uri_string` into pieces at the appropriate punctuation characters (consuming delimiters as appropriate), and returns the pieces. Components that are not present in `uri_string` will be set to `NULL` (but note that the path is always present, though it may be an empty string).

#### Parameters

uri_string | a string containing a relative or absolute URI |
strict | whether to parse `uri_string` strictly |
scheme | on return, contains the scheme, or `NULL`. | [out][nullable]
userinfo | on return, contains the userinfo, or `NULL`. | [out][nullable]
host | on return, contains the host, or `NULL`. | [out][nullable]
port | on return, contains the port, or `NULL`. | [out][nullable]
path | on return, contains the path, or `NULL`. | [out][nullable]
query | on return, contains the query, or `NULL`. | [out][nullable]
fragment | on return, contains the fragment, or `NULL`. | [out][nullable]

### ide_uri_parse_params ()

    GHashTable *
    ide_uri_parse_params (const gchar *params,
                          gssize length,
                          gchar separator,
                          gboolean case_insensitive);

Many URI schemes include one or more attribute/value pairs as part of the URI value. This method can be used to parse them into a hash table.

The `params` string is assumed to still be %-encoded, but the returned values will be fully decoded. (Thus it is possible that the returned values may contain '=' or `separator` , if the value was encoded in the input.) Invalid %-encoding is treated as with the non-`IDE_URI_PARSE_STRICT` rules for `ide_uri_new()`. (However, if `params` is the path or query string from a IdeUri that was parsed with `IDE_URI_PARSE_STRICT`, then you already know that it does not contain any invalid encoding.)

#### Parameters

params | a string containing "attribute=value" parameters |
length | the length of `params` , or -1 if it is NUL-terminated |
separator | the separator character between parameters. (usually ';', but sometimes '&') |
case_insensitive | whether to match parameter names case-insensitively |

#### Returns

a hash table of attribute/value pairs. Both names and values will be fully-decoded. If `params` cannot be parsed (eg, it contains two `separator` characters in a row), then `NULL` is returned.

[element-type utf8 utf8][transfer container]

### ide_uri_parse_host ()

    gboolean
    ide_uri_parse_host (const gchar *uri_string,
                        IdeUriParseFlags flags,
                        gchar **scheme,
                        gchar **host,
                        gushort *port,
                        GError **error);

Utility function for parsing "network" URIs. This extracts just the scheme, host, and port from `uri_string` . All three out parameters are mandatory.

#### Parameters

uri_string | a string containing a network URI |
flags | flags for parsing `uri_string` |
scheme | on return, will contain `uri_string` 's URI scheme. | [out]
host | on return, will contain `uri_string` 's decoded hostname. | [out]
port | on return, will contain `uri_string` 's port, or `0`. | [out]
error | GError for error reporting, or `NULL` to ignore. |

#### Returns

`TRUE` on success, `FALSE` on failure.

### ide_uri_build ()

    gchar *
    ide_uri_build (const gchar *scheme,
                   const gchar *userinfo,
                   const gchar *host,
                   const gchar *port,
                   const gchar *path,
                   const gchar *query,
                   const gchar *fragment);

### ide_uri_is_file ()

    gboolean
    ide_uri_is_file (IdeUri *uri,
                     GFile *file);

### ide_uri_to_file ()

    GFile *
    ide_uri_to_file (IdeUri *uri);

Creates a GFile that represents the resource `uri` .

#### Parameters

uri | An IdeUri |

#### Returns

a GFile or `NULL` upon failure.

[transfer full][nullable]

### ide_uri_error_quark ()

    GQuark
    ide_uri_error_quark (void);

## Types and Values

### enum IdeUriParseFlags

Flags that control how a URI string is parsed (or re-parsed).

#### Members

IDE_URI_PARSE_STRICT | Parse the URI strictly according to the RFC 3986 grammar. |
IDE_URI_PARSE_HTML5 | Parse the URI according to the HTML5 web address parsing rules. |
IDE_URI_PARSE_NO_IRI | Disallow Internationalized URIs; return an error if the URI contains non-ASCII characters |
IDE_URI_PARSE_PASSWORD | Split the userinfo into user and password, separated by ':'. |
IDE_URI_PARSE_AUTH_PARAMS | Split the userinfo into user/password and parameters, separated by ';'. |
IDE_URI_PARSE_NON_DNS | Do not parse the host as a DNS host/IP address. (Eg, for smb URIs with NetBIOS hostnames). |
IDE_URI_PARSE_DECODED | Decode even reserved %encoded characters in the URI (unless this would result in non-UTF8 strings). Using this flag means that you cannot reliably convert the parsed URI back to string form with `ide_uri_to_string()`. |
IDE_URI_PARSE_UTF8_ONLY | Return an error if non-UTF8 characters are encountered in the URI. |

### enum IdeUriToStringFlags

#### Members

IDE_URI_HIDE_AUTH_PARAMS |  |
IDE_URI_HIDE_FRAGMENT |  |

### IDE_URI_ERROR

    #define IDE_URI_ERROR (ide_uri_error_quark ())

Error domain for URI methods. Errors in this domain will be from the IdeUriError enumeration. See GError for information on error domains.

### enum IdeUriError

Error codes returned by IdeUri methods.

#### Members

IDE_URI_ERROR_MISC |  |
IDE_URI_ERROR_BAD_SCHEME |  |
IDE_URI_ERROR_BAD_USER |  |
IDE_URI_ERROR_BAD_PASSWORD |  |
IDE_URI_ERROR_BAD_AUTH_PARAMS |  |
IDE_URI_ERROR_BAD_HOST |  |
IDE_URI_ERROR_BAD_PORT |  |
IDE_URI_ERROR_BAD_PATH |  |
IDE_URI_ERROR_BAD_QUERY |  |
IDE_URI_ERROR_BAD_FRAGMENT |  |