summaryrefslogtreecommitdiff
path: root/include/modules/sql.h
blob: 14cd60a5625012bb87c714a69d5a0c57292eef11 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
/*
 * InspIRCd -- Internet Relay Chat Daemon
 *
 *   Copyright (C) 2017 Peter Powell <petpow@saberuk.com>
 *   Copyright (C) 2010 Daniel De Graaf <danieldg@inspircd.org>
 *
 * This file is part of InspIRCd.  InspIRCd is free software: you can
 * redistribute it and/or modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation, version 2.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */


#pragma once


namespace SQL
{
	class Error;
	class Field;
	class Provider;
	class Query;
	class Result;

	/** A list of parameter replacement values. */
	typedef std::vector<std::string> ParamList;

	/** A map of parameter replacement values. */
	typedef std::map<std::string, std::string> ParamMap;

	/** A list of SQL fields from a specific row. */
	typedef std::vector<Field> Row;

	/** An enumeration of possible error codes. */
	enum ErrorCode
	{
		/** No error has occurred. */
		SUCCESS,

		/** The database identifier is invalid. */
		BAD_DBID,

		/** The database connection has failed. */
		BAD_CONN,

		/** Executing the query failed. */
		QSEND_FAIL,

		/** Reading the response failed. */
		QREPLY_FAIL
	};

	/** Populates a parameter map with information about a user.
	 * @param user The user to collect information from.
	 * @param userinfo The map to populate.
	 */
	void PopulateUserInfo(User* user, ParamMap& userinfo);
}

/** Represents a single SQL field. */
class SQL::Field
{
 private:
	/** Whether this SQL field is NULL. */
	bool null;

	/** The underlying SQL value. */
	std::string value;

 public:
	/** Creates a new NULL SQL field. */
	Field()
		: null(true)
	{
	}

	/** Creates a new non-NULL SQL field.
	 * @param v The value of the field.
	 */
	Field(const std::string& v)
		: null(false)
		, value(v)
	{
	}

	/** Determines whether this SQL entry is NULL. */
	inline bool IsNull() const { return null; }

	/** Retrieves the underlying value. */
	inline operator const std::string&() const { return value; }
};

/** Represents the result of an SQL query. */
class SQL::Result : public classbase
{
 public:
	/**
	 * Return the number of rows in the result.
	 *
	 * Note that if you have perfomed an INSERT or UPDATE query or other
	 * query which will not return rows, this will return the number of
	 * affected rows. In this case you SHOULD NEVER access any of the result
	 * set rows, as there aren't any!
	 * @returns Number of rows in the result set.
	 */
	virtual int Rows() = 0;

	/** Retrieves the next available row from the database.
	 * @param result A list to store the fields from this row in.
	 * @return True if a row could be retrieved; otherwise, false.
	 */
	virtual bool GetRow(Row& result) = 0;

	/** Retrieves a list of SQL columns in the result.
	 * @param result A reference to the vector to store column names in.
	 */
	virtual void GetCols(std::vector<std::string>& result) = 0;
};

/** SQL::Error holds the error state of a request.
 * The error string varies from database software to database software
 * and should be used to display informational error messages to users.
 */
class SQL::Error
{
 private:
	/** The custom error message if one has been specified. */
	const std::string message;

 public:
	/** The code which represents this error. */
	const ErrorCode code;

	/** Initialize an SQL::Error from an error code.
	 * @param c A code which represents this error.
	 */
	Error(ErrorCode c)
		: code(c)
	{
	}

	/** Initialize an SQL::Error from an error code and a custom error message.
	 * @param c A code which represents this error.
	 * @param m A custom error message.
	 */
	Error(ErrorCode c, const std::string m)
		: message(m)
		, code(c)
	{
	}

	/** Retrieves the error message. */
	const char* ToString() const
	{
		if (!message.empty())
			return message.c_str();

		switch (code)
		{
			case BAD_DBID:
				return "Invalid database identifier";
			case BAD_CONN:
				return "Invalid connection";
			case QSEND_FAIL:
				return "Sending query failed";
			case QREPLY_FAIL:
				return "Getting query result failed";
			default:
				return "Unknown error";
		}
	}
};

/**
 * Object representing an SQL query. This should be allocated on the heap and
 * passed to an SQL::Provider, which will free it when the query is complete or
 * when the querying module is unloaded.
 *
 * You should store whatever information is needed to have the callbacks work in
 * this object (UID of user, channel name, etc).
 */
class SQL::Query : public classbase
{
 protected:
	/** Creates a new SQL query. */
	Query(Module* Creator)
		: creator(Creator)
	{
	}

 public:
	const ModuleRef creator;

	/* Destroys this Query instance. */
	virtual ~Query()
	{
	}

	/** Called when an SQL error happens.
	 * @param error The error that occurred.
	 */
	virtual void OnError(Error& error) = 0;

	/** Called when a SQL result is received.
	 * @param result The result of the SQL query.
	 */
	virtual void OnResult(Result& result) = 0;
};

/**
 * Provider object for SQL servers
 */
class SQL::Provider : public DataProvider
{
 public:
	Provider(Module* Creator, const std::string& Name)
		: DataProvider(Creator, Name)
	{
	}

	/** Submit an asynchronous SQL query.
	 * @param callback The result reporting point
	 * @param query The hardcoded query string. If you have parameters to substitute, see below.
	 */
	virtual void Submit(Query* callback, const std::string& query) = 0;

	/** Submit an asynchronous SQL query.
	 * @param callback The result reporting point
	 * @param format The simple parameterized query string ('?' parameters)
	 * @param p Parameters to fill in for the '?' entries
	 */
	virtual void Submit(Query* callback, const std::string& format, const SQL::ParamList& p) = 0;

	/** Submit an asynchronous SQL query.
	 * @param callback The result reporting point
	 * @param format The parameterized query string ('$name' parameters)
	 * @param p Parameters to fill in for the '$name' entries
	 */
	virtual void Submit(Query* callback, const std::string& format, const ParamMap& p) = 0;
};

inline void SQL::PopulateUserInfo(User* user, ParamMap& userinfo)
{
	userinfo["nick"] = user->nick;
	userinfo["host"] = user->GetRealHost();
	userinfo["ip"] = user->GetIPString();
	userinfo["gecos"] = user->fullname;
	userinfo["ident"] = user->ident;
	userinfo["server"] = user->server->GetName();
	userinfo["uuid"] = user->uuid;
}