3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #if defined _dbi_included
24 * Contains information about an SQL driver.
30 * Contains information about a database connection.
36 * Contains information about an active query and its
41 * @handle Statement : Query
43 * Extends a Query Handle and can be used as a Query Handle.
44 * Statement Handles are for prepared queries and contain
45 * their own function for binding parameters. Statement
46 * Handles can be used instead of database Handles in a few
51 * Describes a database field fetch status.
55 DBVal_Error = 0, /**< Column number/field is invalid. */
56 DBVal_TypeMismatch = 1, /**< You cannot retrieve this data with this type. */
57 DBVal_Null = 2, /**< Field has no data (NULL) */
58 DBVal_Data = 3, /**< Field has data */
62 * Describes binding types.
66 DBBind_Int = 0, /**< Bind an integer. */
67 DBBind_Float = 1, /**< Bind a float. */
68 DBBind_String = 2, /**< Bind a string. */
72 * Threading priority level.
76 DBPrio_High = 0, /**< High priority. */
77 DBPrio_Normal = 1, /**< Normal priority. */
78 DBPrio_Low = 2, /**< Low priority. */
82 * Creates an SQL connection from a named configuration.
84 * @param confname Named configuration.
85 * @param persistent True to re-use a previous persistent connection if
86 * possible, false otherwise.
87 * @param error Error buffer.
88 * @param maxlength Maximum length of the error buffer.
89 * @return A database connection Handle, or INVALID_HANDLE on failure.
91 native Handle:SQL_Connect(const String:confname[], bool:persistent, String:error[], maxlength);
94 * Creates a default SQL connection.
96 * @param error Error buffer.
97 * @param maxlength Maximum length of the error buffer.
98 * @param persistent True to re-use a previous persistent connection
99 * if possible, false otherwise.
100 * @return A database connection Handle, or INVALID_HANDLE on failure.
102 stock Handle:SQL_DefConnect(String:error[], maxlength, bool:persistent=true)
104 return SQL_Connect("default", persistent, error, maxlength);
108 * Creates an SQL connection from specific parameters.
110 * @param driver Driver Handle, or INVALID_HANDLE for default.
111 * @param host Host name.
112 * @param user User name.
113 * @param pass User password.
114 * @param database Database name.
115 * @param error Error buffer.
116 * @param maxlength Maximum length of the error buffer.
117 * @param persistent True to re-use a previous persistent connection
118 * if possible, false otherwise.
119 * @param port Optional port to specify.
120 * @param maxTimeout Maximum timeout in seconds if applicable.
121 * @return A database connection Handle, or INVALID_HANDLE on failure.
122 * @error Invalid driver Handle other than INVALID_HANDLE.
124 native Handle:SQL_ConnectEx(Handle:driver,
128 const String:database[],
131 bool:persistent=true,
136 * Returns a driver Handle from a name string.
138 * If the driver is not found, SourceMod will attempt
139 * to load an extension named dbi.<name>.ext.[dll|so].
141 * @param name Driver identification string, or an empty
142 * string to return the default driver.
143 * @return Driver Handle, or INVALID_HANDLE on failure.
145 native Handle:SQL_GetDriver(const String:name[]="");
148 * Retrieves a driver's identification string.
150 * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
151 * @param ident Identification string buffer.
152 * @param maxlength Maximum length of the buffer.
154 * @error Invalid Handle other than INVALID_HANDLE.
156 native SQL_GetDriverIdent(Handle:driver, String:ident[], maxlength);
159 * Retrieves a driver's product string.
161 * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
162 * @param product Product string buffer.
163 * @param maxlength Maximum length of the buffer.
165 * @error Invalid Handle other than INVALID_HANDLE.
167 native SQL_GetDriverProduct(Handle:driver, String:product[], maxlength);
170 * Returns the number of affected rows from the last query.
172 * @param hndl A database OR statement Handle.
173 * @return Number of rows affected by the last query.
174 * @error Invalid database or statement Handle.
176 native SQL_GetAffectedRows(Handle:hndl);
179 * Returns the last query's insertion id.
181 * @param hndl A database OR statement Handle.
182 * @return Last query's insertion id.
183 * @error Invalid database or statement Handle.
185 native SQL_GetInsertId(Handle:hndl);
188 * Returns the error reported by the last query.
190 * @param hndl A database OR statement Handle.
191 * @param error Error buffer.
192 * @param maxlength Maximum length of the buffer.
193 * @return True if there was an error, false otherwise.
194 * @error Invalid database or statement Handle.
196 native bool:SQL_GetError(Handle:hndl, String:error[], maxlength);
199 * Quotes a database string for literal insertion. This is not needed
200 * for binding strings in prepared statements.
202 * @param hndl A database Handle.
203 * @param string String to quote.
204 * @param buffer Buffer to store quoted string in.
205 * @param maxlength Maximum length of the buffer.
206 * @param written Optionally returns the number of bytes written.
207 * @return True on success, false if buffer is not big enough.
208 * The buffer must be at least 2*strlen(string)+1.
209 * @error Invalid database or statement Handle.
211 native bool:SQL_QuoteString(Handle:database, const String:string[], String:buffer[], maxlength, &written=0);
214 * Executes a query and ignores the result set.
216 * @param database A database Handle.
217 * @param query Query string.
218 * @return True if query succeeded, false otherwise. Use
219 * SQL_GetError to find the last error.
220 * @error Invalid database Handle.
222 native bool:SQL_FastQuery(Handle:database, const String:query[]);
225 * Executes a simple query and returns a new query Handle for
226 * receiving the results.
228 * @param database A database Handle.
229 * @param query Query string.
230 * @return A new Query Handle on success, INVALID_HANDLE
231 * otherwise. The Handle must be freed with CloseHandle().
232 * @error Invalid database Handle.
234 native Handle:SQL_Query(Handle:database, const String:query[]);
237 * Creates a new prepared statement query. Prepared statements can
238 * be executed any number of times. They can also have placeholder
239 * parameters, similar to variables, which can be bound safely and
240 * securely (for example, you do not need to quote bound strings).
242 * Statement handles will work in any function that accepts a Query handle.
244 * @param database A database Handle.
245 * @param query Query string.
246 * @param error Error buffer.
247 * @param maxlength Maximum size of the error buffer.
248 * @return A new statement Handle on success, INVALID_HANDLE
249 * otherwise. The Handle must be freed with CloseHandle().
250 * @error Invalid database Handle.
252 native Handle:SQL_PrepareQuery(Handle:database, const String:query[], String:error[], maxlength);
255 * Advances to the next set of results.
257 * In some SQL implementations, multiple result sets can exist on one query.
258 * This is possible in MySQL with simple queries when executing a CALL
259 * query. If this is the case, all result sets must be processed before
260 * another query is made.
262 * @param query A query Handle.
263 * @return True if there was another result set, false otherwise.
264 * @error Invalid query Handle.
266 native bool:SQL_FetchMoreResults(Handle:query);
269 * Returns whether or not a result set exists. This will
270 * return true even if 0 results were returned, but false
271 * on queries like UPDATE, INSERT, or DELETE.
273 * @param query A query (or statement) Handle.
274 * @return True if there is a result set, false otherwise.
275 * @error Invalid query Handle.
277 native bool:SQL_HasResultSet(Handle:query);
280 * Retrieves the number of rows in the last result set.
282 * @param query A query (or statement) Handle.
283 * @return Number of rows in the current result set.
284 * @error Invalid query Handle.
286 native SQL_GetRowCount(Handle:query);
289 * Retrieves the number of fields in the last result set.
291 * @param query A query (or statement) Handle.
292 * @return Number of fields in the current result set.
293 * @error Invalid query Handle.
295 native SQL_GetFieldCount(Handle:query);
298 * Retrieves the name of a field by index.
300 * @param query A query (or statement) Handle.
301 * @param field Field number (starting from 0).
302 * @param name Name buffer.
303 * @param maxlength Maximum length of the name buffer.
305 * @error Invalid query Handle, invalid field index, or
306 * no current result set.
308 native SQL_FieldNumToName(Handle:query, field, String:name[], maxlength);
311 * Retrieves a field index by name.
313 * @param query A query (or statement) Handle.
314 * @param name Name of the field (case sensitive).
315 * @param field Variable to store field index in.
316 * @return True if found, false if not found.
317 * @error Invalid query Handle or no current result set.
319 native bool:SQL_FieldNameToNum(Handle:query, const String:name[], &field);
322 * Fetches a row from the current result set. This must be
323 * successfully called before any results are fetched.
325 * If this function fails, SQL_MoreResults() can be used to
326 * tell if there was an error or the result set is finished.
328 * @param query A query (or statement) Handle.
329 * @return True if a row was fetched, false otherwise.
330 * @error Invalid query Handle.
332 native bool:SQL_FetchRow(Handle:query);
335 * Returns if there are more rows.
337 * @param query A query (or statement) Handle.
338 * @return True if there are more rows, false otherwise.
339 * @error Invalid query Handle.
341 native bool:SQL_MoreRows(Handle:query);
344 * Rewinds a result set back to the first result.
346 * @param query A query (or statement) Handle.
347 * @return True on success, false otherwise.
348 * @error Invalid query Handle or no current result set.
350 native bool:SQL_Rewind(Handle:query);
353 * Fetches a string from a field in the current row of a result set.
354 * If the result is NULL, an empty string will be returned. A NULL
355 * check can be done with the result parameter, or SQL_IsFieldNull().
357 * @param query A query (or statement) Handle.
358 * @param field The field index (starting from 0).
359 * @param buffer String buffer.
360 * @param maxlength Maximum size of the string buffer.
361 * @param result Optional variable to store the status of the return value.
362 * @return Number of bytes written.
363 * @error Invalid query Handle or field index, invalid
364 * type conversion requested from the database,
365 * or no current result set.
367 native SQL_FetchString(Handle:query, field, String:buffer[], maxlength, &DBResult:result=DBVal_Error);
370 * Fetches a float from a field in the current row of a result set.
371 * If the result is NULL, a value of 0.0 will be returned. A NULL
372 * check can be done with the result parameter, or SQL_IsFieldNull().
374 * @param query A query (or statement) Handle.
375 * @param field The field index (starting from 0).
376 * @param result Optional variable to store the status of the return value.
377 * @return A float value.
378 * @error Invalid query Handle or field index, invalid
379 * type conversion requested from the database,
380 * or no current result set.
382 native Float:SQL_FetchFloat(Handle:query, field, &DBResult:result=DBVal_Error);
385 * Fetches an integer from a field in the current row of a result set.
386 * If the result is NULL, a value of 0 will be returned. A NULL
387 * check can be done with the result parameter, or SQL_IsFieldNull().
389 * @param query A query (or statement) Handle.
390 * @param field The field index (starting from 0).
391 * @param result Optional variable to store the status of the return value.
392 * @return An integer value.
393 * @error Invalid query Handle or field index, invalid
394 * type conversion requested from the database,
395 * or no current result set.
397 native SQL_FetchInt(Handle:query, field, &DBResult:result=DBVal_Error);
400 * Returns whether a field's data in the current row of a result set is
401 * NULL or not. NULL is an SQL type which means "no data."
403 * @param query A query (or statement) Handle.
404 * @param field The field index (starting from 0).
405 * @return True if data is NULL, false otherwise.
406 * @error Invalid query Handle or field index, or no
407 * current result set.
409 native bool:SQL_IsFieldNull(Handle:query, field);
412 * Returns the length of a field's data in the current row of a result
413 * set. This only needs to be called for strings to determine how many
414 * bytes to use. Note that the return value does not include the null
417 * @param query A query (or statement) Handle.
418 * @param field The field index (starting from 0).
419 * @return Number of bytes for the field's data size.
420 * @error Invalid query Handle or field index or no
421 * current result set.
423 native SQL_FetchSize(Handle:query, field);
426 * Binds a parameter in a prepared statement to a given integer value.
428 * @param statement A statement (prepared query) Handle.
429 * @param param The parameter index (starting from 0).
430 * @param number The number to bind.
431 * @param signed True to bind the number as signed, false to
432 * bind it as unsigned.
434 * @error Invalid statement Handle or parameter index, or
437 native SQL_BindParamInt(Handle:statement, param, number, bool:signed=true);
440 * Binds a parameter in a prepared statement to a given float value.
442 * @param statement A statement (prepared query) Handle.
443 * @param param The parameter index (starting from 0).
444 * @param float The float number to bind.
446 * @error Invalid statement Handle or parameter index, or
449 native SQL_BindParamFloat(Handle:statement, param, Float:value);
452 * Binds a parameter in a prepared statement to a given string value.
454 * @param statement A statement (prepared query) Handle.
455 * @param param The parameter index (starting from 0).
456 * @param value The string to bind.
457 * @param copy Whether or not SourceMod should copy the value
458 * locally if necessary. If the string contents
459 * won't change before calling SQL_Execute(), this
460 * can be set to false for optimization.
462 * @error Invalid statement Handle or parameter index, or
465 native SQL_BindParamString(Handle:statement, param, const String:value[], bool:copy);
468 * Executes a prepared statement. All parameters must be bound beforehand.
470 * @param statement A statement (prepared query) Handle.
471 * @return True on success, false on failure.
472 * @error Invalid statement Handle.
474 native bool:SQL_Execute(Handle:statement);
477 * Locks a database so threading operations will not interrupt.
479 * If you are using a database Handle for both threading and non-threading,
480 * this MUST be called before doing any set of non-threading DB operations.
481 * Otherwise you risk corrupting the database driver's memory or network
484 * Leaving a lock on a database and then executing a threaded query results
485 * in a dead lock! Make sure to call SQL_UnlockDatabase()!
487 * If the lock cannot be acquired, the main thread will pause until the
488 * threaded operation has concluded.
490 * @param database A database Handle.
492 * @error Invalid database Handle.
494 native SQL_LockDatabase(Handle:database);
497 * Unlocks a database so threading operations may continue.
499 * @param database A database Handle.
501 * @error Invalid database Handle.
503 native SQL_UnlockDatabase(Handle:database);
506 * General callback for threaded SQL stuff.
508 * @param db Parent object of the Handle (or INVALID_HANDLE if none).
509 * @param hndl Handle to the child object (or INVALID_HANDLE if none).
510 * @param error Error string, if any.
513 functag SQLTCallback public(Handle:owner, Handle:hndl, const String:error[], any:data);
516 * Tells whether two database handles both point to the same database
519 * @param hndl1 First database Handle.
520 * @param hndl2 Second database Handle.
521 * @return True if the Handles point to the same
522 * connection, false otherwise.
523 * @error Invalid Handle.
525 native bool:SQL_IsSameConnection(Handle:hndl1, Handle:hndl2);
528 * Connects to a database via a thread. This can be used instead of
529 * SQL_Connect() if you wish for non-blocking functionality.
531 * It is not necessary to use this to use threaded queries. However, if you
532 * don't (or you mix threaded/non-threaded queries), you should see
533 * SQL_LockDatabase().
535 * @param callback Callback; new Handle will be in hndl, owner is the driver.
536 * If no driver was found, the owner is INVALID_HANDLE.
537 * @param name Database name.
540 native SQL_TConnect(SQLTCallback:callback, const String:name[]="default");
543 * Executes a simple query via a thread. The query Handle is passed through
546 * The database Handle returned through the callback is always a new Handle,
547 * and if necessary, SQL_IsSameConnection() should be used to test against
550 * The query Handle returned through the callback is temporary and destroyed
551 * at the end of the callback. If you need to hold onto it, use CloneHandle().
553 * @param database A database Handle.
554 * @param callback Callback; database is in "owner" and the query Handle
555 * is passed in "hndl".
556 * @param query Query string.
557 * @param data Extra data value to pass to the callback.
558 * @param prio Priority queue to use.
560 * @error Invalid database Handle.
562 native SQL_TQuery(Handle:database, SQLTCallback:callback, const String:query[], any:data=0, DBPriority:prio=DBPrio_Normal);
