Uri conversion

Files
file	gnc-uri-utils.h
	Utility functions for convert uri in separate components and back.

Macros
#define	GNC_DATAFILE_EXT   ".gnucash"
#define	GNC_LOGFILE_EXT   ".log"

Functions
gboolean	gnc_uri_is_uri (const gchar *uri)
	Checks if the given uri is a valid uri. More...
void	gnc_uri_get_components (const gchar *uri, gchar **scheme, gchar **hostname, gint32 *port, gchar **username, gchar **password, gchar **path)
	Converts a uri in separate components. More...
gchar *	gnc_uri_get_scheme (const gchar *uri)
	Extracts the scheme from a uri. More...
gchar *	gnc_uri_get_path (const gchar *uri)
	Extracts the path part from a uri. More...
gchar *	gnc_uri_create_uri (const gchar *scheme, const gchar *hostname, gint32 port, const gchar *username, const gchar *password, const gchar *path)
	Composes a normalized uri starting from its separate components. More...
gchar *	gnc_uri_normalize_uri (const gchar *uri, gboolean allow_password)
	Composes a normalized uri starting from any uri (filename, db spec,...). More...
gboolean	gnc_uri_is_known_scheme (const gchar *scheme)
	Checks if there is a backend that explicitly stated to handle the given scheme. More...
gboolean	gnc_uri_is_file_scheme (const gchar *scheme)
	Checks if the given scheme is used to refer to a file (as opposed to a network service like a database or web url) More...
gboolean	gnc_uri_is_file_uri (const gchar *uri)
	Checks if the given uri defines a file (as opposed to a network service like a database or web url) More...
gboolean	gnc_uri_targets_local_fs (const gchar *uri)
	Checks if the given uri is either a valid file uri or a local filesystem path. More...
gchar *	gnc_uri_add_extension (const gchar *uri, const gchar *extension)
	Adds an extension to the uri if: More...

Deprecated functions
gchar *	gnc_uri_get_protocol (const gchar *uri) GNC_DEPRECATED("Please use gnc_uri_get_scheme instead (since 3.4)")
	Extracts the protocol from a uri. More...
gboolean	gnc_uri_is_known_protocol (const gchar *protocol) GNC_DEPRECATED("Please use gnc_uri_known_scheme instead (since 3.4)")
	Checks if there is a backend that explicitly stated to handle the given protocol. More...
gboolean	gnc_uri_is_file_protocol (const gchar *protocol) GNC_DEPRECATED("Please use gnc_uri_is_file_scheme instead (since 3.4)")
	Checks if the given protocol is used to refer to a file (as opposed to a network service like a database or web url) More...

Detailed Description

Function Documentation

gnc_uri_add_extension()

gchar* gnc_uri_add_extension	(	const gchar *	uri,
		const gchar *	extension
	)

Adds an extension to the uri if:

• the uri is not empty and file based
• doesn't already have the extension

Parameters

uri	The uri to process
extension	The extension to add if missing. Note that the extension is added verbatim, so if a dot should be added, this should be part of the extension.

Returns

The uri, but guaranteed to end with extension if the uri is file based. Otherwise the uri is returned unmodified. Note that the returned value should be freed with g_free when no longer needed.

Definition at line 413 of file gnc-uri-utils.c.

{
    g_return_val_if_fail( uri != 0, NULL );

    /* Only add extension if the user provided the extension and the uri is
     * file based.
     */
    if ( !extension || !gnc_uri_is_file_uri( uri ) )
        return g_strdup( uri );

    /* Don't add extension if it's already there */
    if ( g_str_has_suffix( uri, extension ) )
        return g_strdup( uri );

    /* Ok, all tests passed, let's add the extension */
    return g_strconcat( uri, extension, NULL );
}

gnc_uri_create_uri()

gchar* gnc_uri_create_uri	(	const gchar *	scheme,
		const gchar *	hostname,
		gint32	port,
		const gchar *	username,
		const gchar *	password,
		const gchar *	path
	)

Composes a normalized uri starting from its separate components.

The resulting uri will take either of these forms:

• file:///some/absolute/path (file could also be xml or sqlite)
• file://c:\some\windows\path (file could also be xml or sqlite)
• scheme://[user[:password]@]hostname[:port]/path

Only the components that are provided will be inserted in the uri. However if no scheme has been provided, 'file' will be used as default scheme.

