metadata_table.h

Go to the documentation of this file.

#ifndef __METADATA_TABLE_H__
#define __METADATA_TABLE_H__

/**
 * File Name  : metadata_table.h
 *
 * Description: Table with metadata, usually results of a sql query.
 *              This type is designed for easy compatibility with sqlite3.
 */

/*
 * 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 "metadata_cell.h"

G_BEGIN_DECLS


//----------------------------------------------------------------------------
// Macro Definitions
//---------------------------------------------------------------------------- 

#define metadata_table_n_rows(table)                     (table ? (table)->n_rows    : 0   )
#define metadata_table_n_columns(table)                  (table ? (table)->n_columns : 0   )
#define metadata_table_data(table)                       (table ? (table)->cell_data : NULL)
#define metadata_table_cell_index(table, row, column)    (table ? (((row) * (table)->n_columns) + (column)) : 0)


//----------------------------------------------------------------------------
// Type Declarations
//----------------------------------------------------------------------------

typedef struct
{
    guint       n_rows;         // number of rows
    guint       n_columns;      // number of columns
    GArray      *cell_data;     // data as an array of metadata_cell
} metadata_table;


//============================================================================
// Public Functions
//============================================================================

/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_new
 *
 * @brief  Create a new metadata_table
 *
 * @param  --
 *
 * @return Pointer to the newly created table, or NULL
 *
 *--------------------------------------------------------------------------*/
metadata_table *metadata_table_new (void);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_free
 *
 * @brief  Free the memory allocated to a metadata_table and the elements it holds
 *         and clear the pointer passed as argument.
 *         Function is void when a NULL pointer is passed.
 *
 * @param  thiz - the metadata_table to be freed
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
#define metadata_table_free(table)           \
        {                                    \
            metadata_table_free_impl(table); \
            (table) = NULL;                  \
        }
void metadata_table_free_impl (metadata_table *thiz);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_dump
 *
 * @brief  Dump content of a metadata_table,
 *
 * @param  thiz - the metadata_table
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
#if QUERY_ON
#define metadata_table_dump(thiz)  metadata_table_dump_impl(thiz)
#else
#define metadata_table_dump(thiz)
#endif
void metadata_table_dump_impl (const metadata_table *thiz);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_add_column
 *
 * @brief  Add a column at the end of the table,
 *         only allowed on empty table or table with one row
 *
 * @param  thiz - the metadata_table
 * @param  [in]  name - name of the column to be added
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_table_add_column (metadata_table *thiz, const char *name);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_find_column
 *
 * @brief  Find column by its name
 *
 * @param  thiz - the metadata_table
 * @param  [in]  name - name of the column to be found
 *
 * @return index of the column (0 ...), or -1 on error
 *
 *--------------------------------------------------------------------------*/
int metadata_table_find_column (const metadata_table *thiz, const char *name);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_set_int64
 *
 * @brief  Assign an integer value to a specific cell in a sql table
 *
 * @param  thiz - the metadata_table
 * @param  [in] idx - cell index (0 ...)
 * @param  [in] value - integer value (gint64)
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_table_set_int64 (metadata_table *thiz, const guint idx, const gint64 value);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_set_double
 *
 * @brief  Assign a floating point value to a specific cell in a sql table
 *
 * @param  thiz - the metadata_table
 * @param  [in] idx - cell index (0 ...)
 * @param  [in] value - floating point value (double)
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_table_set_double (metadata_table *thiz, const guint idx, const double value);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_set_text
 *
 * @brief  Assign a string value to a specific cell in a sql table
 *         This may move data already in the table to another memory location
 *
 * @param  thiz - the metadata_table
 * @param  [in] idx - cell index (0 ...)
 * @param  [in] value - string value
 *                      Note: The value is copied into metadata_cell,
 *                            so caller keeps ownership and must eventually free it.
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_table_set_text (metadata_table *thiz, const guint idx, const char *value);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_set_blob
 *
 * @brief  Assign a blob to a specific cell in a sql table
 *         BLOB = Binary Large OBject
 *
 * @param  thiz - the metadata_table
 * @param  [in] idx - cell index (0 ...)
 * @param  [in] value - binary value
 *                      Note: The value is "swallowed" by the metadata_cell
 *                            so caller looses ownership and must drop all pointers to it.
 *                            The metadata_cell will eventually release it with g_free()
 *                            so caller must have allocated it with g_new() or g_malloc().
 * @param  [in] len - length of value in bytes
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_table_set_blob (metadata_table *thiz, const guint idx, gchar *value, const guint len);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_get_cell
 *
 * @brief  Report the value of a specific cell in a metadata_table
 *
 * @param  thiz - the metadata_table
 * @param  [in]  idx - cell index (0 ...)
 *
 * @return cell value as a metadata_cell  -- DO NOT MODIFY
 *         or NULL when error
 *
 *--------------------------------------------------------------------------*/
const metadata_cell* metadata_table_get_cell (const metadata_table *thiz, const guint idx);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_table_get_string
 *
 * @brief  Report the value of a specific cell in a metadata_table,
 *         converted to a UTF-8 text string
 *         Not possible for SQLCELL_BLOB types
 *
 * @param  thiz - the metadata_table
 * @param  [in]  idx - cell index (0 ...)
 *
 * @return cell value as a zero-terminated GString, or NULL when error
 *         caller must release this string using g_string_free(string, TRUE)
 *
 *--------------------------------------------------------------------------*/
GString *metadata_table_get_string (const metadata_table *thiz, const guint idx);

G_END_DECLS

#endif // __METADATA_TABLE_H__