mirror of
https://github.com/Gnucash/gnucash.git
synced 2024-11-26 02:40:43 -06:00
4b398325ea
- gnc_uri_get_components will now return NULL as protocol if the input is a normal file system path instead of a uri (it used to return 'file') - gnc_uri_get_protocol will now return NULL if the input is a normal file system path instead of a uri (it used to return 'file') - gnc_uri_is_file_protocol now returns FALSE if protocol is NULL (it used to return TRUE) - gnc_uri_is_file_uri now returns FALSE if input is a normal file system path instead of a uri (it used to return TRUE) - a new function gnc_uri_targets_local_fs will return TRUE only if its input is either a file uri or a normal file system path. This function is now mostly used instead of gnc_uri_is_file_uri in the current code base - a new function gnc_uri_is_uri is added to check whether its input is a valid uri (has protocol, path and hostname for non-file uris)
264 lines
10 KiB
C
264 lines
10 KiB
C
/*
|
|
* gnc-uri-utils.h -- utility functions to convert uri in separate
|
|
* components and back.
|
|
*
|
|
* Copyright (C) 2010 Geert Janssens <janssens.geert@telenet.be>
|
|
*
|
|
* This program is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU General Public License as
|
|
* published by the Free Software Foundation; either version 2 of
|
|
* the License, or (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, contact:
|
|
*
|
|
* Free Software Foundation Voice: +1-617-542-5942
|
|
* 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652
|
|
* Boston, MA 02110-1301, USA gnu@gnu.org
|
|
*/
|
|
|
|
/** @addtogroup Utils Utility functions
|
|
@{ */
|
|
/** @addtogroup UtilUri Uri conversion
|
|
* @{ */
|
|
/** @file gnc-uri-utils.h
|
|
* @brief Utility functions for convert uri in separate components and back
|
|
* @author Copyright (C) 2010 Geert Janssens <janssens-geert@telenet.be>
|
|
*
|
|
* These functions help you convert a uri into its separate components
|
|
* (being protocol, host name, port, user name, password and path) or
|
|
* to compose a uri from these separate components.
|
|
*
|
|
* A full uri can be described as:
|
|
*
|
|
* @li @c proto://[[username[:password]@]hostname[:port]]/path (universal uri)
|
|
* @li @c file://[localhost]/path (uri refering to a file on the local file system)
|
|
*
|
|
* Anything in square brackets is optional.
|
|
*
|
|
* While not strictly uris this function will also accept input in the form
|
|
* of a local file system path for convenience:
|
|
*
|
|
* @li @c some/filesystem/path A simple relative file system path (unix style)
|
|
* @li @c /some/filesystem/path A simple absolute file system path (unix style)
|
|
* @li @c some\\windows\\path A simple relative file system path (Windows style)
|
|
* @li @c c:\\some\\windows\\path A simple file system path (Windows style)
|
|
*
|
|
* The local path will then be considered as the path component of a uri where
|
|
* appropriate. In case of conversion from a file system path to a uri the relative
|
|
* paths will be converted to absolute paths as uris don't allow relative paths.
|
|
*
|
|
*/
|
|
|
|
#ifndef GNCURIUTILS_H_
|
|
#define GNCURIUTILS_H_
|
|
|
|
#define GNC_DATAFILE_EXT ".gnucash"
|
|
#define GNC_LOGFILE_EXT ".log"
|
|
|
|
/** Checks if the given uri is a valid uri
|
|
*
|
|
* A valid uri is defined by having at least a protocol and a path.
|
|
* If the uri is not referring to a file on the local file system
|
|
* a hostname should be set as well.
|
|
*
|
|
* @param uri The uri to check
|
|
*
|
|
* @return TRUE if the input is a valid uri, FALSE otherwise
|
|
*/
|
|
gboolean gnc_uri_is_uri (const gchar *uri);
|
|
|
|
/** 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.
|
|
*
|
|
* @param uri The uri to convert
|
|
*
|
|
* @param protocol The protocol for this uri. If the uri didn't have an
|
|
* explicit protocol, NULL will be returned.
|
|
* @param hostname The host name of the server to connect to. In case of
|
|
* the local file system path, NULL will be returned
|
|
* @param 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.
|
|
* @param username Optional user name found in this uri or NULL if none is found.
|
|
* @param password Optional password found in this uri or NULL if none is found.
|
|
* @param path The path found in this uri.
|
|
*
|
|
*/
|
|
|
|
void gnc_uri_get_components (const gchar *uri,
|
|
gchar **protocol,
|
|
gchar **hostname,
|
|
gint32 *port,
|
|
gchar **username,
|
|
gchar **password,
|
|
gchar **path);
|
|
|
|
/** Extracts the protocol from a uri
|
|
*
|
|
* The function allocates memory for the protocol. The calling function should
|
|
* free this memory with g_free if it no longer needs the string.
|
|
*
|
|
* @param uri The uri to extract the protocol from
|
|
*
|
|
* @return The protocol for this uri. If the uri didn't have an
|
|
* explicit protocol, NULL will be returned.
|
|
*/
|
|
|
|
gchar *gnc_uri_get_protocol (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.
|
|
*
|
|
* @param uri The uri to extract the path part from
|
|
*
|
|
* @return The protocol for this uri, or NULL if no path could be extracted.
|
|
*/
|
|
|
|
gchar *gnc_uri_get_path (const gchar *uri);
|
|
|
|
/** Composes a normalized uri starting from its separate components.
|
|
*
|
|
* The resulting uri will take either of these forms:
|
|
* @li @c file:///some/absolute/path (file could also be xml or sqlite)
|
|
* @li @c file://c:\\some\\windows\\path (file could also be xml or sqlite)
|
|
* @li @c protocol://[user[:password]@]hostname[:port]/path
|
|
*
|
|
* Only the components that are provided will be inserted in the uri. However
|
|
* if no protocol has been provided, 'file' will be used as default protocol.
|
|
*
|
|
* The function allocates memory for the uri. The calling function should
|
|
* free this memory with g_free the uri is no longer needed.
|
|
*
|
|
* @param protocol The protocol for this uri. If NULL,, 'file' will be used
|
|
* in the uri.
|
|
* @param hostname The host name of the server to connect to. This will be
|
|
* ignored for the 'file' type protocols ('file', 'xml', 'sqlite').
|
|
* @param 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 protocols ('file', 'xml',
|
|
* 'sqlite').
|
|
* @param username Optional user name to set in the uri or NULL otherwise. This will
|
|
* be ignored for the 'file' type protocols ('file', 'xml', 'sqlite').
|
|
* @param password Optional password to set in the uri or NULL otherwise. This will
|
|
* be ignored for the 'file' type protocols ('file', 'xml', 'sqlite').
|
|
* @param path The path to set in the uri.
|
|
*
|
|
* @return The normalized uri.
|
|
*/
|
|
|
|
gchar *gnc_uri_create_uri (const gchar *protocol,
|
|
const gchar *hostname,
|
|
gint32 port,
|
|
const gchar *username,
|
|
const gchar *password,
|
|
const gchar *path);
|
|
|
|
/** Composes a normalized uri starting from any uri (filename, db spec,...).
|
|
*
|
|
* The resulting uri will take either of these forms:
|
|
* @li @c file:///some/absolute/path ('file' can also be xml or sqlite)
|
|
* @li @c file://c:\\some\\windows\\path ('file' can also be xml or sqlite)
|
|
* @li @c protocol://[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 protocol has been provided, 'file' will be used as default protocol.
|
|
*
|
|
* The function allocates memory for the uri. The calling function should
|
|
* free this memory with g_free the uri is no longer needed.
|
|
*
|
|
* @param uri The uri that schould be converted into a normalized uri
|
|
* @param 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.
|
|
*
|
|
* @return The normalized uri.
|
|
*/
|
|
gchar *gnc_uri_normalize_uri (const gchar *uri, gboolean allow_password);
|
|
|
|
|
|
/** Checks if the given uri is a valid uri
|
|
*
|
|
* A valid uri is defined by having at least a protocol and a path.
|
|
* If the uri is not referring to a file on the local file system
|
|
* a hostname should be set as well.
|
|
*
|
|
* @param uri The uri to check
|
|
*
|
|
* @return TRUE if the input is a valid uri, FALSE otherwise
|
|
*/
|
|
gboolean gnc_uri_is_uri (const gchar *uri);
|
|
|
|
|
|
/** Checks if there is a backend that explicitly stated to handle the given protocol.
|
|
*
|
|
* @param protocol The protocol to check
|
|
*
|
|
* @return TRUE if at least one backend explicitly handles this protocol, otherwise FALSE
|
|
*/
|
|
gboolean gnc_uri_is_known_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)
|
|
*
|
|
* @param protocol The protocol to check
|
|
*
|
|
* @return TRUE if the protocol is used with files, FALSE of the protocol
|
|
* is normally used with network services (database, web url,...)
|
|
*/
|
|
gboolean gnc_uri_is_file_protocol (const gchar *protocol);
|
|
|
|
/** Checks if the given uri defines a file
|
|
* (as opposed to a network service like a database or web url)
|
|
*
|
|
* @param uri The uri to check
|
|
*
|
|
* @return TRUE if the uri is a files, FALSE of the protocol
|
|
* is normally used with network services (database, web url,...)
|
|
*/
|
|
gboolean gnc_uri_is_file_uri (const gchar *uri);
|
|
|
|
/** Checks if the given uri is either a valid file uri or a local filesystem path
|
|
*
|
|
* A valid uri is defined by having at least a protocol and a path.
|
|
* If the uri is not referring to a file on the local file system
|
|
* a hostname should be set as well.
|
|
*
|
|
* @param uri The uri to check
|
|
*
|
|
* @return TRUE if the input is a valid file uri or a local filesystem path.
|
|
* FALSE otherwise
|
|
*/
|
|
gboolean gnc_uri_targets_local_fs (const gchar *uri);
|
|
|
|
/** Adds an extension to the uri if:
|
|
* * the uri is not empty and file based
|
|
* * doesn't already have the extension
|
|
*
|
|
* @param uri The uri to process
|
|
* @param 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.
|
|
*
|
|
* @return The uri, but garanteed 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.
|
|
*/
|
|
gchar *gnc_uri_add_extension ( const gchar *uri, const gchar *extension );
|
|
|
|
#endif /* GNCURIUTILS_H_ */
|
|
/** @} */
|
|
/** @} */
|
|
|