SpatiaLite  4.3.0
Macros | Functions
gaiaaux.h File Reference

Auxiliary/helper functions. More...

Go to the source code of this file.

Macros

#define GAIA_SQL_SINGLE_QUOTE   1001
 SQL single quoted string (text constant)
 
#define GAIA_SQL_DOUBLE_QUOTE   1002
 SQL double quoted string (SQL name)
 

Functions

GAIAAUX_DECLARE const char * gaiaGetLocaleCharset (void)
 Retrieves the Locale Charset. More...
 
GAIAAUX_DECLARE int gaiaConvertCharset (char **buf, const char *fromCs, const char *toCs)
 Converts a text string from one charset to another. More...
 
GAIAAUX_DECLARE void * gaiaCreateUTF8Converter (const char *fromCS)
 Creates a persistent UTF8 converter object. More...
 
GAIAAUX_DECLARE void gaiaFreeUTF8Converter (void *cvtCS)
 Destroys an UTF8 converter object. More...
 
GAIAAUX_DECLARE char * gaiaConvertToUTF8 (void *cvtCS, const char *buf, int len, int *err)
 Converts a text string to UTF8. More...
 
GAIAAUX_DECLARE int gaiaIsReservedSqliteName (const char *name)
 Checks if a name is a reserved SQLite name. More...
 
GAIAAUX_DECLARE int gaiaIsReservedSqlName (const char *name)
 Checks if a name is a reserved SQL name. More...
 
GAIAAUX_DECLARE int gaiaIllegalSqlName (const char *name)
 Checks if a name is an illegal SQL name. More...
 
GAIAAUX_DECLARE char * gaiaSingleQuotedSql (const char *value)
 Properly formats an SQL text constant. More...
 
GAIAAUX_DECLARE char * gaiaDoubleQuotedSql (const char *value)
 Properly formats an SQL name. More...
 
GAIAAUX_DECLARE char * gaiaQuotedSql (const char *value, int quote)
 Properly formats an SQL generic string. More...
 
GAIAAUX_DECLARE char * gaiaDequotedSql (const char *value)
 Properly formats an SQL generic string (dequoting) More...
 
GAIAAUX_DECLARE void gaiaCleanSqlString (char *value)
 deprecated function More...
 
GAIAAUX_DECLARE void gaiaInsertIntoSqlLog (sqlite3 *sqlite, const char *user_agent, const char *utf8Sql, sqlite3_int64 *sqllog_pk)
 SQL log: statement start. More...
 
GAIAAUX_DECLARE void gaiaUpdateSqlLog (sqlite3 *sqlite, sqlite3_int64 sqllog_pk, int success, const char *errMsg)
 SQL log: statement start. More...
 
GAIAAUX_DECLARE void * gaiaCreateMD5Checksum (void)
 Creates a persistent MD5 checksum object. More...
 
GAIAAUX_DECLARE void gaiaFreeMD5Checksum (void *md5)
 Destroys an MD5 checksum object. More...
 
GAIAAUX_DECLARE void gaiaUpdateMD5Checksum (void *md5, const unsigned char *blob, int blob_len)
 Updates an MD5 checksum object. More...
 
GAIAAUX_DECLARE char * gaiaFinalizeMD5Checksum (void *md5)
 Return an MD5 checksum value. More...
 
GAIAAUX_DECLARE int gaiaParseDMS (const char *dms, double *longitude, double *latitude)
 Return longitude and latitude angles from a DMS string. More...
 
GAIAAUX_DECLARE char * gaiaConvertToDMS (double longitude, double latitude)
 Return a DMS string. More...
 
GAIAAUX_DECLARE char * gaiaEncodeURL (const char *url)
 Return a percent-encoded URL. More...
 
GAIAAUX_DECLARE char * gaiaDecodeURL (const char *encoded)
 Return a clean URL from its percent-encoded representation. More...
 
GAIAAUX_DECLARE char * gaiaDirNameFromPath (const char *path)
 Return the DirName component (if any) from a Path. More...
 
