src/modules/sql.h

   1 /*       +------------------------------------+
   2  *       | Inspire Internet Relay Chat Daemon |
   3  *       +------------------------------------+
   4  *
   5  *  InspIRCd: (C) 2002-2010 InspIRCd Development Team
   6  * See: http://wiki.inspircd.org/Credits
   7  *
   8  * This program is free but copyrighted software; see
   9  *          the file COPYING for details.
  10  *
  11  * ---------------------------------------------------
  12  */
  13
  14 #ifndef INSPIRCD_SQLAPI_3
  15 #define INSPIRCD_SQLAPI_3
  16
  17 /** Defines the error types which SQLerror may be set to
  18  */
  19 enum SQLerrorNum { SQL_BAD_DBID, SQL_BAD_CONN, SQL_QSEND_FAIL, SQL_QREPLY_FAIL };
  20
  21 /** A list of format parameters for an SQLquery object.
  22  */
  23 typedef std::vector<std::string> ParamL;
  24
  25 typedef std::map<std::string, std::string> ParamM;
  26
  27 /**
  28  * Result of an SQL query. Only valid inside OnResult
  29  */
  30 class SQLResult : public interfacebase
  31 {
  32  public:
  33         /**
  34          * Return the number of rows in the result.
  35          *
  36          * Note that if you have perfomed an INSERT or UPDATE query or other
  37          * query which will not return rows, this will return the number of
  38          * affected rows. In this case you SHOULD NEVER access any of the result
  39          * set rows, as there aren't any!
  40          * @returns Number of rows in the result set.
  41          */
  42         virtual int Rows() = 0;
  43
  44         /**
  45          * Return a single row (result of the query). The internal row counter
  46          * is incremented by one.
  47          *
  48          * @param result Storage for the result data.
  49          * @returns true if there was a row, false if no row exists (end of
  50          * iteration)
  51          */
  52         virtual bool GetRow(std::vector<std::string>& result) = 0;
  53 };
  54
  55 /** SQLerror holds the error state of a request.
  56  * The error string varies from database software to database software
  57  * and should be used to display informational error messages to users.
  58  */
  59 class SQLerror
  60 {
  61  public:
  62         /** The error id
  63          */
  64         SQLerrorNum id;
  65
  66         /** The error string
  67          */
  68         std::string str;
  69
  70         /** Initialize an SQLerror
  71          * @param i The error ID to set
  72          * @param s The (optional) error string to set
  73          */
  74         SQLerror(SQLerrorNum i, const std::string &s = "")
  75         : id(i), str(s)
  76         {
  77         }
  78
  79         /** Return the error string for an error
  80          */
  81         const char* Str()
  82         {
  83                 if(str.length())
  84                         return str.c_str();
  85
  86                 switch(id)
  87                 {
  88                         case SQL_BAD_DBID:
  89                                 return "Invalid database ID";
  90                         case SQL_BAD_CONN:
  91                                 return "Invalid connection";
  92                         case SQL_QSEND_FAIL:
  93                                 return "Sending query failed";
  94                         case SQL_QREPLY_FAIL:
  95                                 return "Getting query result failed";
  96                         default:
  97                                 return "Unknown error";
  98                 }
  99         }
 100 };
 101
 102 /**
 103  * Object representing an SQL query. This should be allocated on the heap and
 104  * passed to an SQLProvider, which will free it when the query is complete or
 105  * when the querying module is unloaded.
 106  *
 107  * You should store whatever information is needed to have the callbacks work in
 108  * this object (UID of user, channel name, etc).
 109  */
 110 class SQLQuery : public classbase
 111 {
 112  public:
 113         ModuleRef creator;
 114         const std::string dbid;
 115         const std::string query;
 116
 117         SQLQuery(Module* Creator, const std::string& db, const std::string& q)
 118                 : creator(Creator), dbid(db), query(q) {}
 119         virtual ~SQLQuery() {}
 120
 121         virtual void OnResult(SQLResult& result) = 0;
 122         /**
 123          * Called when the query fails
 124          */
 125         virtual void OnError(SQLerror& error) { }
 126 };
 127
 128 /**
 129  * Provider object for SQL servers
 130  */
 131 class SQLProvider : public DataProvider
 132 {
 133  public:
 134         SQLProvider(Module* Creator, const std::string& Name) : DataProvider(Creator, Name) {}
 135         /** Submit an asynchronous SQL request
 136          * @param dbid The database ID to apply the request to
 137          * @param query The query string
 138          * @param callback The callback that the result is sent to
 139          */
 140         virtual void submit(SQLQuery* query) = 0;
 141
 142         /** Format a parameterized query string using proper SQL escaping.
 143          * @param q The query string, with '?' parameters
 144          * @param p The parameters to fill in in the '?' slots
 145          */
 146         virtual std::string FormatQuery(std::string q, ParamL p) = 0;
 147
 148         /** Format a parameterized query string using proper SQL escaping.
 149          * @param q The query string, with '$foo' parameters
 150          * @param p The map to look up parameters in
 151          */
 152         virtual std::string FormatQuery(std::string q, ParamM p) = 0;
 153 };
 154
 155 #endif