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 class SQLEntry
  28 {
  29  public:
  30         std::string value;
  31         bool nul;
  32         SQLEntry() : nul(true) {}
  33         SQLEntry(const std::string& v) : value(v), nul(false) {}
  34         inline operator std::string&() { return value; }
  35 };
  36
  37 typedef std::vector<SQLEntry> SQLEntries;
  38
  39 /**
  40  * Result of an SQL query. Only valid inside OnResult
  41  */
  42 class SQLResult : public interfacebase
  43 {
  44  public:
  45         /**
  46          * Return the number of rows in the result.
  47          *
  48          * Note that if you have perfomed an INSERT or UPDATE query or other
  49          * query which will not return rows, this will return the number of
  50          * affected rows. In this case you SHOULD NEVER access any of the result
  51          * set rows, as there aren't any!
  52          * @returns Number of rows in the result set.
  53          */
  54         virtual int Rows() = 0;
  55
  56         /**
  57          * Return a single row (result of the query). The internal row counter
  58          * is incremented by one.
  59          *
  60          * @param result Storage for the result data.
  61          * @returns true if there was a row, false if no row exists (end of
  62          * iteration)
  63          */
  64         virtual bool GetRow(SQLEntries& result) = 0;
  65
  66         /** Returns column names for the items in this row
  67          */
  68         virtual void GetCols(std::vector<std::string>& result) = 0;
  69 };
  70
  71 /** SQLerror holds the error state of a request.
  72  * The error string varies from database software to database software
  73  * and should be used to display informational error messages to users.
  74  */
  75 class SQLerror
  76 {
  77  public:
  78         /** The error id
  79          */
  80         SQLerrorNum id;
  81
  82         /** The error string
  83          */
  84         std::string str;
  85
  86         /** Initialize an SQLerror
  87          * @param i The error ID to set
  88          * @param s The (optional) error string to set
  89          */
  90         SQLerror(SQLerrorNum i, const std::string &s = "")
  91         : id(i), str(s)
  92         {
  93         }
  94
  95         /** Return the error string for an error
  96          */
  97         const char* Str()
  98         {
  99                 if(str.length())
 100                         return str.c_str();
 101
 102                 switch(id)
 103                 {
 104                         case SQL_BAD_DBID:
 105                                 return "Invalid database ID";
 106                         case SQL_BAD_CONN:
 107                                 return "Invalid connection";
 108                         case SQL_QSEND_FAIL:
 109                                 return "Sending query failed";
 110                         case SQL_QREPLY_FAIL:
 111                                 return "Getting query result failed";
 112                         default:
 113                                 return "Unknown error";
 114                 }
 115         }
 116 };
 117
 118 /**
 119  * Object representing an SQL query. This should be allocated on the heap and
 120  * passed to an SQLProvider, which will free it when the query is complete or
 121  * when the querying module is unloaded.
 122  *
 123  * You should store whatever information is needed to have the callbacks work in
 124  * this object (UID of user, channel name, etc).
 125  */
 126 class SQLQuery : public classbase
 127 {
 128  public:
 129         ModuleRef creator;
 130         const std::string query;
 131
 132         SQLQuery(Module* Creator, const std::string& q)
 133                 : creator(Creator), query(q) {}
 134         virtual ~SQLQuery() {}
 135
 136         virtual void OnResult(SQLResult& result) = 0;
 137         /**
 138          * Called when the query fails
 139          */
 140         virtual void OnError(SQLerror& error) { }
 141 };
 142
 143 /**
 144  * Provider object for SQL servers
 145  */
 146 class SQLProvider : public DataProvider
 147 {
 148  public:
 149         SQLProvider(Module* Creator, const std::string& Name) : DataProvider(Creator, Name) {}
 150         /** Submit an asynchronous SQL request
 151          * @param dbid The database ID to apply the request to
 152          * @param query The query string
 153          * @param callback The callback that the result is sent to
 154          */
 155         virtual void submit(SQLQuery* query) = 0;
 156
 157         /** Format a parameterized query string using proper SQL escaping.
 158          * @param q The query string, with '?' parameters
 159          * @param p The parameters to fill in in the '?' slots
 160          */
 161         virtual std::string FormatQuery(const std::string& q, const ParamL& p) = 0;
 162
 163         /** Format a parameterized query string using proper SQL escaping.
 164          * @param q The query string, with '$foo' parameters
 165          * @param p The map to look up parameters in
 166          */
 167         virtual std::string FormatQuery(const std::string& q, const ParamM& p) = 0;
 168
 169         /** Convenience function */
 170         void PopulateUserInfo(User* user, ParamM& userinfo)
 171         {
 172                 userinfo["nick"] = user->nick;
 173                 userinfo["host"] = user->host;
 174                 userinfo["ip"] = user->GetIPString();
 175                 userinfo["gecos"] = user->fullname;
 176                 userinfo["ident"] = user->ident;
 177                 userinfo["server"] = user->server;
 178                 userinfo["uuid"] = user->uuid;
 179         }
 180 };
 181
 182 #endif