src/headers/spatialite/gaiaaux.h File Reference

Auxiliary/helper functions. More...

Go to the source code of this file.

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

---

Detailed Description

Auxiliary/helper functions.

---

Function Documentation

GAIAAUX_DECLARE void gaiaCleanSqlString

(

char *

value

)

deprecated function

Parameters:

value

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

buf	the text string to be converted
fromCs	the GNU ICONV name identifying the input charset
toCs	the 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:

longitude	the angle of longitude expressed in Decimal Degrees.
latitude	the 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:

cvtCS	the handle identifying the UTF8 convert object (returned by a previous call to gaiaCreateUTF8Converter).
buf	the input text string
len	length (in bytes) of input string
err	on 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:

fromCS

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

encoded

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

value

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

path	full 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:

value

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

url	the 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:

path	full 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:

path	full 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:

md5	the 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:

md5	the 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:

cvtCS

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

path	full 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:

name	the 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:

sqlite	handle of the current DB connection
user_agent	name of the invoking application, e.g. "spatialite_gui" or "spatialite CLI"
utf8Sql	the SQL statement bein executed
sqllog_pk	after 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:

name	the 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:

name	the 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:

dms	a text string representing a valid DMS (Degrees/Minutes/Seconds) expression.
longitude	on completion this variable will contain the longitude angle expressed in Decimal Degrees.
latitude	on 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:

value	the string to be formatted
quote	GAIA_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:

value

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

md5	the handle of the MD5 checksum object (returned by a previous call to gaiaCreateMD5Checksum).
blob	an arbitrary sequence of binary data
blob_size	the 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:

sqlite	handle of the current DB connection
sqllog_pk	the Primary Key identifying the corresponding Log event. expected to be exactely the same returned by the most recent call to gaiaInsertIntoSqlLog()
success	expected to be TRUE if the SQL statement was successfully executed.
errMsg	expected 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.