The function allocates memory for the uri. The calling function should free this memory with g_free the uri is no longer needed.

Parameters

scheme	The scheme for this uri. If NULL,, 'file' will be used in the uri.
hostname	The host name of the server to connect to. This will be ignored for the 'file' type schemes ('file', 'xml', 'sqlite').
port	An optional port to set o, the uri, or 0 if no port is to be set. This will be ignored for the 'file' type schemes ('file', 'xml', 'sqlite').
username	Optional user name to set in the uri or NULL otherwise. This will be ignored for the 'file' type schemes ('file', 'xml', 'sqlite').
password	Optional password to set in the uri or NULL otherwise. This will be ignored for the 'file' type schemes ('file', 'xml', 'sqlite').
path	The path to set in the uri.

Returns

The normalized uri.

Definition at line 297 of file gnc-uri-utils.c.

{
    gchar *userpass = NULL, *portstr = NULL, *uri = NULL;

    g_return_val_if_fail( path != 0, NULL );

    if (!scheme || gnc_uri_is_file_scheme (scheme))
    {
        /* Compose a file based uri, which means ignore everything but
         * the scheme and the path
         * We return an absolute pathname if the scheme is known or
         * no scheme was given. For an unknown scheme, we return the
         * path info as is.
         */
        gchar *abs_path;
        gchar *uri_scheme;
        if (scheme && (!gnc_uri_is_known_scheme (scheme)) )
            abs_path = g_strdup ( path );
        else
            abs_path = gnc_resolve_file_path ( path );

        if (!scheme)
            uri_scheme = g_strdup ("file");
        else
            uri_scheme = g_strdup (scheme);

        /* Arrive here with...
         *
         * /my/path/to/file with space.txt
         * becomes file:///my/path/to/file with space.txt
         *
         * c:\my\path\to\file with space.txt
         * becomes file:///c:\my\path\to\file with space.txt
         *
         * \\myserver\share\path\to\file with space.txt
         * becomes file://\\myserver\share\path\to\file with space.txt
         *
         * probably they should all be forward slashes and spaces escaped
         * also with UNC it could be file://myserver/share/path/to/file with space.txt
         */

        if (g_str_has_prefix (abs_path, "/") || g_str_has_prefix (abs_path, "\\"))
            uri = g_strdup_printf ( "%s://%s", uri_scheme, abs_path );
        else // for windows add an extra "/"
            uri = g_strdup_printf ( "%s:///%s", uri_scheme, abs_path );

        g_free (uri_scheme);
        g_free (abs_path);

        return uri;
    }

    /* Not a file based uri, we need to setup all components that are not NULL
     * For this scenario, hostname is mandatory.
     */
    g_return_val_if_fail( hostname != 0, NULL );

    if ( username != NULL && *username )
    {
        if ( password != NULL && *password )
            userpass = g_strdup_printf ( "%s:%s@", username, password );
        else
            userpass = g_strdup_printf ( "%s@", username );
    }
    else
        userpass = g_strdup ( "" );

    if ( port != 0 )
        portstr = g_strdup_printf ( ":%d", port );
    else
        portstr = g_strdup ( "" );

    // XXX Do I have to add the slash always or are there situations
    //     it is in the path already ?
    uri = g_strconcat ( scheme, "://", userpass, hostname, portstr, "/", path, NULL );

    g_free ( userpass );
    g_free ( portstr );

    return uri;

}

gnc_uri_get_components()

void gnc_uri_get_components	(	const gchar *	uri,
		gchar **	scheme,
		gchar **	hostname,
		gint32 *	port,
		gchar **	username,
		gchar **	password,
		gchar **	path
	)

Converts a uri in separate components.

The function allocates memory for each of the components that it finds in the uri. The calling function should free this memory with g_free when the items are no longer needed.

Parameters

uri	The uri to convert
scheme	The scheme for this uri. If the uri doesn't have an explicit scheme, NULL will be returned.
hostname	The host name of the server to connect to. In case of the local file system path, NULL will be returned
port	An optional port to connect to or 0 if the default port is to be used. For local filesystem path this is always 0 as well.
username	Optional user name found in this uri or NULL if none is found.
password	Optional password found in this uri or NULL if none is found.
path	The path found in this uri.

Definition at line 143 of file gnc-uri-utils.c.

