2 * InspIRCd -- Internet Relay Chat Daemon
4 * Copyright (C) 2010 Daniel De Graaf <danieldg@inspircd.org>
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.
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
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/>.
20 #ifndef INSPIRCD_SQLAPI_3
21 #define INSPIRCD_SQLAPI_3
23 /** Defines the error types which SQLerror may be set to
25 enum SQLerrorNum { SQL_NO_ERROR, SQL_BAD_DBID, SQL_BAD_CONN, SQL_QSEND_FAIL, SQL_QREPLY_FAIL };
27 /** A list of format parameters for an SQLquery object.
29 typedef std::vector<std::string> ParamL;
31 typedef std::map<std::string, std::string> ParamM;
38 SQLEntry() : nul(true) {}
39 SQLEntry(const std::string& v) : value(v), nul(false) {}
40 inline operator std::string&() { return value; }
43 typedef std::vector<SQLEntry> SQLEntries;
46 * Result of an SQL query. Only valid inside OnResult
48 class SQLResult : public classbase
52 * Return the number of rows in the result.
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.
60 virtual int Rows() = 0;
63 * Return a single row (result of the query). The internal row counter
64 * is incremented by one.
66 * @param result Storage for the result data.
67 * @returns true if there was a row, false if no row exists (end of
70 virtual bool GetRow(SQLEntries& result) = 0;
72 /** Returns column names for the items in this row
74 virtual void GetCols(std::vector<std::string>& result) = 0;
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.
92 /** Initialize an SQLerror
93 * @param i The error ID to set
94 * @param s The (optional) error string to set
96 SQLerror(SQLerrorNum i, const std::string &s = "")
101 /** Return the error string for an error
111 return "Invalid database ID";
113 return "Invalid connection";
115 return "Sending query failed";
116 case SQL_QREPLY_FAIL:
117 return "Getting query result failed";
119 return "Unknown error";
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.
129 * You should store whatever information is needed to have the callbacks work in
130 * this object (UID of user, channel name, etc).
132 class SQLQuery : public classbase
137 SQLQuery(Module* Creator) : creator(Creator) {}
138 virtual ~SQLQuery() {}
140 virtual void OnResult(SQLResult& result) = 0;
142 * Called when the query fails
144 virtual void OnError(SQLerror& error) { }
148 * Provider object for SQL servers
150 class SQLProvider : public DataProvider
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.
158 virtual void submit(SQLQuery* callback, const std::string& query) = 0;
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
165 virtual void submit(SQLQuery* callback, const std::string& format, const ParamL& p) = 0;
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
172 virtual void submit(SQLQuery* callback, const std::string& format, const ParamM& p) = 0;
174 /** Convenience function to prepare a map from a User* */
175 void PopulateUserInfo(User* user, ParamM& userinfo)
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;