/usr/include/spatialite/gaiaaux.h is in libspatialite-dev 4.1.1-5ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 | /*
gaiaaux.h -- Gaia common utility functions
version 4.1, 2013 May 8
Author: Sandro Furieri a.furieri@lqt.it
------------------------------------------------------------------------------
Version: MPL 1.1/GPL 2.0/LGPL 2.1
The contents of this file are subject to the Mozilla Public License Version
1.1 (the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.mozilla.org/MPL/
Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
for the specific language governing rights and limitations under the
License.
The Original Code is the SpatiaLite library
The Initial Developer of the Original Code is Alessandro Furieri
Portions created by the Initial Developer are Copyright (C) 2008-2013
the Initial Developer. All Rights Reserved.
Contributor(s):
Alternatively, the contents of this file may be used under the terms of
either the GNU General Public License Version 2 or later (the "GPL"), or
the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
in which case the provisions of the GPL or the LGPL are applicable instead
of those above. If you wish to allow use of your version of this file only
under the terms of either the GPL or the LGPL, and not to allow others to
use your version of this file under the terms of the MPL, indicate your
decision by deleting the provisions above and replace them with the notice
and other provisions required by the GPL or the LGPL. If you do not delete
the provisions above, a recipient may use your version of this file under
the terms of any one of the MPL, the GPL or the LGPL.
*/
/**
\file gaiaaux.h
Auxiliary/helper functions
*/
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#ifdef DLL_EXPORT
#define GAIAAUX_DECLARE __declspec(dllexport)
#else
#define GAIAAUX_DECLARE extern
#endif
#endif
#ifndef _GAIAAUX_H
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define _GAIAAUX_H
#endif
#ifdef __cplusplus
extern "C"
{
#endif
/* constants */
/** SQL single quoted string (text constant) */
#define GAIA_SQL_SINGLE_QUOTE 1001
/** SQL double quoted string (SQL name) */
#define GAIA_SQL_DOUBLE_QUOTE 1002
/* function prototypes */
/**
Retrieves the Locale Charset
\return the GNU ICONV name identifying the locale charset
*/
GAIAAUX_DECLARE const char *gaiaGetLocaleCharset (void);
/**
Converts a text string from one charset to another
\param buf the text string to be converted
\param fromCs the GNU ICONV name identifying the input charset
\param toCs the GNU ICONV name identifying the output charset
\return 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 int gaiaConvertCharset (char **buf, const char *fromCs,
const char *toCs);
/**
Creates a persistent UTF8 converter object
\param fromCS the GNU ICONV name identifying the input charset
\return the handle of the converter object, or NULL on failure
\sa gaiaFreeUTF8Converter
\note you must properly destroy the converter object
when it isn't any longer used.
*/
GAIAAUX_DECLARE void *gaiaCreateUTF8Converter (const char *fromCS);
/**
Destroys an UTF8 converter object
\param cvtCS the handle identifying the UTF8 convert object
(returned by a previous call to gaiaCreateUTF8Converter).
\sa gaiaCreateUTF8Converter
*/
GAIAAUX_DECLARE void gaiaFreeUTF8Converter (void *cvtCS);
/**
Converts a text string to UTF8
\param cvtCS the handle identifying the UTF8 convert object
(returned by a previous call to gaiaCreateUTF8Converter).
\param buf the input text string
\param len length (in bytes) of input string
\param err on completion will contain 0 on success, any other value on failure
\return the null-terminated UTF8 encoded string: NULL on failure
\sa 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 char *gaiaConvertToUTF8 (void *cvtCS, const char *buf,
int len, int *err);
/**
Checks if a name is a reserved SQLite name
\param name the name to be checked
\return 0 if no: any other value if yes
\sa gaiaIsReservedSqlName, gaiaIllegalSqlName
*/
GAIAAUX_DECLARE int gaiaIsReservedSqliteName (const char *name);
/**
Checks if a name is a reserved SQL name
\param name the name to be checked
\return 0 if no: any other value if yes
\sa gaiaIsReservedSqliteName, gaiaIllegalSqlName
*/
GAIAAUX_DECLARE int gaiaIsReservedSqlName (const char *name);
/**
Checks if a name is an illegal SQL name
\param name the name to be checked
\return 0 if no: any other value if yes
\sa gaiaIsReservedSqliteName, gaiaIsReservedSqlName
*/
GAIAAUX_DECLARE int gaiaIllegalSqlName (const char *name);
/**
Properly formats an SQL text constant
\param value the text string to be formatted
\return the formatted string: NULL on failure
\sa gaiaQuotedSql, gaiaDequotedSql
\note this function simply is a convenience method corresponding to:
gaiaQuotedSQL(value, GAIA_SQL_SINGLE_QUOTE);
\remark passing a string like "Sant'Andrea" will return 'Sant''Andrea'
*/
GAIAAUX_DECLARE char *gaiaSingleQuotedSql (const char *value);
/**
Properly formats an SQL name
\param value the SQL name to be formatted
\return the formatted string: NULL on failure
\sa gaiaQuotedSql, gaiaDequotedSql
\note this function simply is a convenience method corresponding to:
gaiaQuotedSQL(value, GAIA_SQL_DOUBLE_QUOTE);
\remark passing a string like "Sant\"Andrea" will return "Sant""Andrea"
*/
GAIAAUX_DECLARE char *gaiaDoubleQuotedSql (const char *value);
/**
Properly formats an SQL generic string
\param value the string to be formatted
\param quote GAIA_SQL_SINGLE_QUOTE or GAIA_SQL_DOUBLE_QUOTE
\return the formatted string: NULL on failure
\sa 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 *gaiaQuotedSql (const char *value, int quote);
/**
Properly formats an SQL generic string (dequoting)
\param value the string to be dequoted
\return the formatted string: NULL on failure
\sa 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 *gaiaDequotedSql (const char *value);
/*
/ DEPRECATED FUNCTION: gaiaCleanSqlString()
/ this function must not be used for any new project
/ it's still maintained for backward compatibility,
/ but will be probably removed in future versions
*/
/**
deprecated function
\param value the string to be formatted
\sa 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 void gaiaCleanSqlString (char *value);
/**
SQL log: statement start
\param sqlite handle of the current DB connection
\param user_agent name of the invoking application, e.g. "spatialite_gui" or "spatialite CLI"
\param utf8Sql the SQL statement bein executed
\param sqllog_pk after completion this variable will contain the value
of the Primary Key identifying the corresponding Log event
\sa gaiaUpdateSqlLog
\note this function inserts an \b event into the SQL Log, and
is expected to be invoked immediately \b before executing the SQL
statement itself.
*/
GAIAAUX_DECLARE void gaiaInsertIntoSqlLog (sqlite3 * sqlite,
const char *user_agent,
const char *utf8Sql,
sqlite3_int64 * sqllog_pk);
/**
SQL log: statement start
\param sqlite handle of the current DB connection
\param sqllog_pk the Primary Key identifying the corresponding Log event.
\n expected to be exactely the same returned by the most recent call to gaiaInsertIntoSqlLog()
\param success expected to be TRUE if the SQL statement was succesfully executed.
\param errMsg expected to be the error message returned by SQLite on failure, NULL on success.
\sa gaiaInsertIntoSqlLog
\note this function completes an \b event inserted into the SQL Log, and
is expected to be invoked immediately \b after executing the SQL
statement itself.
*/
GAIAAUX_DECLARE void gaiaUpdateSqlLog (sqlite3 * sqlite,
sqlite3_int64 sqllog_pk, int success,
const char *errMsg);
/**
Creates a persistent MD5 checksum object
\return the handle of an MD5 checksum object, or NULL on failure
\sa gaiaFreeMD5Checksum, gaiaUpdateMD5Checksum, gaiaFinalizeMD5Checksum
\note you must properly destroy the MD5 object
when it isn't any longer used.
*/
GAIAAUX_DECLARE void *gaiaCreateMD5Checksum (void);
/**
Destroys an MD5 checksum object
\param md5 the handle of the MD5 checksum object (returned by
a previous call to gaiaCreateMD5Checksum).
\sa gaiaCreateMD5Checksum
*/
GAIAAUX_DECLARE void gaiaFreeMD5Checksum (void *md5);
/**
Updates an MD5 checksum object
\param md5 the handle of the MD5 checksum object (returned by
a previous call to gaiaCreateMD5Checksum).
\param blob an arbitrary sequence of binary data
\param blob_size the length (in bytes) of the binary data
\sa 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 gaiaUpdateMD5Checksum (void *md5,
const unsigned char *blob,
int blob_len);
/**
Return an MD5 checksum value
\param md5 the handle of the MD5 checksum object (returned by
a previous call to gaiaCreateMD5Checksum).
\return an hexadecimal text string representing the MD checksum:
NULL on failure
\sa 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.
\note gaiaFinalizeMD5Checksum will implicitly reset the MD5 object to its
initial state.
*/
GAIAAUX_DECLARE char *gaiaFinalizeMD5Checksum (void *md5);
#ifdef __cplusplus
}
#endif
#endif /* _GAIAAUX_H */
|