Adding upstream version 1:2.3.19.1+dfsg1.upstream/1%2.3.19.1+dfsg1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 249 insertions, 0 deletions

diff --git a/src/lib-sql/sql-api.h b/src/lib-sql/sql-api.h
new file mode 100644
index 0000000..7936b98
--- /dev/null
+++ b/src/lib-sql/sql-api.h
@@ -0,0 +1,249 @@
+#ifndef SQL_API_H
+#define SQL_API_H
+
+struct timespec;
+
+/* This SQL API is designed to work asynchronously. The underlying drivers
+   however may not. */
+
+enum sql_db_flags {
+	/* Set if queries are not executed asynchronously */
+	SQL_DB_FLAG_BLOCKING		= 0x01,
+	/* Set if database wants to use connection pooling */
+	SQL_DB_FLAG_POOLED		= 0x02,
+	/* Prepared statements are supported by the database. If they aren't,
+	   the functions can still be used, but they're just internally
+	   convered into regular statements. */
+	SQL_DB_FLAG_PREP_STATEMENTS	= 0x04,
+	/* Database supports INSERT .. ON DUPLICATE KEY syntax. */
+	SQL_DB_FLAG_ON_DUPLICATE_KEY	= 0x08,
+	/* Database supports INSERT .. ON CONFLICT DO UPDATE syntax. */
+	SQL_DB_FLAG_ON_CONFLICT_DO	= 0x10,
+};
+
+enum sql_field_type {
+	SQL_TYPE_STR,
+	SQL_TYPE_UINT,
+	SQL_TYPE_ULLONG,
+	SQL_TYPE_BOOL
+};
+
+struct sql_field_def {
+	enum sql_field_type type;
+	const char *name;
+	size_t offset;
+};
+
+enum sql_result_error_type {
+	SQL_RESULT_ERROR_TYPE_UNKNOWN = 0,
+	/* It's unknown whether write succeeded or not. This could be due to
+	   a timeout or a disconnection from server. */
+	SQL_RESULT_ERROR_TYPE_WRITE_UNCERTAIN
+};
+
+enum sql_result_next {
+	/* Row was returned */
+	SQL_RESULT_NEXT_OK = 1,
+	/* There are no more rows */
+	SQL_RESULT_NEXT_LAST = 0,
+	/* Error occurred - see sql_result_get_error*() */
+	SQL_RESULT_NEXT_ERROR = -1,
+	/* There are more results - call sql_result_more() */
+	SQL_RESULT_NEXT_MORE = -99
+};
+
+#define SQL_DEF_STRUCT(name, struct_name, type, c_type) \
+	{ (type) + COMPILE_ERROR_IF_TYPES_NOT_COMPATIBLE( \
+		((struct struct_name *)0)->name, c_type), \
+	  #name, offsetof(struct struct_name, name) }
+
+#define SQL_DEF_STRUCT_STR(name, struct_name) \
+	SQL_DEF_STRUCT(name, struct_name, SQL_TYPE_STR, const char *)
+#define SQL_DEF_STRUCT_UINT(name, struct_name) \
+	SQL_DEF_STRUCT(name, struct_name, SQL_TYPE_UINT, unsigned int)
+#define SQL_DEF_STRUCT_ULLONG(name, struct_name) \
+	SQL_DEF_STRUCT(name, struct_name, SQL_TYPE_ULLONG, unsigned long long)
+#define SQL_DEF_STRUCT_BOOL(name, struct_name) \
+	SQL_DEF_STRUCT(name, struct_name, SQL_TYPE_BOOL, bool)
+
+struct sql_db;
+struct sql_result;
+
+struct sql_commit_result {
+	const char *error;
+	enum sql_result_error_type error_type;
+};
+
+struct sql_settings {
+	const char *driver;
+	const char *connect_string;
+	struct event *event_parent;
+};
+
+typedef void sql_query_callback_t(struct sql_result *result, void *context);
+typedef void sql_commit_callback_t(const struct sql_commit_result *result, void *context);
+
+void sql_drivers_init(void);
+void sql_drivers_deinit(void);
+
+/* register all built-in SQL drivers */
+void sql_drivers_register_all(void);
+
+void sql_driver_register(const struct sql_db *driver);
+void sql_driver_unregister(const struct sql_db *driver);
+
+/* Initialize database connections. db_driver is the database driver name,
+   eg. "mysql" or "pgsql". connect_string is driver-specific. */
+struct sql_db *sql_init(const char *db_driver, const char *connect_string);
+int sql_init_full(const struct sql_settings *set, struct sql_db **db_r,
+		  const char **error_r);
+
+void sql_ref(struct sql_db *db);
+void sql_unref(struct sql_db **db);
+
+/* Returns SQL database state flags. */
+enum sql_db_flags sql_get_flags(struct sql_db *db);
+
+/* Explicitly connect to the database. It's not required to call this function
+   though. Returns -1 if we're not connected, 0 if we started connecting or
+   1 if we are fully connected now. */
+int sql_connect(struct sql_db *db);
+/* Explicitly disconnect from database and abort pending auth requests. */
+void sql_disconnect(struct sql_db *db);
+
+/* Escape the given string if needed and return it. */
+const char *sql_escape_string(struct sql_db *db, const char *string);
+/* Escape the given data as a string. */
+const char *sql_escape_blob(struct sql_db *db,
+			    const unsigned char *data, size_t size);
+
+/* Execute SQL query without waiting for results. */
+void sql_exec(struct sql_db *db, const char *query);
+/* Execute SQL query and return result in callback. If fields list is given,
+   the returned fields are validated to be of correct type, and you can use
+   sql_result_next_row_get() */
+void sql_query(struct sql_db *db, const char *query,
+	       sql_query_callback_t *callback, void *context);
+#define sql_query(db, query, callback, context) \
+	sql_query(db, query - \
+		CALLBACK_TYPECHECK(callback, void (*)( \
+			struct sql_result *, typeof(context))), \
+		(sql_query_callback_t *)callback, context)
+/* Execute blocking SQL query and return result. */
+struct sql_result *sql_query_s(struct sql_db *db, const char *query);
+
+struct sql_prepared_statement *
+sql_prepared_statement_init(struct sql_db *db, const char *query_template);
+void sql_prepared_statement_unref(struct sql_prepared_statement **prep_stmt);
+
+struct sql_statement *
+sql_statement_init(struct sql_db *db, const char *query_template);
+struct sql_statement *
+sql_statement_init_prepared(struct sql_prepared_statement *prep_stmt);
+void sql_statement_abort(struct sql_statement **stmt);
+void sql_statement_set_timestamp(struct sql_statement *stmt,
+				 const struct timespec *ts);
+void sql_statement_bind_str(struct sql_statement *stmt,
+			    unsigned int column_idx, const char *value);
+void sql_statement_bind_binary(struct sql_statement *stmt,
+			       unsigned int column_idx, const void *value,
+			       size_t value_size);
+void sql_statement_bind_int64(struct sql_statement *stmt,
+			      unsigned int column_idx, int64_t value);
+void sql_statement_query(struct sql_statement **stmt,
+			 sql_query_callback_t *callback, void *context);
+#define sql_statement_query(stmt, callback, context) \
+	sql_statement_query(stmt, \
+		(sql_query_callback_t *)callback, TRUE ? context : \
+		CALLBACK_TYPECHECK(callback, void (*)( \
+			struct sql_result *, typeof(context))))
+struct sql_result *sql_statement_query_s(struct sql_statement **stmt);
+
+void sql_result_setup_fetch(struct sql_result *result,
+			    const struct sql_field_def *fields,
+			    void *dest, size_t dest_size);
+
+/* Go to next row. See enum sql_result_next. */
+int sql_result_next_row(struct sql_result *result);
+
+/* If sql_result_next_row() returned SQL_RESULT_NEXT_MORE, this can be called
+   to continue returning more results. The result is freed with this call, so
+   it must not be accesed anymore until the callback is finished. */
+void sql_result_more(struct sql_result **result,
+		     sql_query_callback_t *callback, void *context);
+#define sql_result_more(result, callback, context) \
+	sql_result_more(result - \
+		CALLBACK_TYPECHECK(callback, void (*)( \
+			struct sql_result *, typeof(context))), \
+		(sql_query_callback_t *)callback, context)
+/* Synchronous version of sql_result_more(). The result will be replaced with
+   the new result. */
+void sql_result_more_s(struct sql_result **result);
+
+void sql_result_ref(struct sql_result *result);
+/* Needs to be called only with sql_query_s() or when result has been
+   explicitly referenced. */
+void sql_result_unref(struct sql_result *result);
+
+/* Return number of fields in result. */
+unsigned int sql_result_get_fields_count(struct sql_result *result);
+/* Return name of the given field index. */
+const char *sql_result_get_field_name(struct sql_result *result,
+				      unsigned int idx);
+/* Return field index for given name, or -1 if not found. */
+int sql_result_find_field(struct sql_result *result, const char *field_name);
+
+/* Returns value of given field as string. Note that it can be NULL. */
+const char *sql_result_get_field_value(struct sql_result *result,
+				       unsigned int idx);
+/* Returns a binary value. Note that a NULL is returned as NULL with size=0,
+   while empty string returns non-NULL with size=0. */
+const unsigned char *
+sql_result_get_field_value_binary(struct sql_result *result,
+				  unsigned int idx, size_t *size_r);
+/* Find the field and return its value. NULL return value can mean that either
+   the field didn't exist or that its value is NULL. */
+const char *sql_result_find_field_value(struct sql_result *result,
+					const char *field_name);
+/* Return all values of current row. Note that this array is not
+   NULL-terminated - you must use sql_result_get_fields_count() to find out
+   the array's length. It's also possible that some of the values inside the
+   array are NULL. */
+const char *const *sql_result_get_values(struct sql_result *result);
+
+/* Return last error message in result. */
+const char *sql_result_get_error(struct sql_result *result);
+enum sql_result_error_type sql_result_get_error_type(struct sql_result *result);
+
+/* Begin a new transaction. Currently you're limited to only one open
+   transaction at a time. */
+struct sql_transaction_context *sql_transaction_begin(struct sql_db *db);
+/* Commit transaction. */
+void sql_transaction_commit(struct sql_transaction_context **ctx,
+			    sql_commit_callback_t *callback, void *context);
+#define sql_transaction_commit(ctx, callback, context) \
+	  sql_transaction_commit(ctx - \
+		CALLBACK_TYPECHECK(callback, void (*)( \
+			const struct sql_commit_result *, typeof(context))), \
+		(sql_commit_callback_t *)callback, context)
+/* Synchronous commit. Returns 0 if ok, -1 if error. */
+int sql_transaction_commit_s(struct sql_transaction_context **ctx,
+			     const char **error_r);
+void sql_transaction_rollback(struct sql_transaction_context **ctx);
+
+/* Execute query in given transaction. */
+void sql_update(struct sql_transaction_context *ctx, const char *query);
+void sql_update_stmt(struct sql_transaction_context *ctx,
+		     struct sql_statement **stmt);
+/* Save the number of rows updated by this query. The value is set before
+   commit callback is called. */
+void sql_update_get_rows(struct sql_transaction_context *ctx, const char *query,
+			 unsigned int *affected_rows);
+void sql_update_stmt_get_rows(struct sql_transaction_context *ctx,
+			      struct sql_statement **stmt,
+			      unsigned int *affected_rows);
+
+/* Wait for SQL query results. */
+void sql_wait(struct sql_db *db);
+
+#endif