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

---

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* 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* 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* 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* 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 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 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 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 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 succesfully 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.