metadata_cell.h

Go to the documentation of this file.

#ifndef __METADATA_CELL_H__
#define __METADATA_CELL_H__

/**
 * File Name  : metadata_cell.h
 *
 * Description: Data for single cell in a metadata table.
 *              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>

G_BEGIN_DECLS

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

typedef enum
{
    METADATA_NULL = 0,          // SQLCELL_NULL must be zero for easy init
    METADATA_INT64,
    METADATA_DOUBLE,
    METADATA_TEXT,
    METADATA_BLOB,
    NUM_METADATA_TYPES
} metadata_cell_type;


typedef struct
{
    GString             *name;          // optional
    metadata_cell_type  type;
    union
    {
        gint64          v_int64;
        gdouble         v_double;
        GString         *v_text;
        struct
        {
            guint       len;
            gboolean    data_is_static; // TRUE  : leave data block as is
                                        // FALSE : g_free() data when no longer needed
            const gchar *data;
        }               v_blob;
    }                   value;
} metadata_cell;


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

/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_clear
 *
 * @brief  Clear the content (name, value) of a metadata_cell
 *
 * @param  thiz - the metadata_cell
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
void metadata_cell_clear (metadata_cell *thiz);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_clear_value
 *
 * @brief  Clear the value of a metadata_cell, leave its name as is
 *
 * @param  thiz - the metadata_cell
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
void metadata_cell_clear_value (metadata_cell *thiz);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_copy_value
 *
 * @brief  Copy the value of a metadata_cell, leave target name as is
 *
 * @param  [out] thiz - the metadata_cell to copy into
 * @param  [in]  src - the metadata_cell to copy from
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_cell_copy_value (metadata_cell *thiz, const metadata_cell *src);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_set_name
 *
 * @brief  Set the name of a metadata_cell
 *
 * @param  thiz - the metadata_cell
 * @param  [in] name - the new cell-name, or NULL to clear name
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_cell_set_name (metadata_cell *thiz, const char *name);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_set_null
 *
 * @brief  Assign a NULL value to a metadata_cell
 *
 * @param  thiz - the metadata_cell
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
#define metadata_cell_set_null(cell)     metadata_cell_clear_value(cell)

/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_set_int64
 *
 * @brief  Assign an integer value to a metadata_cell
 *
 * @param  thiz - the metadata_cell
 * @param  [in] value - integer value (gint64)
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_cell_set_int64 (metadata_cell *thiz, const gint64 value);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_set_double
 *
 * @brief  Assign a floating point value to a metadata_cell
 *
 * @param  thiz - the metadata_cell
 * @param  [in] value - floating point value (double)
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_cell_set_double (metadata_cell *thiz, const double value);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_set_text
 *
 * @brief  Assign a string value to a metadata_cell
 *
 * @param  thiz - the metadata_cell
 * @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_cell_set_text (metadata_cell *thiz, const char *value);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_set_blob
 *
 * @brief  Assign a blob to a metadata_cell
 *         BLOB = Binary Large OBject
 *
 * @param  thiz - the metadata_cell
 * @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_cell_set_blob (metadata_cell *thiz, gchar *value, const guint len);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_set_blob_static
 *
 * @brief  Assign a blob to a metadata_cell, assuming blob is static data
 *         BLOB = Binary Large OBject
 *
 * @param  thiz - the metadata_cell
 * @param  [in] value - binary value
 *                      Note: The metadata_cell will NOT release this memory block
 *                            so caller must ensure the data stays available for
 *                            as long as 'thiz' metadata_cell exists
 *                            or until a new value is assigned to 'thiz' cell.
 * @param  [in] len - length of value in bytes
 *
 * @return ER_OK or error code
 *
 *--------------------------------------------------------------------------*/
int metadata_cell_set_blob_static (metadata_cell *thiz, const gchar *value, const guint len);


/**---------------------------------------------------------------------------
 *
 * Name :  metadata_cell_get_string
 *
 * @brief  Report the value of a metadata_cell converted to a UTF-8 text string
 *         Not possible for SQLCELL_BLOB types
 *
 * @param  thiz - the metadata_cell
 *
 * @return cell value as a zero-terminated GString, or NULL when error
 *         caller must release this GString using g_string_free(string, TRUE)
 *
 *--------------------------------------------------------------------------*/
GString *metadata_cell_get_string (const metadata_cell *thiz);

G_END_DECLS

#endif // __METADATA_CELL_H__