00001 /** 00002 * vim: set ts=4 : 00003 * ============================================================================= 00004 * SourceMod 00005 * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved. 00006 * ============================================================================= 00007 * 00008 * This program is free software; you can redistribute it and/or modify it under 00009 * the terms of the GNU General Public License, version 3.0, as published by the 00010 * Free Software Foundation. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU General Public License along with 00018 * this program. If not, see <http://www.gnu.org/licenses/>. 00019 * 00020 * As a special exception, AlliedModders LLC gives you permission to link the 00021 * code of this program (as well as its derivative works) to "Half-Life 2," the 00022 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software 00023 * by the Valve Corporation. You must obey the GNU General Public License in 00024 * all respects for all other code used. Additionally, AlliedModders LLC grants 00025 * this exception to all derivative works. AlliedModders LLC defines further 00026 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), 00027 * or <http://www.sourcemod.net/license.php>. 00028 * 00029 * Version: $Id$ 00030 */ 00031 00032 #ifndef _INCLUDE_SOURCEMOD_INTERFACE_DBDRIVER_H_ 00033 #define _INCLUDE_SOURCEMOD_INTERFACE_DBDRIVER_H_ 00034 00035 #include <IShareSys.h> 00036 #include <IHandleSys.h> 00037 #include <string.h> 00038 00039 /** 00040 * @file IDBDriver.h 00041 * @brief Defines interfaces for interacting with relational databases. 00042 */ 00043 00044 #define SMINTERFACE_DBI_NAME "IDBI" 00045 #define SMINTERFACE_DBI_VERSION 8 00046 00047 namespace SourceMod 00048 { 00049 /** 00050 * @brief Describes a database field value. 00051 */ 00052 enum DBResult 00053 { 00054 DBVal_Error = 0, /**< Column number/field is invalid */ 00055 DBVal_TypeMismatch = 1, /**< You cannot retrieve this data with this type */ 00056 DBVal_Null = 2, /**< Field has no data (NULL) */ 00057 DBVal_Data = 3, /**< Field has data */ 00058 }; 00059 00060 /** 00061 * @brief Describes a primitive database type. 00062 */ 00063 enum DBType 00064 { 00065 DBType_Unknown = 0, /**< Type could not be inferred */ 00066 DBType_String, /**< NULL-terminated string (variable length) */ 00067 DBType_Blob, /**< Raw binary data (variable length) */ 00068 DBType_Integer, /**< 4-byte signed integer */ 00069 DBType_Float, /**< 4-byte floating point */ 00070 DBType_NULL, /**< NULL (no data) */ 00071 /* --------- */ 00072 DBTypes_TOTAL, /**< Total number of database types known */ 00073 }; 00074 00075 /** 00076 * @brief Represents a one database result row. 00077 * 00078 * Note that type mismatches will only occur when type safety is being 00079 * enforced. So far this is only the case for prepared statements in 00080 * MySQL and SQLite. 00081 * 00082 * Also, it is worth noting that retrieving as raw data will never cause a 00083 * type mismatch. 00084 */ 00085 class IResultRow 00086 { 00087 public: 00088 /** 00089 * @brief Retrieves a database field result as a string. 00090 * 00091 * For NULL values, the resulting string pointer will be non-NULL but 00092 * empty. The pointer returned will become invalid after advancing to 00093 * the next row. 00094 * 00095 * @param columnId Column to use, starting from 0. 00096 * @param pString Pointer to store a pointer to the string. 00097 * @param length Optional pointer to store the string length. 00098 * @return A DBResult return code. 00099 */ 00100 virtual DBResult GetString(unsigned int columnId, const char **pString, size_t *length) =0; 00101 00102 /** 00103 * @brief Retrieves a database field result as a string, using a 00104 * user-supplied buffer. If the field is NULL, an empty string 00105 * will be copied. 00106 * 00107 * @param columnId Column to use, starting from 0. 00108 * @param buffer Buffer to store string in. 00109 * @param maxlength Maximum length of the buffer. 00110 * @param written Optional pointer to store the number of bytes 00111 * written, excluding the null terminator. 00112 * @return A DBResult return code. 00113 */ 00114 virtual DBResult CopyString(unsigned int columnId, 00115 char *buffer, 00116 size_t maxlength, 00117 size_t *written) =0; 00118 00119 /** 00120 * @brief Retrieves a database field result as a float. 00121 * 00122 * For NULL entries, the returned float value will be 0.0. 00123 * 00124 * @param columnId Column to use, starting from 0. 00125 * @param pFloat Pointer to a floating point number to set. 00126 * @return A DBResult return code. 00127 */ 00128 virtual DBResult GetFloat(unsigned int columnId, float *pFloat) =0; 00129 00130 /** 00131 * @brief Retrieves a database field result as an integer. 00132 * 00133 * For NULL entries, the returned integer value will be 0. 00134 * 00135 * @param columnId Column to use, starting from 0. 00136 * @param pInt Pointer to an integer number to set. 00137 * @return A DBResult return code. 00138 */ 00139 virtual DBResult GetInt(unsigned int columnId, int *pInt) =0; 00140 00141 /** 00142 * @brief Returns whether or not a field is NULL. 00143 * 00144 * @param columnId Column to use, starting from 0. 00145 * @return True if field is NULL, false otherwise. 00146 */ 00147 virtual bool IsNull(unsigned int columnId) =0; 00148 00149 /** 00150 * @brief Returns the size of a field (text/raw/blob) in bytes. 00151 * For strings, this returned size will not include the null 00152 * terminator. 00153 * 00154 * When used on fields that are not of variable length, 00155 * the size returned will be the number of bytes required 00156 * to store the internal data. Note that the data size 00157 * will correspond to the ACTUAL data type, not the 00158 * COLUMN type. 00159 * 00160 * @param columnId Column to use, starting from 0. 00161 * @return Number of bytes required to store 00162 * the data, or 0 on failure. 00163 */ 00164 virtual size_t GetDataSize(unsigned int columnId) =0; 00165 00166 /** 00167 * @brief Retrieves field data as a raw bitstream. The pointer returned 00168 * will become invalid after advancing to the next row. 00169 * 00170 * @param columnId Column to use, starting from 0. 00171 * @param pData Pointer to store the raw bit stream. If the 00172 * data is NULL, a NULL pointer will be returned. 00173 * @param length Pointer to store the data length. 00174 * @return A DBResult return code. 00175 */ 00176 virtual DBResult GetBlob(unsigned int columnId, const void **pData, size_t *length) =0; 00177 00178 /** 00179 * @brief Copies field data as a raw bitstream. 00180 * 00181 * @param columnId Column to use, starting from 0. 00182 * @param buffer Pointer to copy the data to. If the data is 00183 * NULL, no data will be copied. 00184 * @param maxlength Maximum length of the buffer. 00185 * @param written Optional pointer to store the number of bytes 00186 * written. 00187 * @return A DBResult return code. 00188 */ 00189 virtual DBResult CopyBlob(unsigned int columnId, void *buffer, size_t maxlength, size_t *written) =0; 00190 }; 00191 00192 /** 00193 * @brief Describes a set of database results. 00194 */ 00195 class IResultSet 00196 { 00197 public: 00198 /** 00199 * @brief Returns the number of rows in the set. 00200 * 00201 * @return Number of rows in the set. 00202 */ 00203 virtual unsigned int GetRowCount() =0; 00204 00205 /** 00206 * @brief Returns the number of fields in the set. 00207 * 00208 * @return Number of fields in the set. 00209 */ 00210 virtual unsigned int GetFieldCount() =0; 00211 00212 /** 00213 * @brief Converts a column number to a column name. 00214 * 00215 * @param columnId Column to use, starting from 0. 00216 * @return Pointer to column name, or NULL if not found. 00217 */ 00218 virtual const char *FieldNumToName(unsigned int columnId) =0; 00219 00220 /** 00221 * @brief Converts a column name to a column id. 00222 * 00223 * @param name Column name (case sensitive). 00224 * @param columnId Pointer to store the column id. If the 00225 * name is not found, the value will be 00226 * undefined. 00227 * @return True on success, false if not found. 00228 */ 00229 virtual bool FieldNameToNum(const char *name, unsigned int *columnId) =0; 00230 00231 /** 00232 * @brief Returns if there is still data in the result set. 00233 * 00234 * @return False if there is more data to be read, 00235 * true, otherwise. 00236 */ 00237 virtual bool MoreRows() =0; 00238 00239 /** 00240 * @brief Returns a pointer to the current row and advances 00241 * the internal row pointer/counter to the next row available. 00242 * 00243 * @return IResultRow pointer to the current row, 00244 * or NULL if there is no more data. 00245 */ 00246 virtual IResultRow *FetchRow() =0; 00247 00248 /** 00249 * @brief Returns a pointer to the current row. 00250 * 00251 * @return IResultRow pointer to the current row, 00252 * or NULL if the current row is invalid. 00253 */ 00254 virtual IResultRow *CurrentRow() =0; 00255 00256 /** 00257 * @brief Rewinds back to the beginning of the row iteration. 00258 * 00259 * @return True on success, false otherwise. 00260 */ 00261 virtual bool Rewind() =0; 00262 00263 /** 00264 * @brief Returns a field's type as it should be interpreted 00265 * by the user. 00266 * 00267 * @param field Field number (starting from 0). 00268 * @return A DBType value. 00269 */ 00270 virtual DBType GetFieldType(unsigned int field) =0; 00271 00272 /** 00273 * @brief Returns a field's type as it will be interpreted 00274 * by the GetDataSize() function. For example, MySQL 00275 * for non-prepared queries will store all results as 00276 * strings internally. 00277 * 00278 * @param field Field number (starting from 0). 00279 * @return A DBType value. 00280 */ 00281 virtual DBType GetFieldDataType(unsigned int field) =0; 00282 }; 00283 00284 class IDBDriver; 00285 00286 class IQuery 00287 { 00288 public: 00289 /** 00290 * @brief Returns a pointer to the current result set, if any. 00291 * 00292 * @return An IResultSet pointer on success, 00293 * NULL if no result set exists. 00294 */ 00295 virtual IResultSet *GetResultSet() =0; 00296 00297 /** 00298 * @brief Advances to the next result set if one exists. This 00299 * is for checking for MORE result sets, and should not be used 00300 * on the first result set. 00301 * 00302 * Multiple results only happen in certain cases, such as CALLing 00303 * stored procedure that have a SELECTs, where MySQL will return 00304 * both the CALL status and one or more SELECT result sets. If 00305 * you do not process these results, they will be automatically 00306 * processed for you. However, the behaviour of creating a new 00307 * query from the same connection while results are left 00308 * unprocessed is undefined, and may result in a dropped 00309 * connection. Therefore, process all extra results or destroy the 00310 * IQuery pointer before starting a new query. 00311 * 00312 * Again, this only happens in very specific cases, so there is 00313 * no need to call this for normal queries. 00314 * 00315 * After calling this function, GetResultSet() must be called 00316 * again to return the result set. The previous result set 00317 * is automatically destroyed and will be unusable. 00318 * 00319 * @return True if another result set is 00320 * available, false otherwise. 00321 */ 00322 virtual bool FetchMoreResults() =0; 00323 00324 /** 00325 * @brief Frees resources created by this query. 00326 */ 00327 virtual void Destroy() =0; 00328 }; 00329 00330 class IPreparedQuery : public IQuery 00331 { 00332 public: 00333 /** 00334 * @brief Binds an integer parameter. 00335 * 00336 * @param param Parameter index, starting from 0. 00337 * @param num Number to bind as a value. 00338 * @param signd True to write as signed, false to write as 00339 * unsigned. 00340 * @return True on success, false otherwise. 00341 */ 00342 virtual bool BindParamInt(unsigned int param, int num, bool signd=true) =0; 00343 00344 /** 00345 * @brief Binds a float parameter. 00346 * 00347 * @param param Parameter index, starting from 0. 00348 * @param f Float to bind as a value. 00349 * @return True on success, false otherwise. 00350 */ 00351 virtual bool BindParamFloat(unsigned int param, float f) =0; 00352 00353 /** 00354 * @brief Binds an SQL NULL type as a parameter. 00355 * 00356 * @param param Parameter index, starting from 0. 00357 * @return True on success, false otherwise. 00358 */ 00359 virtual bool BindParamNull(unsigned int param) =0; 00360 00361 /** 00362 * @brief Binds a string as a parameter. 00363 * 00364 * @param param Parameter index, starting from 0. 00365 * @param text Pointer to a null-terminated string. 00366 * @param copy If true, the pointer is assumed to be 00367 * volatile and a temporary copy may be 00368 * made for safety. 00369 * @return True on success, false otherwise. 00370 */ 00371 virtual bool BindParamString(unsigned int param, const char *text, bool copy) =0; 00372 00373 /** 00374 * @brief Binds a blob of raw data as a parameter. 00375 * 00376 * @param param Parameter index, starting from 0. 00377 * @param data Pointer to a blob of memory. 00378 * @param length Number of bytes to copy. 00379 * @param copy If true, the pointer is assumed to be 00380 * volatile and a temporary copy may be 00381 * made for safety. 00382 * @return True on success, false otherwise. 00383 */ 00384 virtual bool BindParamBlob(unsigned int param, 00385 const void *data, 00386 size_t length, 00387 bool copy) =0; 00388 00389 /** 00390 * @brief Executes the query with the currently bound parameters. 00391 00392 * @return True on success, false otherwise. 00393 */ 00394 virtual bool Execute() =0; 00395 00396 /** 00397 * @brief Returns the last error message from this statement. 00398 * 00399 * @param errCode Optional pointer to store the driver-specific 00400 * error code. 00401 * @return Error message string. 00402 */ 00403 virtual const char *GetError(int *errCode=NULL) =0; 00404 00405 /** 00406 * @brief Number of rows affected by the last execute. 00407 * 00408 * @return Number of rows affected by the last execute. 00409 */ 00410 virtual unsigned int GetAffectedRows() =0; 00411 00412 /** 00413 * @brief Retrieves the last insert ID on this database connection. 00414 * 00415 * @return Row insertion ID of the last execute, if any. 00416 */ 00417 virtual unsigned int GetInsertID() =0; 00418 }; 00419 00420 class IDBDriver; 00421 00422 /** 00423 * @brief Encapsulates a database connection. 00424 */ 00425 class IDatabase 00426 { 00427 public: 00428 /** 00429 * @brief Disconnects the database and frees its associated memory. 00430 * Note that the actual object will not be freed until all open 00431 * references have been closed. 00432 * 00433 * It is guaranteed that an IDatabase pointer won't be destroyed until 00434 * all open IQuery or IPreparedQuery pointers are closed. 00435 * 00436 * This function is thread safe. 00437 * 00438 * @return True if object was destroyed, false if 00439 * references are remaining. 00440 */ 00441 virtual bool Close() =0; 00442 00443 /** 00444 * @brief Error code and string returned by the last operation on this 00445 * connection. 00446 * 00447 * This function is not thread safe and must be included in any locks. 00448 * 00449 * @param errorCode Optional pointer to retrieve an error code. 00450 * @return Error string pointer (empty if none). 00451 */ 00452 virtual const char *GetError(int *errorCode=NULL) =0; 00453 00454 /** 00455 * @brief Prepares and executes a query in one step, and discards 00456 * any return data. 00457 * 00458 * This function is not thread safe and must be included in any locks. 00459 * 00460 * @param query Query string. 00461 * @return True on success, false otherwise. 00462 */ 00463 virtual bool DoSimpleQuery(const char *query) =0; 00464 00465 /** 00466 * @brief Prepares and executes a query in one step, and returns 00467 * the resultant data set. 00468 * 00469 * Note: If a query contains more than one result set, each 00470 * result set must be processed before a new query is started. 00471 * 00472 * This function is not thread safe and must be included in any locks. 00473 * 00474 * @param query Query string. 00475 * @return IQuery pointer on success, NULL otherwise. 00476 */ 00477 virtual IQuery *DoQuery(const char *query) =0; 00478 00479 /** 00480 * @brief Prepares a query statement for multiple executions and/or 00481 * binding marked parameters (? in MySQL/sqLite, $n in PostgreSQL). 00482 * 00483 * This function is not thread safe and must be included in any locks. 00484 * 00485 * @param query Query string. 00486 * @param error Error buffer. 00487 * @param maxlength Maximum length of the error buffer. 00488 * @param errCode Optional pointer to store a driver-specific error code. 00489 * @return IPreparedQuery pointer on success, NULL 00490 * otherwise. 00491 */ 00492 virtual IPreparedQuery *PrepareQuery(const char *query, char *error, size_t maxlength, int *errCode=NULL) =0; 00493 00494 /** 00495 * Quotes a string for insertion into a query. 00496 * 00497 * @param str Source string. 00498 * @param buffer Buffer to store new string (should not overlap source string). 00499 * @param maxlen Maximum length of the output buffer. 00500 * @param newSize Pointer to store the output size. 00501 * @return True on success, false if the output buffer is not big enough. 00502 * If not big enough, the required buffer size is passed through 00503 * newSize. 00504 */ 00505 virtual bool QuoteString(const char *str, char buffer[], size_t maxlen, size_t *newSize) =0; 00506 00507 /** 00508 * @brief Number of rows affected by the last execute. 00509 * 00510 * This function is not thread safe and must be included in any locks. 00511 * 00512 * @return Number of rows affected by the last execute. 00513 */ 00514 virtual unsigned int GetAffectedRows() =0; 00515 00516 /** 00517 * @brief Retrieves the last insert ID on this database connection. 00518 * 00519 * This function is not thread safe and must be included in any locks. 00520 * 00521 * @return Row insertion ID of the last execute, if any. 00522 */ 00523 virtual unsigned int GetInsertID() =0; 00524 00525 /** 00526 * @brief Locks the database for an atomic query+retrieval operation. 00527 * 00528 * @return True on success, false if not supported. 00529 */ 00530 virtual bool LockForFullAtomicOperation() =0; 00531 00532 /** 00533 * @brief Unlocks a locked atomic fetch. 00534 */ 00535 virtual void UnlockFromFullAtomicOperation() =0; 00536 00537 /** 00538 * @brief Increases the reference count on the database. 00539 * 00540 * This function is thread safe. 00541 */ 00542 virtual void IncReferenceCount() =0; 00543 00544 /** 00545 * @brief Returns the parent driver. 00546 * 00547 * This function is thread safe. 00548 */ 00549 virtual IDBDriver *GetDriver() =0; 00550 00551 /** 00552 * @brief Prepares and executes a binary query in one step, and discards 00553 * any return data. 00554 * 00555 * This function is not thread safe and must be included in any locks. 00556 * 00557 * @param query Query string. 00558 * @param length Length of query string. 00559 * @return True on success, false otherwise. 00560 */ 00561 virtual bool DoSimpleQueryEx(const char *query, size_t len) =0; 00562 00563 /** 00564 * @brief Prepares and executes a binary query in one step, and returns 00565 * the resultant data set. 00566 * 00567 * Note: If a query contains more than one result set, each 00568 * result set must be processed before a new query is started. 00569 * 00570 * This function is not thread safe and must be included in any locks. 00571 * 00572 * @param query Query string. 00573 * @return IQuery pointer on success, NULL otherwise. 00574 */ 00575 virtual IQuery *DoQueryEx(const char *query, size_t len) =0; 00576 00577 /** 00578 * @brief Retrieves the number of affected rows from the last execute of 00579 * the given query 00580 * 00581 * Note: This can only accept queries from this driver. 00582 * 00583 * This function is not thread safe and must be included in any locks. 00584 * 00585 * @param query IQuery object from this driver 00586 * @return Rows affected from last execution of this query, 00587 * if applicable. 00588 */ 00589 virtual unsigned int GetAffectedRowsForQuery(IQuery *query) =0; 00590 00591 /** 00592 * @brief Retrieves the last insert id of the given query 00593 * 00594 * Note: This can only accept queries from this driver. 00595 * 00596 * This function is not thread safe and must be included in any locks. 00597 * 00598 * @param query IQuery object from this driver 00599 * @return Insert Id from the last execution of this query, 00600 * if applicable. 00601 */ 00602 virtual unsigned int GetInsertIDForQuery(IQuery *query) =0; 00603 }; 00604 00605 /** 00606 * @brief Describes database connection info. 00607 */ 00608 struct DatabaseInfo 00609 { 00610 DatabaseInfo() 00611 { 00612 dbiVersion = SMINTERFACE_DBI_VERSION; 00613 port = 0; 00614 maxTimeout = 0; 00615 } 00616 unsigned int dbiVersion; /**< DBI Version for backwards compatibility */ 00617 const char *host; /**< Host string */ 00618 const char *database; /**< Database name string */ 00619 const char *user; /**< User to authenticate as */ 00620 const char *pass; /**< Password to authenticate with */ 00621 const char *driver; /**< Driver to use */ 00622 unsigned int port; /**< Port to use, 0=default */ 00623 unsigned int maxTimeout; /**< Maximum timeout, 0=default */ 00624 }; 00625 00626 /** 00627 * @brief Describes an SQL driver. 00628 */ 00629 class IDBDriver 00630 { 00631 public: 00632 virtual unsigned int GetDBIVersion() 00633 { 00634 return SMINTERFACE_DBI_VERSION; 00635 } 00636 public: 00637 /** 00638 * @brief Initiates a database connection. 00639 * 00640 * Note: Persistent connections should never be created from a thread. 00641 * 00642 * @param info Database connection info pointer. 00643 * @param persistent If true, a previous persistent connection will 00644 * be re-used if possible. 00645 * @param error Buffer to store error message. 00646 * @param maxlength Maximum size of the error buffer. 00647 * @return A new IDatabase pointer, or NULL on failure. 00648 */ 00649 virtual IDatabase *Connect(const DatabaseInfo *info, bool persistent, char *error, size_t maxlength) =0; 00650 00651 /** 00652 * @brief Returns a case insensitive database identifier string. 00653 * 00654 * @return String containing an identifier. 00655 */ 00656 virtual const char *GetIdentifier() =0; 00657 00658 /** 00659 * @brief Returns a case sensitive implementation name. 00660 * 00661 * @return String containing an implementation name. 00662 */ 00663 virtual const char *GetProductName() =0; 00664 00665 /** 00666 * @brief Retrieves a Handle_t handle of the IDBDriver type. 00667 * 00668 * @return A Handle_t handle. 00669 */ 00670 virtual Handle_t GetHandle() =0; 00671 00672 /** 00673 * @brief Returns the driver's controlling identity (must be the same 00674 * as from IExtension::GetIdentity). 00675 * 00676 * @return An IdentityToken_t identity. 00677 */ 00678 virtual IdentityToken_t *GetIdentity() =0; 00679 00680 /** 00681 * @brief Returns whether the driver is thread safe. 00682 * 00683 * @return True if thread safe, false otherwise. 00684 */ 00685 virtual bool IsThreadSafe() =0; 00686 00687 /** 00688 * @brief Initializes thread safety for the calling thread. 00689 * 00690 * @return True on success, false otherwise. 00691 */ 00692 virtual bool InitializeThreadSafety() =0; 00693 00694 /** 00695 * @brief Shuts down thread safety for the calling thread. 00696 */ 00697 virtual void ShutdownThreadSafety() =0; 00698 }; 00699 00700 /** 00701 * @brief Priority queue level. 00702 */ 00703 enum PrioQueueLevel 00704 { 00705 PrioQueue_High, /**< High priority */ 00706 PrioQueue_Normal, /**< Normal priority */ 00707 PrioQueue_Low /**< Low priority */ 00708 }; 00709 00710 /** 00711 * Specification for a threaded database operation. 00712 */ 00713 class IDBThreadOperation 00714 { 00715 public: 00716 /** 00717 * @brief Must return the driver this operation is using, or 00718 * NULL if not using any driver. This is not never inside 00719 * the thread. 00720 * 00721 * @return IDBDriver pointer. 00722 */ 00723 virtual IDBDriver *GetDriver() =0; 00724 00725 /** 00726 * @brief Must return the object owning this threaded operation. 00727 * This is never called inside the thread. 00728 * 00729 * @return IdentityToken_t pointer. 00730 */ 00731 virtual IdentityToken_t *GetOwner() =0; 00732 00733 /** 00734 * @brief Called inside the thread; this is where any blocking 00735 * or threaded operations must occur. 00736 */ 00737 virtual void RunThreadPart() =0; 00738 00739 /** 00740 * @brief Called in a server frame after the thread operation 00741 * has completed. This is the non-threaded completion callback, 00742 * which although optional, is useful for pumping results back 00743 * to normal game API. 00744 */ 00745 virtual void RunThinkPart() =0; 00746 00747 /** 00748 * @brief If RunThinkPart() is not called, this will be called 00749 * instead. Note that RunThreadPart() is ALWAYS called regardless, 00750 * and this is only called when Core requests that the operation 00751 * be scrapped (for example, the database driver might be unloading). 00752 */ 00753 virtual void CancelThinkPart() =0; 00754 00755 /** 00756 * @brief Called when the operation is finalized and any resources 00757 * can be released. 00758 */ 00759 virtual void Destroy() =0; 00760 }; 00761 00762 /** 00763 * @brief Database-related Handle types. 00764 */ 00765 enum DBHandleType 00766 { 00767 DBHandle_Driver = 0, /**< Driver Handle */ 00768 DBHandle_Database = 1, /**< Database Handle */ 00769 }; 00770 00771 /** 00772 * @brief Describes the DBI manager. 00773 */ 00774 class IDBManager : public SMInterface 00775 { 00776 public: 00777 virtual const char *GetInterfaceName() =0; 00778 virtual unsigned int GetInterfaceVersion() =0; 00779 public: 00780 /** 00781 * @brief Adds a driver to the DBI system. Not thread safe. 00782 * 00783 * @param pDriver Database driver. 00784 */ 00785 virtual void AddDriver(IDBDriver *pDriver) =0; 00786 00787 /** 00788 * @brief Removes a driver from the DBI system. Not thread safe. 00789 * 00790 * @param pDriver Database driver. 00791 */ 00792 virtual void RemoveDriver(IDBDriver *pDriver) =0; 00793 00794 /** 00795 * @brief Searches for database info by name. Both the return pointer 00796 * and all pointers contained therein should be considered volatile. 00797 * 00798 * @param name Named database info. 00799 * @return DatabaseInfo pointer. 00800 */ 00801 virtual const DatabaseInfo *FindDatabaseConf(const char *name) =0; 00802 00803 /** 00804 * @brief Tries to connect to a named database. Not thread safe. 00805 * 00806 * @param name Named database info. 00807 * @param pdr Pointer to store the IDBDriver pointer in. 00808 * If driver is not found, NULL will be stored. 00809 * @param pdb Pointer to store the IDatabase pointer in. 00810 * If connection fails, NULL will be stored. 00811 * @param persistent If true, the dbmanager will attempt to PConnect 00812 * instead of connect. 00813 * @param error Error buffer to store a driver's error message. 00814 * @param maxlength Maximum length of the error buffer. 00815 * @return True on success, false otherwise. 00816 */ 00817 virtual bool Connect(const char *name, 00818 IDBDriver **pdr, 00819 IDatabase **pdb, 00820 bool persistent, 00821 char *error, 00822 size_t maxlength) =0; 00823 00824 /** 00825 * @brief Returns the number of drivers loaded. Not thread safe. 00826 * 00827 * @return Number of drivers loaded. 00828 */ 00829 virtual unsigned int GetDriverCount() =0; 00830 00831 /** 00832 * @brief Returns a driver by index. Not thread safe. 00833 * 00834 * @param index Driver index, starting from 0. 00835 * @return IDBDriver pointer for the given index. 00836 */ 00837 virtual IDBDriver *GetDriver(unsigned int index) =0; 00838 00839 /** 00840 * @brief Creates a Handle_t of the IDBDriver type. Not thread safe. 00841 * 00842 * @param type A DBHandleType value. 00843 * @param ptr A pointer corrresponding to a DBHandleType 00844 * object. 00845 * @param pToken Identity pointer of the owning identity. 00846 * @return A new Handle_t handle, or 0 on failure. 00847 */ 00848 virtual Handle_t CreateHandle(DBHandleType type, void *ptr, IdentityToken_t *pToken) =0; 00849 00850 /** 00851 * @brief Reads an IDBDriver pointer from an IDBDriver handle. Not 00852 * thread safe. 00853 * 00854 * @param hndl Handle_t handle to read. 00855 * @param type A DBHandleType value. 00856 * @param ptr Pointer to store the object pointer. 00857 * @return HandleError value. 00858 */ 00859 virtual HandleError ReadHandle(Handle_t hndl, DBHandleType type, void **ptr) =0; 00860 00861 /** 00862 * @brief Releases an IDBDriver handle. 00863 * 00864 * @param hndl Handle_t handle to release. 00865 * @param type A DBHandleType value. 00866 * @param token Identity pointer of the owning identity. 00867 * @return HandleError value. 00868 */ 00869 virtual HandleError ReleaseHandle(Handle_t hndl, DBHandleType type, IdentityToken_t *token) =0; 00870 00871 /** 00872 * @brief Given a driver name, attempts to find it. If it is not found, SourceMod 00873 * will attempt to load it. This function is not thread safe. 00874 * 00875 * @param driver Driver identifier name. 00876 * @return IDBDriver pointer on success, NULL otherwise. 00877 */ 00878 virtual IDBDriver *FindOrLoadDriver(const char *driver) =0; 00879 00880 /** 00881 * @brief Returns the default driver, or NULL if none is set. This 00882 * function is not thread safe. 00883 * 00884 * @return IDBDriver pointer on success, NULL otherwise. 00885 */ 00886 virtual IDBDriver *GetDefaultDriver() =0; 00887 00888 /** 00889 * @brief Adds a threaded database operation to the priority queue. 00890 * This function is not thread safe. 00891 * 00892 * @param op Instance of an IDBThreadOperation. 00893 * @param prio Priority level to run at. 00894 * @return True on success, false on failure. 00895 */ 00896 virtual bool AddToThreadQueue(IDBThreadOperation *op, PrioQueueLevel prio) =0; 00897 00898 /** 00899 * @brief Adds a dependency from one extension to the owner of a driver. 00900 * 00901 * @param myself Extension that is using the IDBDriver. 00902 * @param driver Driver that is being used. 00903 */ 00904 virtual void AddDependency(IExtension *myself, IDBDriver *driver) =0; 00905 }; 00906 } 00907 00908 #endif //_INCLUDE_SOURCEMOD_INTERFACE_DBDRIVER_H_ 00909
1.7.1