hedera/db/db-model.h

/*
 * Copyright (C) 2012 - Juan Ferrer Toribio
 *
 * This file is part of Hedera.
 *
 * Hedera 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, either version 3 of the License, or
 * (at your option) any later version.
 *
 * 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/>.
 */

#ifndef DB_MODEL_H
#define DB_MODEL_H

#include <sql/sql.h>
#include "db-conn.h"
#include "db-iter.h"

#define DB_MODEL_LOG_DOMAIN		(g_quark_from_string ("DbModel"))

#define DB_TYPE_MODEL				(db_model_get_type())
#define DB_MODEL(self)				(G_TYPE_CHECK_INSTANCE_CAST ((self), DB_TYPE_MODEL, DbModel))
#define DB_IS_MODEL(self)			(G_TYPE_CHECK_INSTANCE_TYPE ((self), DB_TYPE_MODEL))
#define DB_MODEL_CLASS(klass)		(G_TYPE_CHECK_CLASS_CAST ((klass), DB_TYPE_MODEL, DbModelClass))
#define DB_IS_MODEL_CLASS(klass)	(G_TYPE_CHECK_CLASS_TYPE ((klass), DB_TYPE_MODEL))
#define DB_MODEL_GET_CLASS(self)	(G_TYPE_INSTANCE_GET_CLASS ((self), DB_TYPE_MODEL, DbModelClass))

#define DB_TYPE_MODEL_UPDATE_FLAGS	(db_model_update_flags_get_type())

typedef struct _DbModel			DbModel;
typedef struct _DbModelClass	DbModelClass;
typedef struct _DbModelPrivate	DbModelPrivate;

/**
 * DbModelRowOp:
 * @DB_MODEL_ROW_OP_INSERT: an INSERT operation 
 * @DB_MODEL_ROW_OP_DELETE: a DELETE operation
 * @DB_MODEL_ROW_OP_UPDATE: an UPDATE operation
 * 
 * Flags stating the changes made over a row.
 * 
 * If a DELETE is taking place on a row at the same time of another operation,
 * the changes won't be performed and the row will be deleted. Every INSERT
 * operation must have an UPDATE operation to add data, otherwise all data will
 * get filled with the values set by default by the DB. Each UPDATE operation
 * will merge with the previous ones and substitute the values already set by
 * these.
 **/
typedef enum
{
	 DB_MODEL_ROW_OP_INSERT = 1 << 0
	,DB_MODEL_ROW_OP_DELETE = 1 << 1
	,DB_MODEL_ROW_OP_UPDATE = 1 << 2
}
DbModelRowOp;

/**
 * DbModelError:
 * @DB_MODEL_ERROR_NOT_READY: the model data is not completely loaded yet
 * @DB_MODEL_ERROR_NOT_UPDATABLE: a changed model column cannot be updated
 * @DB_MODEL_ERROR_OUT_OF_RANGE: an index is out of the column range
 * 
 * Error codes of a #DbModel.
 **/
typedef enum
{
	 DB_MODEL_ERROR_NOT_READY
	,DB_MODEL_ERROR_NOT_UPDATABLE
	,DB_MODEL_ERROR_OUT_OF_RANGE
}
DbModelError;

/**
 * DbModelUpdateFlags:
 * @DB_MODEL_INSERT: rows can be inserted into the model
 * @DB_MODEL_DELETE: it's possible to delete rows from the model
 * @DB_MODEL_UPDATE: the values of the model can be changed
 * 
 * Indicates which operations are allowed for the user in a #DbModel.
 **/
typedef enum
{
	 DB_MODEL_INSERT = 1 << 0
	,DB_MODEL_DELETE = 1 << 1
	,DB_MODEL_UPDATE = 1 << 2
	/* <private> */
	,DB_MODEL_ALL = DB_MODEL_INSERT | DB_MODEL_DELETE | DB_MODEL_UPDATE
}
DbModelUpdateFlags;

/**
 * DbModelStatus:
 * @DB_MODEL_STATUS_ERROR: there has been an error while executing the main
 * statement of a #DbModel
 * @DB_MODEL_STATUS_LOADING: the statement is being executed
 * @DB_MODEL_STATUS_READY: the statement execution is over and the data is
 * available on the #DbModel
 * @DB_MODEL_STATUS_CLEAN: the #DbModel is created but the statement has not
 * been executed yet
 * 
 * These constants indicate the status of the model. This status depends on the
 * execution of the stamtement (@stmt property)of a #DbModel. They are returned
 * by db_model_get_status().
 **/
typedef enum
{
	 DB_MODEL_STATUS_ERROR
	,DB_MODEL_STATUS_LOADING
	,DB_MODEL_STATUS_READY
	,DB_MODEL_STATUS_CLEAN
}
DbModelStatus;

/**
 * DbModelMode:
 * @DB_MODEL_MODE_ON_CHANGE: every change made in the model will be immediatelly 
 * sent to the database
 * @DB_MODEL_MODE_ON_DEMAND: nothing will be sent to the database since demanded
 * by calling db_model_perform_operations()
 * 
 * The working mode of a #DbModel, depending on which the changes made on it
 * will be sent to the database or will be made only locally.
 * The same methods are used to modify the model in both modes 
 * (db_model_set_value(), db_model_insert() and db_model_delete()). 
 **/
typedef enum
{
	 DB_MODEL_MODE_ON_CHANGE
	,DB_MODEL_MODE_ON_DEMAND
}
DbModelMode;

/**
 * DbSortType:
 * @DB_SORT_ASCENDING: Ascending sort order
 * @DB_SORT_DESCENDING: Descending sort order
 * 
 * Determines the direction of a sort.
 **/
