src/modules/sql.h

   1 /*
   2  * InspIRCd -- Internet Relay Chat Daemon
   3  *
   4  *   Copyright (C) 2010 Daniel De Graaf <danieldg@inspircd.org>
   5  *
   6  * This file is part of InspIRCd.  InspIRCd is free software: you can
   7  * redistribute it and/or modify it under the terms of the GNU General Public
   8  * License as published by the Free Software Foundation, version 2.
   9  *
  10  * This program is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  12  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  13  * details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19
  20 #ifndef INSPIRCD_SQLAPI_3
  21 #define INSPIRCD_SQLAPI_3
  22
  23 /** Defines the error types which SQLerror may be set to
  24  */
  25 enum SQLerrorNum { SQL_NO_ERROR, SQL_BAD_DBID, SQL_BAD_CONN, SQL_QSEND_FAIL, SQL_QREPLY_FAIL };
  26
  27 /** A list of format parameters for an SQLquery object.
  28  */
  29 typedef std::vector<std::string> ParamL;
  30
  31 typedef std::map<std::string, std::string> ParamM;
  32
  33 class SQLEntry
  34 {
  35  public:
  36         std::string value;
  37         bool nul;
  38         SQLEntry() : nul(true) {}
  39         SQLEntry(const std::string& v) : value(v), nul(false) {}
  40         inline operator std::string&() { return value; }
  41 };
  42
  43 typedef std::vector<SQLEntry> SQLEntries;
  44
  45 /**
  46  * Result of an SQL query. Only valid inside OnResult
  47  */
  48 class SQLResult : public classbase
  49 {
  50  public:
  51         /**
  52          * Return the number of rows in the result.
  53          *
  54          * Note that if you have perfomed an INSERT or UPDATE query or other
  55          * query which will not return rows, this will return the number of
  56          * affected rows. In this case you SHOULD NEVER access any of the result
  57          * set rows, as there aren't any!
  58          * @returns Number of rows in the result set.
  59          */
  60         virtual int Rows() = 0;
  61
  62         /**
  63          * Return a single row (result of the query). The internal row counter
  64          * is incremented by one.
  65          *
  66          * @param result Storage for the result data.
  67          * @returns true if there was a row, false if no row exists (end of
  68          * iteration)
  69          */
  70         virtual bool GetRow(SQLEntries& result) = 0;
  71
  72         /** Returns column names for the items in this row
  73          */
  74         virtual void GetCols(std::vector<std::string>& result) = 0;
  75 };
  76
  77 /** SQLerror holds the error state of a request.
  78  * The error string varies from database software to database software
  79  * and should be used to display informational error messages to users.
  80  */
  81 class SQLerror
  82 {
  83  public:
  84         /** The error id
  85          */
  86         SQLerrorNum id;
  87
  88         /** The error string
  89          */
  90         std::string str;
  91
  92         /** Initialize an SQLerror
  93          * @param i The error ID to set
  94          * @param s The (optional) error string to set
  95          */
  96         SQLerror(SQLerrorNum i, const std::string &s = "")
  97         : id(i), str(s)
  98         {
  99         }
 100
 101         /** Return the error string for an error
 102          */
 103         const char* Str()
 104         {
 105                 if(str.length())
 106                         return str.c_str();
 107
 108                 switch(id)
 109                 {
 110                         case SQL_BAD_DBID:
 111                                 return "Invalid database ID";
 112                         case SQL_BAD_CONN:
 113                                 return "Invalid connection";
 114                         case SQL_QSEND_FAIL:
 115                                 return "Sending query failed";
 116                         case SQL_QREPLY_FAIL:
 117                                 return "Getting query result failed";
 118                         default:
 119                                 return "Unknown error";
 120                 }
 121         }
 122 };
 123
 124 /**
 125  * Object representing an SQL query. This should be allocated on the heap and
 126  * passed to an SQLProvider, which will free it when the query is complete or
 127  * when the querying module is unloaded.
 128  *
 129  * You should store whatever information is needed to have the callbacks work in
 130  * this object (UID of user, channel name, etc).
 131  */
 132 class SQLQuery : public classbase
 133 {
 134  public:
 135         ModuleRef creator;
 136
 137         SQLQuery(Module* Creator) : creator(Creator) {}
 138         virtual ~SQLQuery() {}
 139
 140         virtual void OnResult(SQLResult& result) = 0;
 141         /**
 142          * Called when the query fails
 143          */
 144         virtual void OnError(SQLerror& error) { }
 145 };
 146
 147 /**
 148  * Provider object for SQL servers
 149  */
 150 class SQLProvider : public DataProvider
 151 {
 152  public:
 153         SQLProvider(Module* Creator, const std::string& Name) : DataProvider(Creator, Name) {}
 154         /** Submit an asynchronous SQL request
 155          * @param callback The result reporting point
 156          * @param query The hardcoded query string. If you have parameters to substitute, see below.
 157          */
 158         virtual void submit(SQLQuery* callback, const std::string& query) = 0;
 159
 160         /** Submit an asynchronous SQL request
 161          * @param callback The result reporting point
 162          * @param format The simple parameterized query string ('?' parameters)
 163          * @param p Parameters to fill in for the '?' entries
 164          */
 165         virtual void submit(SQLQuery* callback, const std::string& format, const ParamL& p) = 0;
 166
 167         /** Submit an asynchronous SQL request.
 168          * @param callback The result reporting point
 169          * @param format The parameterized query string ('$name' parameters)
 170          * @param p Parameters to fill in for the '$name' entries
 171          */
 172         virtual void submit(SQLQuery* callback, const std::string& format, const ParamM& p) = 0;
 173
 174         /** Convenience function to prepare a map from a User* */
 175         void PopulateUserInfo(User* user, ParamM& userinfo)
 176         {
 177                 userinfo["nick"] = user->nick;
 178                 userinfo["host"] = user->host;
 179                 userinfo["ip"] = user->GetIPString();
 180                 userinfo["gecos"] = user->fullname;
 181                 userinfo["ident"] = user->ident;
 182                 userinfo["server"] = user->server;
 183                 userinfo["uuid"] = user->uuid;
 184         }
 185 };
 186
 187 #endif