1 /* 2 * FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application 3 * Copyright (C) 2005-2014, Anthony Minessale II <anthm@freeswitch.org> 4 * 5 * Version: MPL 1.1 6 * 7 * The contents of this file are subject to the Mozilla Public License Version 8 * 1.1 (the "License"); you may not use this file except in compliance with 9 * the License. You may obtain a copy of the License at 10 * http://www.mozilla.org/MPL/ 11 * 12 * Software distributed under the License is distributed on an "AS IS" basis, 13 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 14 * for the specific language governing rights and limitations under the 15 * License. 16 * 17 * The Original Code is FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application 18 * 19 * The Initial Developer of the Original Code is 20 * Anthony Minessale II <anthm@freeswitch.org> 21 * Portions created by the Initial Developer are Copyright (C) 22 * the Initial Developer. All Rights Reserved. 23 * 24 * Contributor(s): 25 * 26 * Anthony Minessale II <anthm@freeswitch.org> 27 * Michael Jerris <mike@jerris.com> 28 * 29 * switch_core_db.h -- Sqlite wrapper and extensions Header 30 * 31 */ 32 /*! \file switch_core_db.h 33 \brief Core DB Header 34 */ 35 #ifndef SWITCH_CORE_DB_H 36 #define SWITCH_CORE_DB_H 37 38 SWITCH_BEGIN_EXTERN_C 39 /** 40 * @defgroup switch_sqlite_top Brought To You By SQLite 41 * @ingroup FREESWITCH 42 * @{ 43 */ 44 /** 45 * @defgroup switch_core_db Database Routines 46 * @ingroup switch_sqlite_top 47 * @{ 48 */ 49 /** 50 * Each open database is represented by an instance of the 51 * following opaque structure. 52 */ 53 typedef struct sqlite3 switch_core_db_t; 54 55 struct switch_coredb_handle { 56 switch_bool_t in_memory; 57 switch_core_db_t *handle; 58 }; 59 60 typedef struct sqlite3_stmt switch_core_db_stmt_t; 61 62 typedef int (*switch_core_db_callback_func_t) (void *pArg, int argc, char **argv, char **columnNames); 63 typedef int (*switch_core_db_err_callback_func_t) (void *pArg, const char *errmsg); 64 65 /* 66 ** These are special value for the destructor that is passed in as the 67 ** final argument to routines like switch_core_db_result_blob(). If the destructor 68 ** argument is SWITCH_CORE_DB_STATIC, it means that the content pointer is constant 69 ** and will never change. It does not need to be destroyed. The 70 ** SWITCH_CORE_DB_TRANSIENT value means that the content will likely change in 71 ** the near future and that the db should make its own private copy of 72 ** the content before returning. 73 ** 74 ** The typedef is necessary to work around problems in certain 75 ** C++ compilers. 76 */ 77 typedef void (*switch_core_db_destructor_type_t) (void *); 78 #define SWITCH_CORE_DB_STATIC ((switch_core_db_destructor_type_t)0) 79 #define SWITCH_CORE_DB_TRANSIENT ((switch_core_db_destructor_type_t)-1) 80 81 /** 82 * A function to close the database. 83 * 84 * Call this function with a pointer to a structure that was previously 85 * returned from switch_core_db_open() and the corresponding database will by closed. 86 * 87 * All SQL statements prepared using switch_core_db_prepare() 88 * must be deallocated using switch_core_db_finalize() before 89 * this routine is called. Otherwise, SWITCH_CORE_DB_BUSY is returned and the 90 * database connection remains open. 91 */ 92 SWITCH_DECLARE(int) switch_core_db_close(switch_core_db_t *db); 93 94 /** 95 * Open the database file "filename". The "filename" is UTF-8 96 * encoded. A switch_core_db_t* handle is returned in *Db, even 97 * if an error occurs. If the database is opened (or created) successfully, 98 * then SWITCH_CORE_DB_OK is returned. Otherwise an error code is returned. The 99 * switch_core_db_errmsg() routine can be used to obtain 100 * an English language description of the error. 101 * 102 * If the database file does not exist, then a new database is created. 103 * The encoding for the database is UTF-8. 104 * 105 * Whether or not an error occurs when it is opened, resources associated 106 * with the switch_core_db_t* handle should be released by passing it to 107 * switch_core_db_close() when it is no longer required. 108 */ 109 SWITCH_DECLARE(int) switch_core_db_open(const char *filename, switch_core_db_t **ppDb); 110 111 /** 112 Same as switch_core_db_open() but additionally allows SQLITE_OPEN_URI 113 */ 114 SWITCH_DECLARE(int) switch_core_db_open_v2(const char *filename, switch_core_db_t **ppDb); 115 116 /** 117 * ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(), 118 * even empty strings, are always zero-terminated. ^The return 119 * value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer. 120 * 121 * ^The object returned by [sqlite3_column_value()] is an 122 * [unprotected sqlite3_value] object. An unprotected sqlite3_value object 123 * may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. 124 * If the [unprotected sqlite3_value] object returned by 125 * [sqlite3_column_value()] is used in any other way, including calls 126 * to routines like [sqlite3_value_int()], [sqlite3_value_text()], 127 * or [sqlite3_value_bytes()], then the behavior is undefined. 128 * 129 * These routines attempt to convert the value where appropriate. ^For 130 * example, if the internal representation is FLOAT and a text result 131 * is requested, [sqlite3_snprintf()] is used internally to perform the 132 * conversion automatically. ^(The following table details the conversions 133 * that are applied: 134 * 135 * Internal Type Requested Type Conversion 136 * ------------- -------------- -------------------------- 137 * NULL INTEGER Result is 0 138 * NULL FLOAT Result is 0.0 139 * NULL TEXT Result is a NULL pointer 140 * NULL BLOB Result is a NULL pointer 141 * INTEGER FLOAT Convert from integer to float 142 * INTEGER TEXT ASCII rendering of the integer 143 * INTEGER BLOB Same as INTEGER->TEXT 144 * FLOAT INTEGER [CAST] to INTEGER 145 * FLOAT TEXT ASCII rendering of the float 146 * FLOAT BLOB [CAST] to BLOB 147 * TEXT INTEGER [CAST] to INTEGER 148 * TEXT FLOAT [CAST] to REAL 149 * TEXT BLOB No change 150 * BLOB INTEGER [CAST] to INTEGER 151 * BLOB FLOAT [CAST] to REAL 152 * BLOB TEXT Add a zero terminator if needed 153 * 154 * Return the value as UTF-8 text. 155 */ 156 SWITCH_DECLARE(const unsigned char *) switch_core_db_column_text(switch_core_db_stmt_t *stmt, int iCol); 157 158 /** 159 * The first parameter is a compiled SQL statement. This function returns 160 * the column heading for the Nth column of that statement, where N is the 161 * second function parameter. The string returned is UTF-8. 162 */ 163 SWITCH_DECLARE(const char *) switch_core_db_column_name(switch_core_db_stmt_t *stmt, int N); 164 165 /** 166 * Return the number of columns in the result set returned by the compiled 167 * SQL statement. This routine returns 0 if pStmt is an SQL statement 168 * that does not return data (for example an UPDATE). 169 */ 170 SWITCH_DECLARE(int) switch_core_db_column_count(switch_core_db_stmt_t *pStmt); 171 172 /** 173 * Return a pointer to a UTF-8 encoded string describing in english the 174 * error condition for the most recent switch_core_db_* API call. The returned 175 * string is always terminated by an 0x00 byte. 176 * 177 * The string "not an error" is returned when the most recent API call was 178 * successful. 179 */ 180 SWITCH_DECLARE(const char *) switch_core_db_errmsg(switch_core_db_t *db); 181 182 /** 183 * A function to executes one or more statements of SQL. 184 * 185 * If one or more of the SQL statements are queries, then 186 * the callback function specified by the 3rd parameter is 187 * invoked once for each row of the query result. This callback 188 * should normally return 0. If the callback returns a non-zero 189 * value then the query is aborted, all subsequent SQL statements 190 * are skipped and the switch_core_db_exec() function returns the SWITCH_CORE_DB_ABORT. 191 * 192 * The 4th parameter is an arbitrary pointer that is passed 193 * to the callback function as its first parameter. 194 * 195 * The 2nd parameter to the callback function is the number of 196 * columns in the query result. The 3rd parameter to the callback 197 * is an array of strings holding the values for each column. 198 * The 4th parameter to the callback is an array of strings holding 199 * the names of each column. 200 * 201 * The callback function may be NULL, even for queries. A NULL 202 * callback is not an error. It just means that no callback 203 * will be invoked. 204 * 205 * If an error occurs while parsing or evaluating the SQL (but 206 * not while executing the callback) then an appropriate error 207 * message is written into memory obtained from malloc() and 208 * *errmsg is made to point to that message. The calling function 209 * is responsible for freeing the memory that holds the error 210 * message. Use switch_core_db_free() for this. If errmsg==NULL, 211 * then no error message is ever written. 212 * 213 * The return value is is SWITCH_CORE_DB_OK if there are no errors and 214 * some other return code if there is an error. The particular 215 * return value depends on the type of error. 216 * 217 * If the query could not be executed because a database file is 218 * locked or busy, then this function returns SWITCH_CORE_DB_BUSY. (This 219 * behavior can be modified somewhat using the sswitch_core_db_busy_handler() 220 * and switch_core_db_busy_timeout() functions below.) 221 */ 222 SWITCH_DECLARE(int) switch_core_db_exec(switch_core_db_t *db, const char *sql, switch_core_db_callback_func_t callback, void *data, char **errmsg); 223 224 /** 225 * This function is called to delete a compiled 226 * SQL statement obtained by a previous call to switch_core_db_prepare(). 227 * If the statement was executed successfully, or 228 * not executed at all, then SWITCH_CORE_DB_OK is returned. If execution of the 229 * statement failed then an error code is returned. 230 * 231 * This routine can be called at any point during the execution of the 232 * virtual machine. If the virtual machine has not completed execution 233 * when this routine is called, that is like encountering an error or 234 * an interrupt. (See switch_core_db_interrupt().) Incomplete updates may be 235 * rolled back and transactions cancelled, depending on the circumstances, 236 * and the result code returned will be SWITCH_CORE_DB_ABORT. 237 */ 238 SWITCH_DECLARE(int) switch_core_db_finalize(switch_core_db_stmt_t *pStmt); 239 240 /** 241 * To execute an SQL query, it must first be compiled into a byte-code 242 * program using the following routine. 243 * 244 * The first parameter "db" is an SQLite database handle. The second 245 * parameter "zSql" is the statement to be compiled, encoded as 246 * UTF-8. If the next parameter, "nBytes", is less 247 * than zero, then zSql is read up to the first nul terminator. If 248 * "nBytes" is not less than zero, then it is the length of the string zSql 249 * in bytes (not characters). 250 * 251 * *pzTail is made to point to the first byte past the end of the first 252 * SQL statement in zSql. This routine only compiles the first statement 253 * in zSql, so *pzTail is left pointing to what remains uncompiled. 254 * 255 * *ppStmt is left pointing to a compiled SQL statement that can be 256 * executed using switch_core_db_step(). Or if there is an error, *ppStmt may be 257 * set to NULL. If the input text contained no SQL (if the input is and 258 * empty string or a comment) then *ppStmt is set to NULL. 259 * 260 * On success, SWITCH_CORE_DB_OK is returned. Otherwise an error code is returned. 261 */ 262 SWITCH_DECLARE(int) switch_core_db_prepare(switch_core_db_t *db, const char *zSql, int nBytes, switch_core_db_stmt_t **ppStmt, const char **pzTail); 263 264 /** 265 * After an SQL query has been compiled with a call to either 266 * switch_core_db_prepare(), then this function must be 267 * called one or more times to execute the statement. 268 * 269 * The return value will be either SWITCH_CORE_DB_BUSY, SWITCH_CORE_DB_DONE, 270 * SWITCH_CORE_DB_ROW, SWITCH_CORE_DB_ERROR, or SWITCH_CORE_DB_MISUSE. 271 * 272 * SWITCH_CORE_DB_BUSY means that the database engine attempted to open 273 * a locked database and there is no busy callback registered. 274 * Call switch_core_db_step() again to retry the open. 275 * 276 * SWITCH_CORE_DB_DONE means that the statement has finished executing 277 * successfully. switch_core_db_step() should not be called again on this virtual 278 * machine. 279 * 280 * If the SQL statement being executed returns any data, then 281 * SWITCH_CORE_DB_ROW is returned each time a new row of data is ready 282 * for processing by the caller. The values may be accessed using 283 * the switch_core_db_column_*() functions described below. switch_core_db_step() 284 * is called again to retrieve the next row of data. 285 * 286 * SWITCH_CORE_DB_ERROR means that a run-time error (such as a constraint 287 * violation) has occurred. switch_core_db_step() should not be called again on 288 * the VM. More information may be found by calling switch_core_db_errmsg(). 289 * 290 * SWITCH_CORE_DB_MISUSE means that the this routine was called inappropriately. 291 * Perhaps it was called on a virtual machine that had already been 292 * finalized or on one that had previously returned SWITCH_CORE_DB_ERROR or 293 * SWITCH_CORE_DB_DONE. Or it could be the case the the same database connection 294 * is being used simulataneously by two or more threads. 295 */ 296 SWITCH_DECLARE(int) switch_core_db_step(switch_core_db_stmt_t *stmt); 297 298 /** 299 * The switch_core_db_reset() function is called to reset a compiled SQL 300 * statement obtained by a previous call to switch_core_db_prepare() 301 * back to it's initial state, ready to be re-executed. 302 * Any SQL statement variables that had values bound to them using 303 * the switch_core_db_bind_*() API retain their values. 304 */ 305 SWITCH_DECLARE(int) switch_core_db_reset(switch_core_db_stmt_t *pStmt); 306 307 /** 308 * In the SQL strings input to switch_core_db_prepare(), 309 * one or more literals can be replace by parameters "?" or ":AAA" or 310 * "$VVV" where AAA is an identifer and VVV is a variable name according 311 * to the syntax rules of the TCL programming language. 312 * The value of these parameters (also called "host parameter names") can 313 * be set using the routines listed below. 314 * 315 * In every case, the first parameter is a pointer to the sqlite3_stmt 316 * structure returned from switch_core_db_prepare(). The second parameter is the 317 * index of the parameter. The first parameter as an index of 1. For 318 * named parameters (":AAA" or "$VVV") you can use 319 * switch_core_db_bind_parameter_index() to get the correct index value given 320 * the parameters name. If the same named parameter occurs more than 321 * once, it is assigned the same index each time. 322 * 323 * The switch_core_db_bind_* routine must be called before switch_core_db_step() after 324 * an switch_core_db_prepare() or sqlite3_reset(). Unbound parameterss are 325 * interpreted as NULL. 326 */ 327 SWITCH_DECLARE(int) switch_core_db_bind_int(switch_core_db_stmt_t *pStmt, int i, int iValue); 328 329 /** 330 * In the SQL strings input to switch_core_db_prepare(), 331 * one or more literals can be replace by parameters "?" or ":AAA" or 332 * "$VVV" where AAA is an identifer and VVV is a variable name according 333 * to the syntax rules of the TCL programming language. 334 * The value of these parameters (also called "host parameter names") can 335 * be set using the routines listed below. 336 * 337 * In every case, the first parameter is a pointer to the sqlite3_stmt 338 * structure returned from switch_core_db_prepare(). The second parameter is the 339 * index of the parameter. The first parameter as an index of 1. For 340 * named parameters (":AAA" or "$VVV") you can use 341 * switch_core_db_bind_parameter_index() to get the correct index value given 342 * the parameters name. If the same named parameter occurs more than 343 * once, it is assigned the same index each time. 344 * 345 * The switch_core_db_bind_* routine must be called before switch_core_db_step() after 346 * an switch_core_db_prepare() or sqlite3_reset(). Unbound parameterss are 347 * interpreted as NULL. 348 */ 349 SWITCH_DECLARE(int) switch_core_db_bind_int64(switch_core_db_stmt_t *pStmt, int i, int64_t iValue); 350 351 /** 352 * In the SQL strings input to switch_core_db_prepare(), 353 * one or more literals can be replace by parameters "?" or ":AAA" or 354 * "$VVV" where AAA is an identifer and VVV is a variable name according 355 * to the syntax rules of the TCL programming language. 356 * The value of these parameters (also called "host parameter names") can 357 * be set using the routines listed below. 358 * 359 * In every case, the first parameter is a pointer to the sqlite3_stmt 360 * structure returned from switch_core_db_prepare(). The second parameter is the 361 * index of the parameter. The first parameter as an index of 1. For 362 * named parameters (":AAA" or "$VVV") you can use 363 * switch_core_db_bind_parameter_index() to get the correct index value given 364 * the parameters name. If the same named parameter occurs more than 365 * once, it is assigned the same index each time. 366 * 367 * The fifth parameter to switch_core_db_bind_blob(), switch_core_db_bind_text(), and 368 * switch_core_db_bind_text16() is a destructor used to dispose of the BLOB or 369 * text after SQLite has finished with it. If the fifth argument is the 370 * special value SQLITE_STATIC, then the library assumes that the information 371 * is in static, unmanaged space and does not need to be freed. If the 372 * fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its 373 * own private copy of the data. 374 * 375 * The switch_core_db_bind_* routine must be called before switch_core_db_step() after 376 * an switch_core_db_prepare() or sqlite3_reset(). Unbound parameterss are 377 * interpreted as NULL. 378 */ 379 SWITCH_DECLARE(int) switch_core_db_bind_text(switch_core_db_stmt_t *pStmt, int i, const char *zData, int nData, switch_core_db_destructor_type_t xDel); 380 381 /** 382 * In the SQL strings input to switch_core_db_prepare(), 383 * one or more literals can be replace by parameters "?" or ":AAA" or 384 * "$VVV" where AAA is an identifer and VVV is a variable name according 385 * to the syntax rules of the TCL programming language. 386 * The value of these parameters (also called "host parameter names") can 387 * be set using the routines listed below. 388 * 389 * In every case, the first parameter is a pointer to the sqlite3_stmt 390 * structure returned from switch_core_db_prepare(). The second parameter is the 391 * index of the parameter. The first parameter as an index of 1. For 392 * named parameters (":AAA" or "$VVV") you can use 393 * sqlite3_bind_parameter_index() to get the correct index value given 394 * the parameters name. If the same named parameter occurs more than 395 * once, it is assigned the same index each time. 396 * 397 * The sqlite3_bind_* routine must be called before switch_core_db_step() after 398 * an switch_core_db_prepare() or switch_core_db_reset(). Unbound parameterss are 399 * interpreted as NULL. 400 */ 401 SWITCH_DECLARE(int) switch_core_db_bind_double(switch_core_db_stmt_t *pStmt, int i, double dValue); 402 403 /** 404 * Each entry in a table has a unique integer key. (The key is 405 * the value of the INTEGER PRIMARY KEY column if there is such a column, 406 * otherwise the key is generated at random. The unique key is always 407 * available as the ROWID, OID, or _ROWID_ column.) The following routine 408 * returns the integer key of the most recent insert in the database. 409 * 410 * This function is similar to the mysql_insert_id() function from MySQL. 411 */ 412 SWITCH_DECLARE(int64_t) switch_core_db_last_insert_rowid(switch_core_db_t *db); 413 414 /** 415 * This next routine is really just a wrapper around switch_core_db_exec(). 416 * Instead of invoking a user-supplied callback for each row of the 417 * result, this routine remembers each row of the result in memory 418 * obtained from malloc(), then returns all of the result after the 419 * query has finished. 420 * 421 * As an example, suppose the query result where this table: 422 * 423 * Name | Age 424 * ----------------------- 425 * Alice | 43 426 * Bob | 28 427 * Cindy | 21 428 * 429 * If the 3rd argument were &azResult then after the function returns 430 * azResult will contain the following data: 431 * 432 * azResult[0] = "Name"; 433 * azResult[1] = "Age"; 434 * azResult[2] = "Alice"; 435 * azResult[3] = "43"; 436 * azResult[4] = "Bob"; 437 * azResult[5] = "28"; 438 * azResult[6] = "Cindy"; 439 * azResult[7] = "21"; 440 * 441 * Notice that there is an extra row of data containing the column 442 * headers. But the *nrow return value is still 3. *ncolumn is 443 * set to 2. In general, the number of values inserted into azResult 444 * will be ((*nrow) + 1)*(*ncolumn). 445 * 446 * After the calling function has finished using the result, it should 447 * pass the result data pointer to switch_core_db_free_table() in order to 448 * release the memory that was malloc-ed. Because of the way the 449 * malloc() happens, the calling function must not try to call 450 * free() directly. Only switch_core_db_free_table() is able to release 451 * the memory properly and safely. 452 * 453 * The return value of this routine is the same as from switch_core_db_exec(). 454 */ 455 SWITCH_DECLARE(int) switch_core_db_get_table(switch_core_db_t *db, /* An open database */ 456 const char *sql, /* SQL to be executed */ 457 char ***resultp, /* Result written to a char *[] that this points to */ 458 int *nrow, /* Number of result rows written here */ 459 int *ncolumn, /* Number of result columns written here */ 460 char **errmsg /* Error msg written here */ 461 ); 462 463 /** 464 * Call this routine to free the memory that sqlite3_get_table() allocated. 465 */ 466 SWITCH_DECLARE(void) switch_core_db_free_table(char **result); 467 468 /** 469 * Call this routine to free the memory that switch_core_db_get_table() allocated. 470 */ 471 SWITCH_DECLARE(void) switch_core_db_free(char *z); 472 473 /** 474 * Call this routine to find the number of rows changed by the last statement. 475 */ 476 SWITCH_DECLARE(int) switch_core_db_changes(switch_core_db_t *db); 477 478 /** 479 * Call this routine to load an external extension 480 */ 481 SWITCH_DECLARE(int) switch_core_db_load_extension(switch_core_db_t *db, const char *extension); 482 483 /** Return values for switch_core_db_exec() and switch_core_db_step()*/ 484 #define SWITCH_CORE_DB_OK 0 /* Successful result */ 485 /* beginning-of-error-codes */ 486 #define SWITCH_CORE_DB_ERROR 1 /* SQL error or missing database */ 487 #define SWITCH_CORE_DB_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ 488 #define SWITCH_CORE_DB_PERM 3 /* Access permission denied */ 489 #define SWITCH_CORE_DB_ABORT 4 /* Callback routine requested an abort */ 490 #define SWITCH_CORE_DB_BUSY 5 /* The database file is locked */ 491 #define SWITCH_CORE_DB_LOCKED 6 /* A table in the database is locked */ 492 #define SWITCH_CORE_DB_NOMEM 7 /* A malloc() failed */ 493 #define SWITCH_CORE_DB_READONLY 8 /* Attempt to write a readonly database */ 494 #define SWITCH_CORE_DB_INTERRUPT 9 /* Operation terminated by switch_core_db_interrupt() */ 495 #define SWITCH_CORE_DB_IOERR 10 /* Some kind of disk I/O error occurred */ 496 #define SWITCH_CORE_DB_CORRUPT 11 /* The database disk image is malformed */ 497 #define SWITCH_CORE_DB_NOTFOUND 12 /* NOT USED. Table or record not found */ 498 #define SWITCH_CORE_DB_FULL 13 /* Insertion failed because database is full */ 499 #define SWITCH_CORE_DB_CANTOPEN 14 /* Unable to open the database file */ 500 #define SWITCH_CORE_DB_PROTOCOL 15 /* Database lock protocol error */ 501 #define SWITCH_CORE_DB_EMPTY 16 /* Database is empty */ 502 #define SWITCH_CORE_DB_SCHEMA 17 /* The database schema changed */ 503 #define SWITCH_CORE_DB_TOOBIG 18 /* NOT USED. Too much data for one row */ 504 #define SWITCH_CORE_DB_CONSTRAINT 19 /* Abort due to contraint violation */ 505 #define SWITCH_CORE_DB_MISMATCH 20 /* Data type mismatch */ 506 #define SWITCH_CORE_DB_MISUSE 21 /* Library used incorrectly */ 507 #define SWITCH_CORE_DB_NOLFS 22 /* Uses OS features not supported on host */ 508 #define SWITCH_CORE_DB_AUTH 23 /* Authorization denied */ 509 #define SWITCH_CORE_DB_FORMAT 24 /* Auxiliary database format error */ 510 #define SWITCH_CORE_DB_RANGE 25 /* 2nd parameter to switch_core_db_bind out of range */ 511 #define SWITCH_CORE_DB_NOTADB 26 /* File opened that is not a database file */ 512 #define SWITCH_CORE_DB_ROW 100 /* switch_core_db_step() has another row ready */ 513 #define SWITCH_CORE_DB_DONE 101 /* switch_core_db_step() has finished executing */ 514 /* end-of-error-codes */ 515 516 517 /** @} */ 518 /** @} */ 519 /** 520 * This routine is a variant of the "sprintf()" from the 521 * standard C library. The resulting string is written into memory 522 * obtained from malloc() so that there is never a possiblity of buffer 523 * overflow. This routine also implement some additional formatting 524 * options that are useful for constructing SQL statements. 525 * 526 * The strings returned by this routine should be freed by calling 527 * switch_core_db_free(). 528 * 529 * All of the usual printf formatting options apply. In addition, there 530 * is a "%q" option. %q works like %s in that it substitutes a null-terminated 531 * string from the argument list. But %q also doubles every '\'' character. 532 * %q is designed for use inside a string literal. By doubling each '\'' 533 * character it escapes that character and allows it to be inserted into 534 * the string. 535 * 536 * For example, so some string variable contains text as follows: 537 * 538 * char *zText = "It's a happy day!"; 539 * 540 * We can use this text in an SQL statement as follows: 541 * 542 * char *z = switch_core_db_mprintf("INSERT INTO TABLES('%q')", zText); 543 * switch_core_db_exec(db, z, callback1, 0, 0); 544 * switch_core_db_free(z); 545 * 546 * Because the %q format string is used, the '\'' character in zText 547 * is escaped and the SQL generated is as follows: 548 * 549 * INSERT INTO table1 VALUES('It''s a happy day!') 550 * 551 * This is correct. Had we used %s instead of %q, the generated SQL 552 * would have looked like this: 553 * 554 * INSERT INTO table1 VALUES('It's a happy day!'); 555 * 556 * This second example is an SQL syntax error. As a general rule you 557 * should always use %q instead of %s when inserting text into a string 558 * literal. 559 */ 560 561 SWITCH_DECLARE(char*)switch_sql_concat(void); 562 563 SWITCH_END_EXTERN_C 564 #endif 565 /* For Emacs: 566 * Local Variables: 567 * mode:c 568 * indent-tabs-mode:t 569 * tab-width:4 570 * c-basic-offset:4 571 * End: 572 * For VIM: 573 * vim:set softtabstop=4 shiftwidth=4 tabstop=4 noet: 574 */ 575