GnuCash  3.4-243-gdd64cec27+
Files | Macros | Functions
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
uriThe uri to process
extensionThe 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 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.

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

379 {
380  g_return_val_if_fail( uri != 0, NULL );
381 
382  /* Only add extension if the user provided the extension and the uri is
383  * file based.
384  */
385  if ( !extension || !gnc_uri_is_file_uri( uri ) )
386  return g_strdup( uri );
387 
388  /* Don't add extension if it's already there */
389  if ( g_str_has_suffix( uri, extension ) )
390  return g_strdup( uri );
391 
392  /* Ok, all tests passed, let's add the extension */
393  return g_strconcat( uri, extension, NULL );
394 }
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) ...

◆ 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:

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
schemeThe scheme for this uri. If NULL,, 'file' will be used in the uri.
hostnameThe host name of the server to connect to. This will be ignored for the 'file' type schemes ('file', 'xml', 'sqlite').
portAn 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').
usernameOptional user name to set in the uri or NULL otherwise. This will be ignored for the 'file' type schemes ('file', 'xml', 'sqlite').
passwordOptional password to set in the uri or NULL otherwise. This will be ignored for the 'file' type schemes ('file', 'xml', 'sqlite').
pathThe path to set in the uri.
Returns
The normalized uri.

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

293 {
294  gchar *userpass = NULL, *portstr = NULL, *uri = NULL;
295 
296  g_return_val_if_fail( path != 0, NULL );
297 
298  if (!scheme || gnc_uri_is_file_scheme (scheme))
299  {
300  /* Compose a file based uri, which means ignore everything but
301  * the scheme and the path
302  * We return an absolute pathname if the scheme is known or
303  * no scheme was given. For an unknown scheme, we return the
304  * path info as is.
305  */
306  gchar *abs_path;
307  if (scheme && (!gnc_uri_is_known_scheme (scheme)) )
308  abs_path = g_strdup ( path );
309  else
310  abs_path = gnc_resolve_file_path ( path );
311  if ( scheme == NULL )
312  uri = g_strdup_printf ( "file://%s", abs_path );
313  else
314  uri = g_strdup_printf ( "%s://%s", scheme, abs_path );
315  g_free (abs_path);
316  return uri;
317  }
318 
319  /* Not a file based uri, we need to setup all components that are not NULL
320  * For this scenario, hostname is mandatory.
321  */
322  g_return_val_if_fail( hostname != 0, NULL );
323 
324  if ( username != NULL && *username )
325  {
326  if ( password != NULL && *password )
327  userpass = g_strdup_printf ( "%s:%s@", username, password );
328  else
329  userpass = g_strdup_printf ( "%s@", username );
330  }
331  else
332  userpass = g_strdup ( "" );
333 
334  if ( port != 0 )
335  portstr = g_strdup_printf ( ":%d", port );
336  else
337  portstr = g_strdup ( "" );
338 
339  // XXX Do I have to add the slash always or are there situations
340  // it is in the path already ?
341  uri = g_strconcat ( scheme, "://", userpass, hostname, portstr, "/", path, NULL );
342 
343  g_free ( userpass );
344  g_free ( portstr );
345 
346  return uri;
347 
348 }
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 databas...
Definition: gnc-uri-utils.c:90
gchar * gnc_resolve_file_path(const gchar *filefrag)
The gnc_resolve_file_path() routine is a utility that will accept a fragmentary filename as input...
gboolean gnc_uri_is_known_scheme(const gchar *scheme)
Checks if there is a backend that explicitly stated to handle the given scheme.
Definition: gnc-uri-utils.c:61

◆ 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
uriThe uri to convert
schemeThe scheme for this uri. If the uri doesn't have an explicit scheme, NULL will be returned.
hostnameThe host name of the server to connect to. In case of the local file system path, NULL will be returned
portAn 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.
usernameOptional user name found in this uri or NULL if none is found.
passwordOptional password found in this uri or NULL if none is found.
pathThe path found in this uri.

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

