sqlite3_wrapper.h

Go to the documentation of this file.

#ifndef __SQLITE3_WRAPPER_H__
#define __SQLITE3_WRAPPER_H__

/**
 * File Name  : sqlite3_wrapper.h
 *
 * Description: Wrapper layer around the sqlite3 C API
 */

/*
 * This file is part of libermetadb.
 *
 * libermetadb 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 2 of the License, or
 * (at your option) any later version.
 *
 * libermetadb 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/>.
 */

/**
 * Copyright (C) 2008 iRex Technologies B.V.
 * All rights reserved.
 */


//----------------------------------------------------------------------------
// Include Files
//----------------------------------------------------------------------------

#include <glib.h>

#include "ermetadb.h"
#include "metadata_table.h"

G_BEGIN_DECLS

/**---------------------------------------------------------------------------
 *
 * Name :  sql3_execute_query
 *
 * @brief  Execute sql query.
 *         A convenience wrapper around sql3_prepare_statements(), sql3_execute_statements(),
 *         sql3_finalize_statements() for queries that have no parameters.
 *
 * @param  [in]  db - sqlite database object
 * @param  [in]  sql - SQL statement(s) as text
 * @param  [in]  parameters - metadata_table with parameters (value), or NULL
 *                            table must have exactly one row
 * @param  [in]  result_table - location to store metadata_table holding query results,
 *                              or NULL when caller is not interested in query results
 * @param  [out] result_table - metadata_table holding query results, or NULL when no results
 *                              First row holds column names and cell values,
 *                              other rows hold cell values only.
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int sql3_execute_query (       sqlite3        *db,
                         const char           *sql,
                         const metadata_table *parameters,
                               metadata_table **result_table );


/**---------------------------------------------------------------------------
 *
 * Name :  sql3_begin_transaction
 *
 * @brief  Start a database transaction.
 *         Transactions may be nested, as long as the calls to sql3_begin_transaction() and
 *         sql3_begin_transaction_readonly() are balanced with calls to sql3_commit_or_rollback.
 *
 * @param  [in]  thiz - erMetadb object on which to start a transaction
 *
 * @return ER_OK or error
 *
 *--------------------------------------------------------------------------*/
int sql3_begin_transaction (erMetadb thiz);


/**---------------------------------------------------------------------------
 *
 * Name :  sql3_begin_transaction_readonly
 *
 * @brief  Start a read-only database transaction.
 *         Transactions may be nested, as long as the calls to sql3_begin_transaction() and
 *         sql3_begin_transaction_readonly() are balanced with calls to sql3_commit_or_rollback.
 *
 * @param  [in]  thiz - erMetadb object on which to start a transaction
 *
 * @return ER_OK or error
 *
 *--------------------------------------------------------------------------*/
int sql3_begin_transaction_readonly (erMetadb thiz);


/**---------------------------------------------------------------------------
 *
 * Name :  sql3_commit_or_rollback
 *
 * @brief  Commit or rollback a database transaction
 *         Transactions may be nested, as long as the calls to sql3_begin_transaction()
 *         are balanced with calls to sql3_commit_or_rollback.
 *         Superfluous calls to sql3_commit_or_rollback are allowed.
 *
 * @param  [in]  thiz - erMetadb object on which to end a transaction
 * @param  [in]  err - ER_OK or error code
 *
 * @return ER_OK or error
 *         or 'err' value when this is not ER_OK
 *
 *--------------------------------------------------------------------------*/
int sql3_commit_or_rollback (erMetadb thiz, int err);


/**---------------------------------------------------------------------------
 *
 * Name :  sql3_strcase_cmp
 *
 * @brief  Compare function to be used in custom collation sequence
 *         See documentation on sqlite3_create_collation() for details
 *
 *--------------------------------------------------------------------------*/
int sql3_strcase_compare( void        *user_data,
                          int         left_len,
                          const void  *left_void,
                          int         right_len,
                          const void  *right_void );

G_END_DECLS

#endif // __SQLITE3_WRAPPER_H__