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