{
    gchar **splituri;
    gchar *url = NULL, *tmpusername = NULL, *tmphostname = NULL;
    gchar *delimiter = NULL;

    *scheme   = NULL;
    *hostname = NULL;
    *port     = 0;
    *username = NULL;
    *password = NULL;
    *path     = NULL;

    g_return_if_fail( uri != NULL && strlen (uri) > 0);

    splituri = g_strsplit ( uri, "://", 2 );
    if ( splituri[1] == NULL )
    {
        /* No scheme means simple file path.
           Set path to copy of the input. */
        *path     = g_strdup ( uri );
        g_strfreev ( splituri );
        return;
    }

    /* At least a scheme was found, set it here */
    *scheme = g_strdup ( splituri[0] );

    if ( gnc_uri_is_file_scheme ( *scheme ) )
    {
        /* a true file uri on windows can start file:///N:/
           so we come here with /N:/, it could also be /N:\
        */
        if (g_str_has_prefix (splituri[1], "/") &&
           ((g_strstr_len (splituri[1], -1,  ":/") != NULL) || (g_strstr_len (splituri[1], -1,  ":\\") != NULL)))
        {
            gchar *ptr = splituri[1];
            *path = gnc_resolve_file_path ( ptr + 1 );
        }
        else
            *path = gnc_resolve_file_path ( splituri[1] );
        g_strfreev ( splituri );
        return;
    }

    /* Protocol indicates full network style uri, let's see if it
     * has a username and/or password
     */
    url = g_strdup (splituri[1]);
    g_strfreev ( splituri );

    /* Check for "@" sign, but start from the end - the password may contain
     * this sign as well
     */
    delimiter = g_strrstr ( url, "@" );
    if ( delimiter != NULL )
    {
        /* There is at least a username in the url */
        delimiter[0] = '\0';
        tmpusername = url;
        tmphostname = delimiter + 1;

        /* Check if there's a password too by looking for a :
         * Start from the beginning this time to avoid possible :
         * in the password */
        delimiter = g_strstr_len ( tmpusername, -1, ":" );
        if ( delimiter != NULL )
        {
            /* There is password in the url */
            delimiter[0] = '\0';
            *password = g_strdup ( (const gchar*)(delimiter + 1) );
        }
        *username = g_strdup ( (const gchar*)tmpusername );
    }
    else
    {
        /* No username and password were given */
        tmphostname = url;
    }

    /* Find the path part */
    delimiter = g_strstr_len ( tmphostname, -1, "/" );
    if ( delimiter != NULL )
    {
        delimiter[0] = '\0';
        if ( gnc_uri_is_file_scheme ( *scheme ) ) /* always return absolute file paths */
            *path = gnc_resolve_file_path ( (const gchar*)(delimiter + 1) );
        else /* path is no file path, so copy it as is */
            *path = g_strdup ( (const gchar*)(delimiter + 1) );
    }

    /* Check for a port specifier */
    delimiter = g_strstr_len ( tmphostname, -1, ":" );
    if ( delimiter != NULL )
    {
        delimiter[0] = '\0';
        *port = g_ascii_strtoll ( delimiter + 1, NULL, 0 );
    }

    *hostname = g_strdup ( (const gchar*)tmphostname );

    g_free ( url );

    return;

}

gnc_uri_get_path()

gchar* gnc_uri_get_path

(

const gchar *

uri

)

Extracts the path part from a uri.

The function allocates memory for the path. The calling function should free this memory with g_free if it no longer needs the string.

Parameters

uri	The uri to extract the path part from

Returns

The path for this uri, or NULL if no path could be extracted.

Definition at line 276 of file gnc-uri-utils.c.

{
    gchar *scheme   = NULL;
    gchar *hostname = NULL;
    gint32 port = 0;
    gchar *username = NULL;
    gchar *password = NULL;
    gchar *path     = NULL;

    gnc_uri_get_components ( uri, &scheme, &hostname, &port,
                             &username, &password, &path );

    g_free (scheme);
    g_free (hostname);
    g_free (username);
    g_free (password);

    return path;
}

gnc_uri_get_protocol()

gchar* gnc_uri_get_protocol

(

const gchar *

uri

)

Extracts the protocol from a uri.

Deprecated:

This function has been deprecated in gnucash 3.4. Please use gnc_uri_get_scheme instead.