GAIAAUX_DECLARE char * gaiaFullFileNameFromPath (const char *path)
 Return the FullFileName from a Path. More...
 
GAIAAUX_DECLARE char * gaiaFileNameFromPath (const char *path)
 Return the FileName from a Path. More...
 
GAIAAUX_DECLARE char * gaiaFileExtFromPath (const char *path)
 Return the FileExtension from a Path. More...
 

Detailed Description

Auxiliary/helper functions.

Function Documentation

GAIAAUX_DECLARE void gaiaCleanSqlString ( char *  value)

deprecated function

Parameters
valuethe string to be formatted
See also
gaiaQuotedSql
Note
this function is still supported simply for backward compatibility. it's intrinsically unsafe (passing huge strings potentially leads to buffer overflows) and you are strongly encouraged to use gaiaQuotedSql() as a safest replacement.
GAIAAUX_DECLARE int gaiaConvertCharset ( char **  buf,
const char *  fromCs,
const char *  toCs 
)

Converts a text string from one charset to another.

Parameters
bufthe text string to be converted
fromCsthe GNU ICONV name identifying the input charset
toCsthe GNU ICONV name identifying the output charset
Returns
0 on failure, any other value on success.
Note
this function uses an internal buffer limited to 64KB; so it's not safe passing extremely huge-sized text string.
GAIAAUX_DECLARE char* gaiaConvertToDMS ( double  longitude,
double  latitude 
)

Return a DMS string.

Parameters
longitudethe angle of longitude expressed in Decimal Degrees.
latitudethe angle of latitude expressed in Decimal Degrees.
Returns
the corresponding DMS (Degrees/Minutes/Seconds) text string, or NULL on failure
See also
gaiaLongitudeFromDMS, gaiaLatitudeFromDMS
Note
this function will return a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE char* gaiaConvertToUTF8 ( void *  cvtCS,
const char *  buf,
int  len,
int *  err 
)

Converts a text string to UTF8.

Parameters
cvtCSthe handle identifying the UTF8 convert object (returned by a previous call to gaiaCreateUTF8Converter).
bufthe input text string
lenlength (in bytes) of input string
erron completion will contain 0 on success, any other value on failure
Returns
the null-terminated UTF8 encoded string: NULL on failure
See also
gaiaCreateUTF8Converter, gaiaFreeUTF8Converter
Note
this function can safely handle strings of arbitrary length, and will return the converted string into a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE void* gaiaCreateMD5Checksum ( void  )

Creates a persistent MD5 checksum object.

Returns
the handle of an MD5 checksum object, or NULL on failure
See also
gaiaFreeMD5Checksum, gaiaUpdateMD5Checksum, gaiaFinalizeMD5Checksum
Note
you must properly destroy the MD5 object when it isn't any longer used.
GAIAAUX_DECLARE void* gaiaCreateUTF8Converter ( const char *  fromCS)

Creates a persistent UTF8 converter object.

Parameters
fromCSthe GNU ICONV name identifying the input charset
Returns
the handle of the converter object, or NULL on failure
See also
gaiaFreeUTF8Converter
Note
you must properly destroy the converter object when it isn't any longer used.
GAIAAUX_DECLARE char* gaiaDecodeURL ( const char *  encoded)

Return a clean URL from its percent-encoded representation.

Parameters
encodedthe percent-encoded URL to be decoded
Returns
the corresponding clean URL text string, or NULL on failure
See also
gaiaEncodeURL
Note
this function will return a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE char* gaiaDequotedSql ( const char *  value)

Properly formats an SQL generic string (dequoting)

Parameters
valuethe string to be dequoted
Returns
the formatted string: NULL on failure
See also
gaiaSingleQuotedSql, gaiaDoubleQuotedSql, gaiaQuotedSql
Note
this function can safely handle strings of arbitrary length, and will return the formatted string into a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE char* gaiaDirNameFromPath ( const char *  path)

Return the DirName component (if any) from a Path.