typedef enum
{
	 DB_SORT_ASCENDING
	,DB_SORT_DESCENDING
}
DbSortType;

/**
 * DbIterCompareFunc:
 * @model: a #DbModel
 * @a: a #DbIter
 * @b: a #DbIter
 * @user_data: (closure): user-provided data to use while comparing two #DbIter
 * 
 * Prototype of a function used to search some in a model using
 * #DbIter to iterate through it.
 **/
typedef gint (*DbIterCompareFunc)	(DbModel * model
									,DbIter * a
									,DbIter * b
									,gpointer user_data);

struct _DbModel
{
	GObject parent;
	DbModelPrivate * priv;
};

struct _DbModelClass
{
	/* <private> */
	GObjectClass parent;
};

GType			db_model_get_type				();
GType			db_model_update_flags_get_type	() G_GNUC_CONST;

DbModel *		db_model_new				(DbConn * conn, SqlStmt * stmt);
DbModel *		db_model_new_with_sql		(DbConn * conn, const gchar * sql);
DbModel *		db_model_new_with_file		(DbConn * conn, const gchar * file);
DbConn *		db_model_get_conn			(DbModel * self);
void			db_model_set_conn			(DbModel * self, DbConn * conn);
const GvnParamSpec * db_model_get_spec		(DbModel * self, gint col);
const gchar *	db_model_get_column_name	(DbModel * self, gint col);
gint			db_model_get_column_index	(DbModel * self, const gchar * name);
void			db_model_refresh			(DbModel * self);
const SqlStmt *	db_model_get_stmt			(DbModel * self);
void			db_model_set_stmt			(DbModel * self, SqlStmt * stmt);
void			db_model_add_pre_stmt		(DbModel * self, SqlStmt * stmt);
void			db_model_add_post_stmt		(DbModel * self, SqlStmt * stmt);
DbModelStatus	db_model_get_status			(DbModel * self);
const gchar *	db_model_get_main_table		(DbModel * self);
DbModelUpdateFlags db_model_get_update_flags	(DbModel * self);
void			db_model_request_update_flags	(DbModel * self
											,DbModelUpdateFlags flags);
void			db_model_unset_update_flags	(DbModel * self
											,DbModelUpdateFlags flags);
void			db_model_set_mode			(DbModel * self, DbModelMode mode);
DbModelMode		db_model_get_mode			(DbModel * self);
void			db_model_toggle_mode		(DbModel * self);
void			db_model_use_null_row		(DbModel * self, gboolean use);
gboolean		db_model_get_last			(DbModel * self, DbIter * iter);
void			db_model_get				(DbModel * self
											,DbIter * iter
											,...);
void			db_model_set				(DbModel * self
											,DbIter * iter
											,...);
const GValue *	db_model_get_value			(DbModel * self,
											DbIter * iter,
											gint col,
											GError ** err);
gboolean		db_model_set_value			(DbModel * self,
											DbIter * iter,
											gint col,
											const GValue * value,
											GError ** err);
gboolean		db_model_insert				(DbModel * self, DbIter * iter);
void			db_model_delete				(DbModel * self, DbIter * iter);
DbModelRowOp	db_model_get_row_operations	(DbModel * self, DbIter * iter);
gboolean		db_model_has_pending_operations (DbModel * self);
void			db_model_perform_operations	(DbModel * self, gboolean retry);
void			db_model_reverse_operations	(DbModel * self);
void			db_model_order_by			(DbModel * self,
											gint col,
											DbSortType order);
gboolean		db_model_search				(DbModel * self,
											gint col,
											DbIter * iter,
											gpointer content);
gboolean		db_model_search_value		(DbModel * self,
											gint col,
											DbIter * iter,
											const GValue * value);
gint			db_model_get_nrows			(DbModel * self);
gboolean		db_model_iter_is_valid		(DbIter * iter
											,DbModel * model);
void			db_model_add_join			(DbModel * self
											,const gchar * master_field
											,const gchar * slave_field);
SqlBatch *		db_model_get_batch			(DbModel * self);
void			db_model_set_batch			(DbModel * self, SqlBatch * batch);

void			db_model_set_default_value_from_column	(DbModel * self, const gchar * field_str, const gchar * column_str);
void			db_model_set_default_value_from_param	(DbModel * self, const gchar * field_str, GvnParam * param, gboolean link);

//GtkTreeModel-like methods

gint		db_model_get_ncols				(DbModel * self);
GType		db_model_get_column_type		(DbModel * self, gint index);
gboolean	db_model_get_iter_first			(DbModel * self, DbIter * iter);
gboolean	db_model_get_iter				(DbModel * self,
											DbIter * iter,
											gint path);
gint		db_model_get_path				(DbModel * self, DbIter * iter);
gboolean	db_model_iter_next				(DbModel * self, DbIter * iter);
gboolean	db_model_iter_prev				(DbModel * self, DbIter * iter);
void		db_model_ref_node				(DbModel * self, DbIter * iter);
void		db_model_unref_node				(DbModel * self, DbIter * iter);

//GtkTreeSortable-like methods

gboolean	db_model_get_sort_column_id		(DbModel * self,
											gint * sort_column_id,
											DbSortType * order);
void		db_model_set_sort_column_id		(DbModel * self,
											gint sort_column_id,
											DbSortType order);
void		db_model_set_sort_func			(DbModel * self,
											gint sort_column_id,
											DbIterCompareFunc func,
											gpointer data,
											GDestroyNotify destroy);
void		db_model_set_default_sort_func	(DbModel * self,
											DbIterCompareFunc func,
											gpointer data,
											GDestroyNotify destroy);
gboolean	db_model_has_default_sort_func	(DbModel * self);

#endif