The function allocates memory for the protocol. The calling function should free this memory with g_free if it no longer needs the string.

Parameters

uri	The uri to extract the protocol from

Returns

The protocol for this uri. If the uri didn't have an explicit protocol, NULL will be returned.

Definition at line 436 of file gnc-uri-utils.c.

{
    return gnc_uri_get_scheme (uri);
}

gnc_uri_get_scheme()

gchar* gnc_uri_get_scheme

(

const gchar *

uri

)

Extracts the scheme from a uri.

The function allocates memory for the scheme. The calling function should free this memory with g_free if it no longer needs the string.

Parameters

uri	The uri to extract the scheme from

Returns

The scheme for this uri. If the uri didn't have an explicit scheme, NULL will be returned.

Definition at line 256 of file gnc-uri-utils.c.

{
    gchar *scheme   = NULL;
    gchar *hostname = NULL;
    gint32 port     = 0;
    gchar *username = NULL;
    gchar *password = NULL;
    gchar *path     = NULL;

    gnc_uri_get_components ( uri, &scheme, &hostname, &port,
                             &username, &password, &path );

    g_free (hostname);
    g_free (username);
    g_free (password);
    g_free (path);

    return scheme;
}

gnc_uri_is_file_protocol()

gboolean gnc_uri_is_file_protocol

(

const gchar *

protocol

)

Checks if the given protocol is used to refer to a file (as opposed to a network service like a database or web url)

Deprecated:

This function has been deprecated in gnucash 3.4. Please use gnc_uri_is_file_scheme instead.

Parameters

protocol

The protocol to check

Returns

TRUE if the protocol is used with files, FALSE of the protocol is normally used with network services (database, web url,...)

Definition at line 448 of file gnc-uri-utils.c.

{
    return gnc_uri_is_file_scheme (protocol);
}

gnc_uri_is_file_scheme()

gboolean gnc_uri_is_file_scheme

(

const gchar *

scheme

)

Checks if the given scheme is used to refer to a file (as opposed to a network service like a database or web url)

Parameters

scheme

The scheme to check

Returns

TRUE if the scheme is used with files, FALSE if the scheme is normally used with network services (database, web url,...). It will also return FALSE if scheme is NULL.

Definition at line 90 of file gnc-uri-utils.c.

{
    return (scheme &&
            (!g_ascii_strcasecmp (scheme, "file") ||
             !g_ascii_strcasecmp (scheme, "xml") ||
             !g_ascii_strcasecmp (scheme, "sqlite3")));
}

gnc_uri_is_file_uri()

gboolean gnc_uri_is_file_uri

(

const gchar *

uri

)

Checks if the given uri defines a file (as opposed to a network service like a database or web url)

Parameters

uri	The uri to check

Returns

TRUE if the uri is a files, FALSE of the scheme is normally used with network services (database, web url,...)

Definition at line 101 of file gnc-uri-utils.c.

{
    gchar *scheme = gnc_uri_get_scheme ( uri );
    gboolean result = gnc_uri_is_file_scheme ( scheme );

    g_free ( scheme );

    return result;
}

gnc_uri_is_known_protocol()

gboolean gnc_uri_is_known_protocol

(

const gchar *

protocol

)

Checks if there is a backend that explicitly stated to handle the given protocol.

Deprecated:

This function has been deprecated in gnucash 3.4. Please use gnc_uri_is_known_scheme instead.

Parameters

protocol

The protocol to check

Returns

TRUE if at least one backend explicitly handles this protocol, otherwise FALSE

Definition at line 442 of file gnc-uri-utils.c.

{
    return gnc_uri_is_known_scheme(protocol);
}

gnc_uri_is_known_scheme()

gboolean gnc_uri_is_known_scheme

(

const gchar *

scheme

)

Checks if there is a backend that explicitly stated to handle the given scheme.

Parameters

scheme

The scheme to check

Returns

TRUE if at least one backend explicitly handles this scheme, otherwise FALSE

Definition at line 61 of file gnc-uri-utils.c.

{
    gboolean is_known_scheme = FALSE;
    GList *node;
    GList *known_scheme_list = qof_backend_get_registered_access_method_list();

    for ( node = known_scheme_list; node != NULL; node = node->next )
    {
        gchar *known_scheme = node->data;
        if ( !g_ascii_strcasecmp (scheme, known_scheme) )
        {
            is_known_scheme = TRUE;
            break;
        }
    }

    g_list_free (known_scheme_list);
    return is_known_scheme;
}