Parameters
pathfull or relative pathname
Returns
the corresponding DirName text string, or NULL on failure
See also
gaiaFullFileNameFromPath, gaiaFileNameFromPath, gaiaFileExtFromPath
Note
this function will return a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE char* gaiaDoubleQuotedSql ( const char *  value)

Properly formats an SQL name.

Parameters
valuethe SQL name to be formatted
Returns
the formatted string: NULL on failure
See also
gaiaQuotedSql, gaiaDequotedSql
Note
this function simply is a convenience method corresponding to: gaiaQuotedSQL(value, GAIA_SQL_DOUBLE_QUOTE);
Remarks
passing a string like "Sant\"Andrea" will return "Sant""Andrea"
GAIAAUX_DECLARE char* gaiaEncodeURL ( const char *  url)

Return a percent-encoded URL.

Parameters
urlthe URL to be percent-encoded
Returns
the corresponding percent-encoded URL text string, or NULL on failure
See also
gaiaDecodeURL
Note
this function will return a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE char* gaiaFileExtFromPath ( const char *  path)

Return the FileExtension from a Path.

Parameters
pathfull or relative pathname
Returns
the corresponding FileExtension (if any), or NULL on failure
See also
gaiaDirNameFromPath, gaiaFullFileNameFromPath, gaiaFileNameFromPath
Note
this function will return a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE char* gaiaFileNameFromPath ( const char *  path)

Return the FileName from a Path.

Parameters
pathfull or relative pathname
Returns
the corresponding FileName (excluding an eventual extension), or NULL on failure
See also
gaiaDirNameFromPath, gaiaFullFileNameFromPath, gaiaFileExtFromPath
Note
this function will return a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE char* gaiaFinalizeMD5Checksum ( void *  md5)

Return an MD5 checksum value.

Parameters
md5the handle of the MD5 checksum object (returned by a previous call to gaiaCreateMD5Checksum).
Returns
an hexadecimal text string representing the MD checksum: NULL on failure
See also
gaiaCreateMD5Checksum, gaiaUpdateMD5Checksum, gaiaFreeMD5Checksum
Note
this function will return the MD5 checksum into a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
gaiaFinalizeMD5Checksum will implicitly reset the MD5 object to its initial state.
GAIAAUX_DECLARE void gaiaFreeMD5Checksum ( void *  md5)

Destroys an MD5 checksum object.

Parameters
md5the handle of the MD5 checksum object (returned by a previous call to gaiaCreateMD5Checksum).
See also
gaiaCreateMD5Checksum
GAIAAUX_DECLARE void gaiaFreeUTF8Converter ( void *  cvtCS)

Destroys an UTF8 converter object.

Parameters
cvtCSthe handle identifying the UTF8 convert object (returned by a previous call to gaiaCreateUTF8Converter).
See also
gaiaCreateUTF8Converter
GAIAAUX_DECLARE char* gaiaFullFileNameFromPath ( const char *  path)

Return the FullFileName from a Path.

Parameters
pathfull or relative pathname
Returns
the corresponding FullFileName (including an eventual extension), or NULL on failure
See also
gaiaDirNameFromPath, gaiaFileNameFromPath, gaiaFileExtFromPath
Note
this function will return a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE const char* gaiaGetLocaleCharset ( void  )

Retrieves the Locale Charset.

Returns
the GNU ICONV name identifying the locale charset
GAIAAUX_DECLARE int gaiaIllegalSqlName ( const char *  name)

Checks if a name is an illegal SQL name.

Parameters
namethe name to be checked
Returns
0 if no: any other value if yes
See also
gaiaIsReservedSqliteName, gaiaIsReservedSqlName
GAIAAUX_DECLARE void gaiaInsertIntoSqlLog ( sqlite3 *  sqlite,
const char *  user_agent,
const char *  utf8Sql,
sqlite3_int64 *  sqllog_pk 
)

SQL log: statement start.

