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: IDBDriver.h 2315 2008-07-01 06:12:16Z dvander $ 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 7 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 /** 00579 * @brief Describes database connection info. 00580 */ 00581 struct DatabaseInfo 00582 { 00583 DatabaseInfo() 00584 { 00585 dbiVersion = SMINTERFACE_DBI_VERSION; 00586 port = 0; 00587 maxTimeout = 0; 00588 } 00589 unsigned int dbiVersion; /**< DBI Version for backwards compatibility */ 00590 const char *host; /**< Host string */ 00591 const char *database; /**< Database name string */ 00592 const char *user; /**< User to authenticate as */ 00593 const char *pass; /**< Password to authenticate with */ 00594 const char *driver; /**< Driver to use */ 00595 unsigned int port; /**< Port to use, 0=default */ 00596 unsigned int maxTimeout; /**< Maximum timeout, 0=default */ 00597 }; 00598 00599 /** 00600 * @brief Describes an SQL driver. 00601 */ 00602 class IDBDriver 00603 { 00604 public: 00605 virtual unsigned int GetDBIVersion() 00606 { 00607 return SMINTERFACE_DBI_VERSION; 00608 } 00609 public: 00610 /** 00611 * @brief Initiates a database connection. 00612 * 00613 * Note: Persistent connections should never be created from a thread. 00614 * 00615 * @param info Database connection info pointer. 00616 * @param persistent If true, a previous persistent connection will 00617 * be re-used if possible. 00618 * @param error Buffer to store error message. 00619 * @param maxlength Maximum size of the error buffer. 00620 * @return A new IDatabase pointer, or NULL on failure. 00621 */ 00622 virtual IDatabase *Connect(const DatabaseInfo *info, bool persistent, char *error, size_t maxlength) =0; 00623 00624 /** 00625 * @brief Returns a case insensitive database identifier string. 00626 * 00627 * @return String containing an identifier. 00628 */ 00629 virtual const char *GetIdentifier() =0; 00630 00631 /** 00632 * @brief Returns a case sensitive implementation name. 00633 * 00634 * @return String containing an implementation name. 00635 */ 00636 virtual const char *GetProductName() =0; 00637 00638 /** 00639 * @brief Retrieves a Handle_t handle of the IDBDriver type. 00640 * 00641 * @return A Handle_t handle. 00642 */ 00643 virtual Handle_t GetHandle() =0; 00644 00645 /** 00646 * @brief Returns the driver's controlling identity (must be the same 00647 * as from IExtension::GetIdentity). 00648 * 00649 * @return An IdentityToken_t identity. 00650 */ 00651 virtual IdentityToken_t *GetIdentity() =0; 00652 00653 /** 00654 * @brief Returns whether the driver is thread safe. 00655 * 00656 * @return True if thread safe, false otherwise. 00657 */ 00658 virtual bool IsThreadSafe() =0; 00659 00660 /** 00661 * @brief Initializes thread safety for the calling thread. 00662 * 00663 * @return True on success, false otherwise. 00664 */ 00665 virtual bool InitializeThreadSafety() =0; 00666 00667 /** 00668 * @brief Shuts down thread safety for the calling thread. 00669 */ 00670 virtual void ShutdownThreadSafety() =0; 00671 }; 00672 00673 /** 00674 * @brief Priority queue level. 00675 */ 00676 enum PrioQueueLevel 00677 { 00678 PrioQueue_High, /**< High priority */ 00679 PrioQueue_Normal, /**< Normal priority */ 00680 PrioQueue_Low /**< Low priority */ 00681 }; 00682 00683 /** 00684 * Specification for a threaded database operation. 00685 */ 00686 class IDBThreadOperation 00687 { 00688 public: 00689 /** 00690 * @brief Must return the driver this operation is using, or 00691 * NULL if not using any driver. This is not never inside 00692 * the thread. 00693 * 00694 * @return IDBDriver pointer. 00695 */ 00696 virtual IDBDriver *GetDriver() =0; 00697 00698 /** 00699 * @brief Must return the object owning this threaded operation. 00700 * This is never called inside the thread. 00701 * 00702 * @return IdentityToken_t pointer. 00703 */ 00704 virtual IdentityToken_t *GetOwner() =0; 00705 00706 /** 00707 * @brief Called inside the thread; this is where any blocking 00708 * or threaded operations must occur. 00709 */ 00710 virtual void RunThreadPart() =0; 00711 00712 /** 00713 * @brief Called in a server frame after the thread operation 00714 * has completed. This is the non-threaded completion callback, 00715 * which although optional, is useful for pumping results back 00716 * to normal game API. 00717 */ 00718 virtual void RunThinkPart() =0; 00719 00720 /** 00721 * @brief If RunThinkPart() is not called, this will be called 00722 * instead. Note that RunThreadPart() is ALWAYS called regardless, 00723 * and this is only called when Core requests that the operation 00724 * be scrapped (for example, the database driver might be unloading). 00725 */ 00726 virtual void CancelThinkPart() =0; 00727 00728 /** 00729 * @brief Called when the operation is finalized and any resources 00730 * can be released. 00731 */ 00732 virtual void Destroy() =0; 00733 }; 00734 00735 /** 00736 * @brief Database-related Handle types. 00737 */ 00738 enum DBHandleType 00739 { 00740 DBHandle_Driver = 0, /**< Driver Handle */ 00741 DBHandle_Database = 1, /**< Database Handle */ 00742 }; 00743 00744 /** 00745 * @brief Describes the DBI manager. 00746 */ 00747 class IDBManager : public SMInterface 00748 { 00749 public: 00750 virtual const char *GetInterfaceName() =0; 00751 virtual unsigned int GetInterfaceVersion() =0; 00752 public: 00753 /** 00754 * @brief Adds a driver to the DBI system. Not thread safe. 00755 * 00756 * @param pDriver Database driver. 00757 */ 00758 virtual void AddDriver(IDBDriver *pDriver) =0; 00759 00760 /** 00761 * @brief Removes a driver from the DBI system. Not thread safe. 00762 * 00763 * @param pDriver Database driver. 00764 */ 00765 virtual void RemoveDriver(IDBDriver *pDriver) =0; 00766 00767 /** 00768 * @brief Searches for database info by name. Both the return pointer 00769 * and all pointers contained therein should be considered volatile. 00770 * 00771 * @param name Named database info. 00772 * @return DatabaseInfo pointer. 00773 */ 00774 virtual const DatabaseInfo *FindDatabaseConf(const char *name) =0; 00775 00776 /** 00777 * @brief Tries to connect to a named database. Not thread safe. 00778 * 00779 * @param name Named database info. 00780 * @param pdr Pointer to store the IDBDriver pointer in. 00781 * If driver is not found, NULL will be stored. 00782 * @param pdb Pointer to store the IDatabase pointer in. 00783 * If connection fails, NULL will be stored. 00784 * @param persistent If true, the dbmanager will attempt to PConnect 00785 * instead of connect. 00786 * @param error Error buffer to store a driver's error message. 00787 * @param maxlength Maximum length of the error buffer. 00788 * @return True on success, false otherwise. 00789 */ 00790 virtual bool Connect(const char *name, 00791 IDBDriver **pdr, 00792 IDatabase **pdb, 00793 bool persistent, 00794 char *error, 00795 size_t maxlength) =0; 00796 00797 /** 00798 * @brief Returns the number of drivers loaded. Not thread safe. 00799 * 00800 * @return Number of drivers loaded. 00801 */ 00802 virtual unsigned int GetDriverCount() =0; 00803 00804 /** 00805 * @brief Returns a driver by index. Not thread safe. 00806 * 00807 * @param index Driver index, starting from 0. 00808 * @return IDBDriver pointer for the given index. 00809 */ 00810 virtual IDBDriver *GetDriver(unsigned int index) =0; 00811 00812 /** 00813 * @brief Creates a Handle_t of the IDBDriver type. Not thread safe. 00814 * 00815 * @param type A DBHandleType value. 00816 * @param ptr A pointer corrresponding to a DBHandleType 00817 * object. 00818 * @param pToken Identity pointer of the owning identity. 00819 * @return A new Handle_t handle, or 0 on failure. 00820 */ 00821 virtual Handle_t CreateHandle(DBHandleType type, void *ptr, IdentityToken_t *pToken) =0; 00822 00823 /** 00824 * @brief Reads an IDBDriver pointer from an IDBDriver handle. Not 00825 * thread safe. 00826 * 00827 * @param hndl Handle_t handle to read. 00828 * @param type A DBHandleType value. 00829 * @param ptr Pointer to store the object pointer. 00830 * @return HandleError value. 00831 */ 00832 virtual HandleError ReadHandle(Handle_t hndl, DBHandleType type, void **ptr) =0; 00833 00834 /** 00835 * @brief Releases an IDBDriver handle. 00836 * 00837 * @param hndl Handle_t handle to release. 00838 * @param type A DBHandleType value. 00839 * @param token Identity pointer of the owning identity. 00840 * @return HandleError value. 00841 */ 00842 virtual HandleError ReleaseHandle(Handle_t hndl, DBHandleType type, IdentityToken_t *token) =0; 00843 00844 /** 00845 * @brief Given a driver name, attempts to find it. If it is not found, SourceMod 00846 * will attempt to load it. This function is not thread safe. 00847 * 00848 * @param driver Driver identifier name. 00849 * @return IDBDriver pointer on success, NULL otherwise. 00850 */ 00851 virtual IDBDriver *FindOrLoadDriver(const char *driver) =0; 00852 00853 /** 00854 * @brief Returns the default driver, or NULL if none is set. This 00855 * function is not thread safe. 00856 * 00857 * @return IDBDriver pointer on success, NULL otherwise. 00858 */ 00859 virtual IDBDriver *GetDefaultDriver() =0; 00860 00861 /** 00862 * @brief Adds a threaded database operation to the priority queue. 00863 * This function is not thread safe. 00864 * 00865 * @param op Instance of an IDBThreadOperation. 00866 * @param prio Priority level to run at. 00867 * @return True on success, false on failure. 00868 */ 00869 virtual bool AddToThreadQueue(IDBThreadOperation *op, PrioQueueLevel prio) =0; 00870 00871 /** 00872 * @brief Adds a dependency from one extension to the owner of a driver. 00873 * 00874 * @param myself Extension that is using the IDBDriver. 00875 * @param driver Driver that is being used. 00876 */ 00877 virtual void AddDependency(IExtension *myself, IDBDriver *driver) =0; 00878 }; 00879 } 00880 00881 #endif //_INCLUDE_SOURCEMOD_INTERFACE_DBDRIVER_H_ 00882
1.5.1