gnc_uri_is_uri()

gboolean gnc_uri_is_uri

(

const gchar *

uri

)

Checks if the given uri is a valid uri.

A valid uri is defined by having at least a scheme and a path. If the uri is not referring to a file on the local file system a hostname should be set as well.

Parameters

uri	The uri to check

Returns

TRUE if the input is a valid uri, FALSE otherwise

Definition at line 32 of file gnc-uri-utils.c.

{

    gchar *scheme = NULL, *hostname = NULL;
    gchar *username = NULL, *password = NULL;
    gchar *path     = NULL;
    gint   port = 0;
    gboolean is_uri = FALSE;

    gnc_uri_get_components ( uri, &scheme, &hostname, &port,
                             &username, &password, &path );

    /* For gnucash to consider a uri valid the following must be true:
     * - scheme and path must not be NULL
     * - for anything but local filesystem uris, hostname must be valid as well */
    is_uri = (scheme && path && (gnc_uri_is_file_scheme(scheme) || hostname));

    g_free (scheme);
    g_free (hostname);
    g_free (username);
    g_free (password);
    g_free (path);

    return is_uri;
}

gnc_uri_normalize_uri()

gchar* gnc_uri_normalize_uri	(	const gchar *	uri,
		gboolean	allow_password
	)

Composes a normalized uri starting from any uri (filename, db spec,...).

The resulting uri will take either of these forms:

• file:///some/absolute/path ('file' can also be xml or sqlite)
• file://c:\some\windows\path ('file' can also be xml or sqlite)
• scheme://[user[:password]@]hostname[:port]/path

Only the components that are provided will be inserted in the uri. The allow_password parameter controls if the password should be added to the returned uri when available. If no scheme has been provided, 'file' will be used as default scheme.

The function allocates memory for the uri. The calling function should free this memory with g_free the uri is no longer needed.

Parameters

uri	The uri that should be converted into a normalized uri
allow_password	If set to TRUE, the normalized uri and the input uri has a password, this passworld will also be set in the normalized uri. Otherwise no password will be set in the normalized uri.

Returns

The normalized uri.

Definition at line 385 of file gnc-uri-utils.c.

{
    gchar *scheme   = NULL;
    gchar *hostname = NULL;
    gint32 port = 0;
    gchar *username = NULL;
    gchar *password = NULL;
    gchar *path     = NULL;
    gchar *newuri   = NULL;

    gnc_uri_get_components ( uri, &scheme, &hostname, &port,
                             &username, &password, &path );
    if (allow_password)
        newuri = gnc_uri_create_uri ( scheme, hostname, port,
                                      username, password, path);
    else
        newuri = gnc_uri_create_uri ( scheme, hostname, port,
                                      username, /* no password */ NULL, path);

    g_free (scheme);
    g_free (hostname);
    g_free (username);
    g_free (password);
    g_free (path);

    return newuri;
}

gnc_uri_targets_local_fs()

gboolean gnc_uri_targets_local_fs

(

const gchar *

uri

)

Checks if the given uri is either a valid file uri or a local filesystem path.

A valid file uri is defined by having a file targeting scheme ('file', 'xml' or 'sqlite3' are accepted) and a non-NULL path.

Parameters

uri	The uri to check

Returns

TRUE if the input is a valid file uri or a local filesystem path. FALSE otherwise

Definition at line 113 of file gnc-uri-utils.c.

{

    gchar *scheme = NULL, *hostname = NULL;
    gchar *username = NULL, *password = NULL;
    gchar *path     = NULL;
    gint   port = 0;
    gboolean is_local_fs = FALSE;

    gnc_uri_get_components ( uri, &scheme, &hostname, &port,
                             &username, &password, &path );

    /* For gnucash to consider a uri to target the local fs:
     * path must not be NULL
     * AND
     *   scheme should be NULL
     *   OR
     *   scheme must be file type scheme (file, xml, sqlite) */
    is_local_fs = (path && (!scheme || gnc_uri_is_file_scheme(scheme)));

    g_free (scheme);
    g_free (hostname);
    g_free (username);
    g_free (password);
    g_free (path);

    return is_local_fs;
}