Parameters
sqlitehandle of the current DB connection
user_agentname of the invoking application, e.g. "spatialite_gui" or "spatialite CLI"
utf8Sqlthe SQL statement bein executed
sqllog_pkafter completion this variable will contain the value of the Primary Key identifying the corresponding Log event
See also
gaiaUpdateSqlLog
Note
this function inserts an event into the SQL Log, and is expected to be invoked immediately before executing the SQL statement itself.
GAIAAUX_DECLARE int gaiaIsReservedSqliteName ( const char *  name)

Checks if a name is a reserved SQLite name.

Parameters
namethe name to be checked
Returns
0 if no: any other value if yes
See also
gaiaIsReservedSqlName, gaiaIllegalSqlName
GAIAAUX_DECLARE int gaiaIsReservedSqlName ( const char *  name)

Checks if a name is a reserved SQL name.

Parameters
namethe name to be checked
Returns
0 if no: any other value if yes
See also
gaiaIsReservedSqliteName, gaiaIllegalSqlName
GAIAAUX_DECLARE int gaiaParseDMS ( const char *  dms,
double *  longitude,
double *  latitude 
)

Return longitude and latitude angles from a DMS string.

Parameters
dmsa text string representing a valid DMS (Degrees/Minutes/Seconds) expression.
longitudeon completion this variable will contain the longitude angle expressed in Decimal Degrees.
latitudeon completion this variable will contain the latitude angle expressed in Decimal Degrees.
Returns
ZERO (FALSE) on failure, any other different value (TRUE) on success.
See also
gaiaConvertToDMS
Note
this function will return a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE char* gaiaQuotedSql ( const char *  value,
int  quote 
)

Properly formats an SQL generic string.

Parameters
valuethe string to be formatted
quoteGAIA_SQL_SINGLE_QUOTE or GAIA_SQL_DOUBLE_QUOTE
Returns
the formatted string: NULL on failure
See also
gaiaSingleQuotedSql, gaiaDoubleQuotedSql, gaiaDequotedSql
Note
this function can safely handle strings of arbitrary length, and will return the formatted string into a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.
GAIAAUX_DECLARE char* gaiaSingleQuotedSql ( const char *  value)

Properly formats an SQL text constant.

Parameters
valuethe text string to be formatted
Returns
the formatted string: NULL on failure
See also
gaiaQuotedSql, gaiaDequotedSql
Note
this function simply is a convenience method corresponding to: gaiaQuotedSQL(value, GAIA_SQL_SINGLE_QUOTE);
Remarks
passing a string like "Sant'Andrea" will return 'Sant''Andrea'
GAIAAUX_DECLARE void gaiaUpdateMD5Checksum ( void *  md5,
const unsigned char *  blob,
int  blob_len 
)

Updates an MD5 checksum object.

Parameters
md5the handle of the MD5 checksum object (returned by a previous call to gaiaCreateMD5Checksum).
bloban arbitrary sequence of binary data
blob_sizethe length (in bytes) of the binary data
See also
gaiaCreateMD5Checksum, gaiaFreeMD5Checksum, gaiaFinalizeMD5Checksum
Note
you can repeatedly invoke gaiaUpdateMD5Checksum more than a single time and always using the same MD5 object. In this case the final MD5 checksum returned by gaiaGetMD5Checsum will be the total checksum for any data processed by the MD5 object since its initialization.
GAIAAUX_DECLARE void gaiaUpdateSqlLog ( sqlite3 *  sqlite,
sqlite3_int64  sqllog_pk,
int  success,
const char *  errMsg 
)

SQL log: statement start.

Parameters
sqlitehandle of the current DB connection
sqllog_pkthe Primary Key identifying the corresponding Log event.
expected to be exactely the same returned by the most recent call to gaiaInsertIntoSqlLog()
successexpected to be TRUE if the SQL statement was successfully executed.
errMsgexpected to be the error message returned by SQLite on failure, NULL on success.
See also
gaiaInsertIntoSqlLog
Note
this function completes an event inserted into the SQL Log, and is expected to be invoked immediately after executing the SQL statement itself.