150 {
151  gchar **splituri;
152  gchar *url = NULL, *tmpusername = NULL, *tmphostname = NULL;
153  gchar *delimiter = NULL;
154 
155  *scheme = NULL;
156  *hostname = NULL;
157  *port = 0;
158  *username = NULL;
159  *password = NULL;
160  *path = NULL;
161 
162  g_return_if_fail( uri != NULL && strlen (uri) > 0);
163 
164  splituri = g_strsplit ( uri, "://", 2 );
165  if ( splituri[1] == NULL )
166  {
167  /* No scheme means simple file path.
168  Set path to copy of the input. */
169  *path = g_strdup ( uri );
170  g_strfreev ( splituri );
171  return;
172  }
173 
174  /* At least a scheme was found, set it here */
175  *scheme = g_strdup ( splituri[0] );
176 
177  if ( gnc_uri_is_file_scheme ( *scheme ) )
178  {
179  *path = gnc_resolve_file_path ( splituri[1] );
180  g_strfreev ( splituri );
181  return;
182  }
183 
184  /* Protocol indicates full network style uri, let's see if it
185  * has a username and/or password
186  */
187  url = g_strdup (splituri[1]);
188  g_strfreev ( splituri );
189 
190  /* Check for "@" sign, but start from the end - the password may contain
191  * this sign as well
192  */
193  delimiter = g_strrstr ( url, "@" );
194  if ( delimiter != NULL )
195  {
196  /* There is at least a username in the url */
197  delimiter[0] = '\0';
198  tmpusername = url;
199  tmphostname = delimiter + 1;
200 
201  /* Check if there's a password too by looking for a :
202  * Start from the beginning this time to avoid possible :
203  * in the password */
204  delimiter = g_strstr_len ( tmpusername, -1, ":" );
205  if ( delimiter != NULL )
206  {
207  /* There is password in the url */
208  delimiter[0] = '\0';
209  *password = g_strdup ( (const gchar*)(delimiter + 1) );
210  }
211  *username = g_strdup ( (const gchar*)tmpusername );
212  }
213  else
214  {
215  /* No username and password were given */
216  tmphostname = url;
217  }
218 
219  /* Find the path part */
220  delimiter = g_strstr_len ( tmphostname, -1, "/" );
221  if ( delimiter != NULL )
222  {
223  delimiter[0] = '\0';
224  if ( gnc_uri_is_file_scheme ( *scheme ) ) /* always return absolute file paths */
225  *path = gnc_resolve_file_path ( (const gchar*)(delimiter + 1) );
226  else /* path is no file path, so copy it as is */
227  *path = g_strdup ( (const gchar*)(delimiter + 1) );
228  }
229 
230  /* Check for a port specifier */
231  delimiter = g_strstr_len ( tmphostname, -1, ":" );
232  if ( delimiter != NULL )
233  {
234  delimiter[0] = '\0';
235  *port = g_ascii_strtoll ( delimiter + 1, NULL, 0 );
236  }
237 
238  *hostname = g_strdup ( (const gchar*)tmphostname );
239 
240  g_free ( url );
241 
242  return;
243 
244 }
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 databas...
Definition: gnc-uri-utils.c:90
gchar * gnc_resolve_file_path(const gchar *filefrag)
The gnc_resolve_file_path() routine is a utility that will accept a fragmentary filename as input...

◆ 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
uriThe uri to extract the path part from
Returns
The path for this uri, or NULL if no path could be extracted.

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

267 {
268  gchar *scheme = NULL;
269  gchar *hostname = NULL;
270  gint32 port = 0;
271  gchar *username = NULL;
272  gchar *password = NULL;
273  gchar *path = NULL;
274 
275  gnc_uri_get_components ( uri, &scheme, &hostname, &port,
276  &username, &password, &path );
277 
278  g_free (scheme);
279  g_free (hostname);
280  g_free (username);
281  g_free (password);
282 
283  return path;
284 }
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.

◆ 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
uriThe 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 401 of file gnc-uri-utils.c.

402 {
403  return gnc_uri_get_scheme (uri);
404 }
gchar * gnc_uri_get_scheme(const gchar *uri)
Extracts the scheme from a 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
uriThe 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 246 of file gnc-uri-utils.c.

247 {
248  gchar *scheme = NULL;
249  gchar *hostname = NULL;
250  gint32 port = 0;
251  gchar *username = NULL;
252  gchar *password = NULL;
253  gchar *path = NULL;
254 
255  gnc_uri_get_components ( uri, &scheme, &hostname, &port,
256  &username, &password, &path );
257 
258  g_free (hostname);
259  g_free (username);
260  g_free (password);
261  g_free (path);
262 
263  return scheme;
264 }
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.

◆ 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
protocolThe 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 413 of file gnc-uri-utils.c.

414 {
415  return gnc_uri_is_file_scheme (protocol);
416 }
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 databas...
Definition: gnc-uri-utils.c:90

◆ 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
schemeThe 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.

