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_NO_ERROR, 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 classbase
  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
 131         SQLQuery(Module* Creator) : creator(Creator) {}
 132         virtual ~SQLQuery() {}
 133
 134         virtual void OnResult(SQLResult& result) = 0;
 135         /**
 136          * Called when the query fails
 137          */
 138         virtual void OnError(SQLerror& error) { }
 139 };
 140
 141 /**
 142  * Provider object for SQL servers
 143  */
 144 class SQLProvider : public DataProvider
 145 {
 146  public:
 147         SQLProvider(Module* Creator, const std::string& Name) : DataProvider(Creator, Name) {}
 148         /** Submit an asynchronous SQL request
 149          * @param callback The result reporting point
 150          * @param query The hardcoded query string. If you have parameters to substitute, see below.
 151          */
 152         virtual void submit(SQLQuery* callback, const std::string& query) = 0;
 153
 154         /** Submit an asynchronous SQL request
 155          * @param callback The result reporting point
 156          * @param format The simple parameterized query string ('?' parameters)
 157          * @param p Parameters to fill in for the '?' entries
 158          */
 159         virtual void submit(SQLQuery* callback, const std::string& format, const ParamL& p) = 0;
 160
 161         /** Submit an asynchronous SQL request.
 162          * @param callback The result reporting point
 163          * @param format The parameterized query string ('$name' parameters)
 164          * @param p Parameters to fill in for the '$name' entries
 165          */
 166         virtual void submit(SQLQuery* callback, const std::string& format, const ParamM& p) = 0;
 167
 168         /** Convenience function to prepare a map from a User* */
 169         void PopulateUserInfo(User* user, ParamM& userinfo)
 170         {
 171                 userinfo["nick"] = user->nick;
 172                 userinfo["host"] = user->host;
 173                 userinfo["ip"] = user->GetIPString();
 174                 userinfo["gecos"] = user->fullname;
 175                 userinfo["ident"] = user->ident;
 176                 userinfo["server"] = user->server;
 177                 userinfo["uuid"] = user->uuid;
 178         }
 179 };
 180
 181 #endif