3 * =============================================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _dbi_included
41 * Contains information about an SQL driver.
47 * Contains information about a database connection.
53 * Contains information about an active query and its
58 * @handle Statement : Query
60 * Extends a Query Handle and can be used as a Query Handle.
61 * Statement Handles are for prepared queries and contain
62 * their own function for binding parameters. Statement
63 * Handles can be used instead of database Handles in a few
68 * Describes a database field fetch status.
72 DBVal_Error = 0, /**< Column number/field is invalid. */
73 DBVal_TypeMismatch = 1, /**< You cannot retrieve this data with this type. */
74 DBVal_Null = 2, /**< Field has no data (NULL) */
75 DBVal_Data = 3, /**< Field has data */
79 * Describes binding types.
83 DBBind_Int = 0, /**< Bind an integer. */
84 DBBind_Float = 1, /**< Bind a float. */
85 DBBind_String = 2, /**< Bind a string. */
89 * Threading priority level.
93 DBPrio_High = 0, /**< High priority. */
94 DBPrio_Normal = 1, /**< Normal priority. */
95 DBPrio_Low = 2, /**< Low priority. */
99 * Creates an SQL connection from a named configuration.
101 * @param confname Named configuration.
102 * @param persistent True to re-use a previous persistent connection if
103 * possible, false otherwise.
104 * @param error Error buffer.
105 * @param maxlength Maximum length of the error buffer.
106 * @return A database connection Handle, or INVALID_HANDLE on failure.
108 native Handle:SQL_Connect(const String:confname[], bool:persistent, String:error[], maxlength);
111 * Creates a default SQL connection.
113 * @param error Error buffer.
114 * @param maxlength Maximum length of the error buffer.
115 * @param persistent True to re-use a previous persistent connection
116 * if possible, false otherwise.
117 * @return A database connection Handle, or INVALID_HANDLE on failure.
119 stock Handle:SQL_DefConnect(String:error[], maxlength, bool:persistent=true)
121 return SQL_Connect("default", persistent, error, maxlength);
125 * Creates an SQL connection from specific parameters.
127 * @param driver Driver Handle, or INVALID_HANDLE for default.
128 * @param host Host name.
129 * @param user User name.
130 * @param pass User password.
131 * @param database Database name.
132 * @param error Error buffer.
133 * @param maxlength Maximum length of the error buffer.
134 * @param persistent True to re-use a previous persistent connection
135 * if possible, false otherwise.
136 * @param port Optional port to specify.
137 * @param maxTimeout Maximum timeout in seconds if applicable.
138 * @return A database connection Handle, or INVALID_HANDLE on failure.
139 * @error Invalid driver Handle other than INVALID_HANDLE.
141 native Handle:SQL_ConnectEx(Handle:driver,
145 const String:database[],
148 bool:persistent=true,
153 * Returns if a named configuration is present in databases.cfg.
155 * @param name Configuration name.
156 * @return True if it exists, false otherwise.
158 native bool:SQL_CheckConfig(const String:name[]);
161 * Returns a driver Handle from a name string.
163 * If the driver is not found, SourceMod will attempt
164 * to load an extension named dbi.<name>.ext.[dll|so].
166 * @param name Driver identification string, or an empty
167 * string to return the default driver.
168 * @return Driver Handle, or INVALID_HANDLE on failure.
170 native Handle:SQL_GetDriver(const String:name[]="");
173 * Reads the driver of an opened database.
175 * @param database Database Handle.
176 * @param ident Option buffer to store the identification string.
177 * @param ident_length Maximum length of the buffer.
178 * @return Driver Handle.
180 native Handle:SQL_ReadDriver(Handle:database, String:ident[]="", ident_length=0);
183 * Retrieves a driver's identification string.
185 * Example: "mysql", "sqlite"
187 * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
188 * @param ident Identification string buffer.
189 * @param maxlength Maximum length of the buffer.
191 * @error Invalid Handle other than INVALID_HANDLE.
193 native SQL_GetDriverIdent(Handle:driver, String:ident[], maxlength);
196 * Retrieves a driver's product string.
198 * Example: "MySQL", "SQLite"
200 * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
201 * @param product Product string buffer.
202 * @param maxlength Maximum length of the buffer.
204 * @error Invalid Handle other than INVALID_HANDLE.
206 native SQL_GetDriverProduct(Handle:driver, String:product[], maxlength);
209 * Returns the number of affected rows from the last query.
211 * @param hndl A database OR statement Handle.
212 * @return Number of rows affected by the last query.
213 * @error Invalid database or statement Handle.
215 native SQL_GetAffectedRows(Handle:hndl);
218 * Returns the last query's insertion id.
220 * @param hndl A database OR statement Handle.
221 * @return Last query's insertion id.
222 * @error Invalid database or statement Handle.
224 native SQL_GetInsertId(Handle:hndl);
227 * Returns the error reported by the last query.
229 * @param hndl A database OR statement Handle.
230 * @param error Error buffer.
231 * @param maxlength Maximum length of the buffer.
232 * @return True if there was an error, false otherwise.
233 * @error Invalid database or statement Handle.
235 native bool:SQL_GetError(Handle:hndl, String:error[], maxlength);
238 * Quotes a database string for literal insertion. This is not needed
239 * for binding strings in prepared statements.
241 * @param hndl A database Handle.
242 * @param string String to quote.
243 * @param buffer Buffer to store quoted string in.
244 * @param maxlength Maximum length of the buffer.
245 * @param written Optionally returns the number of bytes written.
246 * @return True on success, false if buffer is not big enough.
247 * The buffer must be at least 2*strlen(string)+1.
248 * @error Invalid database or statement Handle.
250 native bool:SQL_QuoteString(Handle:database, const String:string[], String:buffer[], maxlength, &written=0);
253 * Executes a query and ignores the result set.
255 * @param database A database Handle.
256 * @param query Query string.
257 * @return True if query succeeded, false otherwise. Use
258 * SQL_GetError to find the last error.
259 * @error Invalid database Handle.
261 native bool:SQL_FastQuery(Handle:database, const String:query[]);
264 * Executes a simple query and returns a new query Handle for
265 * receiving the results.
267 * @param database A database Handle.
268 * @param query Query string.
269 * @return A new Query Handle on success, INVALID_HANDLE
270 * otherwise. The Handle must be freed with CloseHandle().
271 * @error Invalid database Handle.
273 native Handle:SQL_Query(Handle:database, const String:query[]);
276 * Creates a new prepared statement query. Prepared statements can
277 * be executed any number of times. They can also have placeholder
278 * parameters, similar to variables, which can be bound safely and
279 * securely (for example, you do not need to quote bound strings).
281 * Statement handles will work in any function that accepts a Query handle.
283 * @param database A database Handle.
284 * @param query Query string.
285 * @param error Error buffer.
286 * @param maxlength Maximum size of the error buffer.
287 * @return A new statement Handle on success, INVALID_HANDLE
288 * otherwise. The Handle must be freed with CloseHandle().
289 * @error Invalid database Handle.
291 native Handle:SQL_PrepareQuery(Handle:database, const String:query[], String:error[], maxlength);
294 * Advances to the next set of results.
296 * In some SQL implementations, multiple result sets can exist on one query.
297 * This is possible in MySQL with simple queries when executing a CALL
298 * query. If this is the case, all result sets must be processed before
299 * another query is made.
301 * @param query A query Handle.
302 * @return True if there was another result set, false otherwise.
303 * @error Invalid query Handle.
305 native bool:SQL_FetchMoreResults(Handle:query);
308 * Returns whether or not a result set exists. This will
309 * return true even if 0 results were returned, but false
310 * on queries like UPDATE, INSERT, or DELETE.
312 * @param query A query (or statement) Handle.
313 * @return True if there is a result set, false otherwise.
314 * @error Invalid query Handle.
316 native bool:SQL_HasResultSet(Handle:query);
319 * Retrieves the number of rows in the last result set.
321 * @param query A query (or statement) Handle.
322 * @return Number of rows in the current result set.
323 * @error Invalid query Handle.
325 native SQL_GetRowCount(Handle:query);
328 * Retrieves the number of fields in the last result set.
330 * @param query A query (or statement) Handle.
331 * @return Number of fields in the current result set.
332 * @error Invalid query Handle.
334 native SQL_GetFieldCount(Handle:query);
337 * Retrieves the name of a field by index.
339 * @param query A query (or statement) Handle.
340 * @param field Field number (starting from 0).
341 * @param name Name buffer.
342 * @param maxlength Maximum length of the name buffer.
344 * @error Invalid query Handle, invalid field index, or
345 * no current result set.
347 native SQL_FieldNumToName(Handle:query, field, String:name[], maxlength);
350 * Retrieves a field index by name.
352 * @param query A query (or statement) Handle.
353 * @param name Name of the field (case sensitive).
354 * @param field Variable to store field index in.
355 * @return True if found, false if not found.
356 * @error Invalid query Handle or no current result set.
358 native bool:SQL_FieldNameToNum(Handle:query, const String:name[], &field);
361 * Fetches a row from the current result set. This must be
362 * successfully called before any results are fetched.
364 * If this function fails, SQL_MoreResults() can be used to
365 * tell if there was an error or the result set is finished.
367 * @param query A query (or statement) Handle.
368 * @return True if a row was fetched, false otherwise.
369 * @error Invalid query Handle.
371 native bool:SQL_FetchRow(Handle:query);
374 * Returns if there are more rows.
376 * @param query A query (or statement) Handle.
377 * @return True if there are more rows, false otherwise.
378 * @error Invalid query Handle.
380 native bool:SQL_MoreRows(Handle:query);
383 * Rewinds a result set back to the first result.
385 * @param query A query (or statement) Handle.
386 * @return True on success, false otherwise.
387 * @error Invalid query Handle or no current result set.
389 native bool:SQL_Rewind(Handle:query);
392 * Fetches a string from a field in the current row of a result set.
393 * If the result is NULL, an empty string will be returned. A NULL
394 * check can be done with the result parameter, or SQL_IsFieldNull().
396 * @param query A query (or statement) Handle.
397 * @param field The field index (starting from 0).
398 * @param buffer String buffer.
399 * @param maxlength Maximum size of the string buffer.
400 * @param result Optional variable to store the status of the return value.
401 * @return Number of bytes written.
402 * @error Invalid query Handle or field index, invalid
403 * type conversion requested from the database,
404 * or no current result set.
406 native SQL_FetchString(Handle:query, field, String:buffer[], maxlength, &DBResult:result=DBVal_Error);
409 * Fetches a float from a field in the current row of a result set.
410 * If the result is NULL, a value of 0.0 will be returned. A NULL
411 * check can be done with the result parameter, or SQL_IsFieldNull().
413 * @param query A query (or statement) Handle.
414 * @param field The field index (starting from 0).
415 * @param result Optional variable to store the status of the return value.
416 * @return A float value.
417 * @error Invalid query Handle or field index, invalid
418 * type conversion requested from the database,
419 * or no current result set.
421 native Float:SQL_FetchFloat(Handle:query, field, &DBResult:result=DBVal_Error);
424 * Fetches an integer from a field in the current row of a result set.
425 * If the result is NULL, a value of 0 will be returned. A NULL
426 * check can be done with the result parameter, or SQL_IsFieldNull().
428 * @param query A query (or statement) Handle.
429 * @param field The field index (starting from 0).
430 * @param result Optional variable to store the status of the return value.
431 * @return An integer value.
432 * @error Invalid query Handle or field index, invalid
433 * type conversion requested from the database,
434 * or no current result set.
436 native SQL_FetchInt(Handle:query, field, &DBResult:result=DBVal_Error);
439 * Returns whether a field's data in the current row of a result set is
440 * NULL or not. NULL is an SQL type which means "no data."
442 * @param query A query (or statement) Handle.
443 * @param field The field index (starting from 0).
444 * @return True if data is NULL, false otherwise.
445 * @error Invalid query Handle or field index, or no
446 * current result set.
448 native bool:SQL_IsFieldNull(Handle:query, field);
451 * Returns the length of a field's data in the current row of a result
452 * set. This only needs to be called for strings to determine how many
453 * bytes to use. Note that the return value does not include the null
456 * @param query A query (or statement) Handle.
457 * @param field The field index (starting from 0).
458 * @return Number of bytes for the field's data size.
459 * @error Invalid query Handle or field index or no
460 * current result set.
462 native SQL_FetchSize(Handle:query, field);
465 * Binds a parameter in a prepared statement to a given integer value.
467 * @param statement A statement (prepared query) Handle.
468 * @param param The parameter index (starting from 0).
469 * @param number The number to bind.
470 * @param signed True to bind the number as signed, false to
471 * bind it as unsigned.
473 * @error Invalid statement Handle or parameter index, or
476 native SQL_BindParamInt(Handle:statement, param, number, bool:signed=true);
479 * Binds a parameter in a prepared statement to a given float value.
481 * @param statement A statement (prepared query) Handle.
482 * @param param The parameter index (starting from 0).
483 * @param float The float number to bind.
485 * @error Invalid statement Handle or parameter index, or
488 native SQL_BindParamFloat(Handle:statement, param, Float:value);
491 * Binds a parameter in a prepared statement to a given string value.
493 * @param statement A statement (prepared query) Handle.
494 * @param param The parameter index (starting from 0).
495 * @param value The string to bind.
496 * @param copy Whether or not SourceMod should copy the value
497 * locally if necessary. If the string contents
498 * won't change before calling SQL_Execute(), this
499 * can be set to false for optimization.
501 * @error Invalid statement Handle or parameter index, or
504 native SQL_BindParamString(Handle:statement, param, const String:value[], bool:copy);
507 * Executes a prepared statement. All parameters must be bound beforehand.
509 * @param statement A statement (prepared query) Handle.
510 * @return True on success, false on failure.
511 * @error Invalid statement Handle.
513 native bool:SQL_Execute(Handle:statement);
516 * Locks a database so threading operations will not interrupt.
518 * If you are using a database Handle for both threading and non-threading,
519 * this MUST be called before doing any set of non-threading DB operations.
520 * Otherwise you risk corrupting the database driver's memory or network
523 * Leaving a lock on a database and then executing a threaded query results
524 * in a dead lock! Make sure to call SQL_UnlockDatabase()!
526 * If the lock cannot be acquired, the main thread will pause until the
527 * threaded operation has concluded.
529 * @param database A database Handle.
531 * @error Invalid database Handle.
533 native SQL_LockDatabase(Handle:database);
536 * Unlocks a database so threading operations may continue.
538 * @param database A database Handle.
540 * @error Invalid database Handle.
542 native SQL_UnlockDatabase(Handle:database);
545 * General callback for threaded SQL stuff.
547 * @param db Parent object of the Handle (or INVALID_HANDLE if none).
548 * @param hndl Handle to the child object (or INVALID_HANDLE if none).
549 * @param error Error string if there was an error. The error could be
550 * empty even if an error condition exists, so it is important
551 * to check the actual Handle value instead.
552 * @param data Data passed in via the original threaded invocation.
555 functag SQLTCallback public(Handle:owner, Handle:hndl, const String:error[], any:data);
558 * Tells whether two database handles both point to the same database
561 * @param hndl1 First database Handle.
562 * @param hndl2 Second database Handle.
563 * @return True if the Handles point to the same
564 * connection, false otherwise.
565 * @error Invalid Handle.
567 native bool:SQL_IsSameConnection(Handle:hndl1, Handle:hndl2);
570 * Connects to a database via a thread. This can be used instead of
571 * SQL_Connect() if you wish for non-blocking functionality.
573 * It is not necessary to use this to use threaded queries. However, if you
574 * don't (or you mix threaded/non-threaded queries), you should see
575 * SQL_LockDatabase().
577 * @param callback Callback; new Handle will be in hndl, owner is the driver.
578 * If no driver was found, the owner is INVALID_HANDLE.
579 * @param name Database name.
582 native SQL_TConnect(SQLTCallback:callback, const String:name[]="default", any:data=0);
585 * Executes a simple query via a thread. The query Handle is passed through
588 * The database Handle returned through the callback is always a new Handle,
589 * and if necessary, SQL_IsSameConnection() should be used to test against
592 * The query Handle returned through the callback is temporary and destroyed
593 * at the end of the callback. If you need to hold onto it, use CloneHandle().
595 * @param database A database Handle.
596 * @param callback Callback; database is in "owner" and the query Handle
597 * is passed in "hndl".
598 * @param query Query string.
599 * @param data Extra data value to pass to the callback.
600 * @param prio Priority queue to use.
602 * @error Invalid database Handle.
604 native SQL_TQuery(Handle:database, SQLTCallback:callback, const String:query[], any:data=0, DBPriority:prio=DBPrio_Normal);