91 {
92  return (scheme &&
93  (!g_ascii_strcasecmp (scheme, "file") ||
94  !g_ascii_strcasecmp (scheme, "xml") ||
95  !g_ascii_strcasecmp (scheme, "sqlite3")));
96 }

◆ 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
uriThe 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.

102 {
103  gchar *scheme = gnc_uri_get_scheme ( uri );
104  gboolean result = gnc_uri_is_file_scheme ( scheme );
105 
106  g_free ( scheme );
107 
108  return result;
109 }
gchar * gnc_uri_get_scheme(const gchar *uri)
Extracts the scheme from a uri.
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 databas...
Definition: gnc-uri-utils.c:90

◆ 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
protocolThe protocol to check
Returns
TRUE if at least one backend explicitly handles this protocol, otherwise FALSE

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

408 {
409  return gnc_uri_is_known_scheme(protocol);
410 }
gboolean gnc_uri_is_known_scheme(const gchar *scheme)
Checks if there is a backend that explicitly stated to handle the given scheme.
Definition: gnc-uri-utils.c:61

◆ 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
schemeThe 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.

62 {
63  gboolean is_known_scheme = FALSE;
64  GList *node;
65  GList *known_scheme_list = qof_backend_get_registered_access_method_list();
66 
67  for ( node = known_scheme_list; node != NULL; node = node->next )
68  {
69  gchar *known_scheme = node->data;
70  if ( !g_ascii_strcasecmp (scheme, known_scheme) )
71  {
72  is_known_scheme = TRUE;
73  break;
74  }
75  }
76 
77  g_list_free (known_scheme_list);
78  return is_known_scheme;
79 }
GList * qof_backend_get_registered_access_method_list(void)
Return a list of strings for the registered access methods.
Definition: qofsession.cpp:106

◆ 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
uriThe uri to check
Returns
TRUE if the input is a valid uri, FALSE otherwise

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

33 {
34 
35  gchar *scheme = NULL, *hostname = NULL;
36  gchar *username = NULL, *password = NULL;
37  gchar *path = NULL;
38  gint port = 0;
39  gboolean is_uri = FALSE;
40 
41  gnc_uri_get_components ( uri, &scheme, &hostname, &port,
42  &username, &password, &path );
43 
44  /* For gnucash to consider a uri valid the following must be true:
45  * - scheme and path must not be NULL
46  * - for anything but local filesystem uris, hostname must be valid as well */
47  is_uri = (scheme && path && (gnc_uri_is_file_scheme(scheme) || hostname));
48 
49  g_free (scheme);
50  g_free (hostname);
51  g_free (username);
52  g_free (password);
53  g_free (path);
54 
55  return is_uri;
56 }
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 databas...
Definition: gnc-uri-utils.c:90
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.

◆ 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:

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
uriThe uri that schould be converted into a normalized uri
allow_passwordIf 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 350 of file gnc-uri-utils.c.

351 {
352  gchar *scheme = NULL;
353  gchar *hostname = NULL;
354  gint32 port = 0;
355  gchar *username = NULL;
356  gchar *password = NULL;
357  gchar *path = NULL;
358  gchar *newuri = NULL;
359 
360  gnc_uri_get_components ( uri, &scheme, &hostname, &port,
361  &username, &password, &path );
362  if (allow_password)
363  newuri = gnc_uri_create_uri ( scheme, hostname, port,
364  username, password, path);
365  else
366  newuri = gnc_uri_create_uri ( scheme, hostname, port,
367  username, /* no password */ NULL, path);
368 
369  g_free (scheme);
370  g_free (hostname);
371  g_free (username);
372  g_free (password);
373  g_free (path);
374 
375  return newuri;
376 }
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.
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.

◆ 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
uriThe 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.

114 {
115 
116  gchar *scheme = NULL, *hostname = NULL;
117  gchar *username = NULL, *password = NULL;
118  gchar *path = NULL;
119  gint port = 0;
120  gboolean is_local_fs = FALSE;
121 
122  gnc_uri_get_components ( uri, &scheme, &hostname, &port,
123  &username, &password, &path );
124 
125  /* For gnucash to consider a uri to target the local fs:
126  * path must not be NULL
127  * AND
128  * scheme should be NULL
129  * OR
130  * scheme must be file type scheme (file, xml, sqlite) */
131  is_local_fs = (path && (!scheme || gnc_uri_is_file_scheme(scheme)));
132 
133  g_free (scheme);
134  g_free (hostname);
135  g_free (username);
136  g_free (password);
137  g_free (path);
138 
139  return is_local_fs;
140 }
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 databas...
Definition: gnc-uri-utils.c:90
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.