psMetadata.h

Go to the documentation of this file.

/** @file  psMetadata.h
*
*  @brief Contains metadata struuctures, enumerations and functions prototypes
*
*  This file defines metadata item, metadata type, metadata flags, metadata containers, and function
*  prototypes necessary creating psLib metadata APIs
*
*  @ingroup Metadata
*
*  @author Robert DeSonia, MHPCC
*  @author Ross Harman, MHPCC
*
*  @version $Revision: 1.42 $ $Name: rel5_0 $
*  @date $Date: 2005/03/29 22:13:53 $
*
*  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
*/
#ifndef PS_METADATA_H
#define PS_METADATA_H

#include <stdarg.h>
#include <stdio.h>
#include <sys/types.h>
#include <regex.h>

#include "psHash.h"
#include "psList.h"
#include "psImage.h"
#include "psLookupTable.h"

/// @addtogroup Metadata
/// @{

/** Metadata item type.
 *
 * Enumeration for maintaining metadata item types.
 */
typedef enum {
    PS_META_S32 = PS_TYPE_S32,         ///< psS32 primitive data.
    PS_META_F32 = PS_TYPE_F32,         ///< psF32 primitive data.
    PS_META_F64 = PS_TYPE_F64,         ///< psF64 primitive data.
    PS_META_BOOL = PS_TYPE_BOOL,       ///< psBool primitive data.
    PS_META_LIST = 0x10000,            ///< List data (Stored as item.data.list).
    PS_META_STR,                       ///< String data (Stored as item.data.V).
    PS_META_VEC,                       ///< Vector data (Stored as item.data.V).
    PS_META_IMG,                       ///< Image data (Stored as item.data.V).
    PS_META_HASH,                      ///< Hash data (Stored as item.data.V).
    PS_META_LOOKUPTABLE,               ///< Lookup table data (Stored as item.data.V).
    PS_META_JPEG,                      ///< JPEG data (Stored as item.data.V).
    PS_META_PNG,                       ///< PNG data (Stored as item.data.V).
    PS_META_ASTROM,                    ///< Astrometric coefficients (Stored as item.data.V).
    PS_META_UNKNOWN,                   ///< Other data (Stored as item.data.V).
    PS_META_MULTI                      ///< Used internally, do not create an metadata item of this type.
} psMetadataType;

#define PS_META_IS_PRIMITIVE(TYPE) \
(TYPE == PS_META_S32 || \
 TYPE == PS_META_F32 || \
 TYPE == PS_META_F64 || \
 TYPE == PS_META_BOOL)

#define PS_META_PRIMITIVE_TYPE(METATYPE) ( \
        (METATYPE==PS_META_S32) ? PS_TYPE_S32 : \
        (METATYPE==PS_META_F32) ? PS_TYPE_F32 : \
        (METATYPE==PS_META_F64) ? PS_TYPE_F64 : \
        (METATYPE==PS_META_BOOL) ? PS_TYPE_BOOL : PS_TYPE_PTR )

/** Option flags for psMetadata functions
 *
 *  Enumeration for the modification of the behaviour in psMetadataAddItem.
 * 
 *  @see psMetadataAddItem
 */
typedef enum {
    PS_META_DEFAULT = 0,               ///< default behaviour (duplicate entry is an error)
    PS_META_REPLACE = 0x1000000,       ///< allow entry to be replaced
    PS_META_DUPLICATE_OK = 0x2000000   ///< allow duplicate entries
} psMetadataFlags;

#define PS_METADATA_FLAGS_MASK 0xFF000000
#define PS_METADATA_TYPE_MASK 0x00FFFFFF

/** Metadata data structure.
 *
 *  Struct for holding metadata items. Metadata items are held in two
 *  containers. The first employs a doubly-linked list to preserve the order
 *  of the metadata. The second container employs a hash table which
 *  allows fast lookup when given a metadata keyword.
 */
typedef struct psMetadata
{
    psList*  list;                     ///< Metadata in linked-list
    psHash*  table;                    ///< Metadata in a hash table
}
psMetadata;

/** Metadata iterator
 *
 *  Iterator for metadata.
 */
typedef struct
{
    psListIterator* iter;              ///< iterator for the psMetadata's psList
    regex_t* preg;                     ///< the subsetting regular expression
}
psMetadataIterator;


/** Metadata item data structure.
 *
 * Struct for maintaining metadata items of varying types. It also contains
 * information about the item name, flags, comments, and other items with the same name.
 */
typedef struct psMetadataItem
{
    const psS32 id;                    ///< Unique ID for metadata item.
    char *name;                        ///< Name of metadata item.
    psMetadataType type;               ///< Type of metadata item.
    union {
        psBool B;                      ///< boolean data
        psS32 S32;                     ///< Signed 32-bit integer data.
        psF32 F32;                     ///< Single-precision float data.
        psF64 F64;                     ///< Double-precision float data.
        psList *list;                  ///< List data.
        psMetadata *md;                ///< Metadata data.
        psPtr V;                       ///< Pointer to other type of data.
    } data;                            ///< Union for data types.
    char *comment;                     ///< Optional comment ("", not NULL).
}
psMetadataItem;

/** Create a metadata item.
 *
 *  Returns a fill psMetadataItem ready for insertion into the psMetadata
 *  struct. The name argument specifies the name to use for this item, and
 *  may include sprintf formatting codes. The format entry specifies both
 *  the metadata type and optional flags and is created by bit-wise or of the
 *  appropriate type and flag. The comment argument is a fixed string used to
 *  comment the metadata item. The arguments to the name formatting codes and
 *  the metadata itself are passed as arguments following the comment string.
 *  The data must be a pointer for any of the elements stored in data.void.
 *  The argument list must be interpreted appropriately by the va_list
 *  operators in the function specified size and type.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
psMetadataItem* psMetadataItemAlloc(
    const char *name,                  ///< Name of metadata item.
    psMetadataType type,               ///< Type of metadata item.
    const char *comment,               ///< Comment for metadata item.
    ...                                ///< Arguments for name formatting and metadata item data.
);

/** Create a metadata item with specified string data.
 *
 *  Returns a fill psMetadataItem ready for insertion into the psMetadata
 *  struct.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
psMetadataItem* psMetadataItemAllocStr(
    const char* name,                  ///< Name of metadata item.
    const char* comment,               ///< Comment for metadata item.
    const char* value                  ///< the value of the metadata item.
);

/** Create a metadata item with specified psF32 data.
 *
 *  Returns a fill psMetadataItem ready for insertion into the psMetadata
 *  struct.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
psMetadataItem* psMetadataItemAllocF32(
    const char* name,                  ///< Name of metadata item.
    const char* comment,               ///< Comment for metadata item.
    psF32 value                        ///< the value of the metadata item.
);

/** Create a metadata item with specified psF64 data.
 *
 *  Returns a fill psMetadataItem ready for insertion into the psMetadata
 *  struct.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
psMetadataItem* psMetadataItemAllocF64(
    const char* name,                  ///< Name of metadata item.
    const char* comment,               ///< Comment for metadata item.
    psF64 value                        ///< the value of the metadata item.
);

/** Create a metadata item with specified psS32 data.
 *
 *  Returns a fill psMetadataItem ready for insertion into the psMetadata
 *  struct.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
psMetadataItem* psMetadataItemAllocS32(
    const char* name,                  ///< Name of metadata item.
    const char* comment,               ///< Comment for metadata item.
    psS32 value                        ///< the value of the metadata item.
);

/** Create a metadata item with specified psBool data.
 *
 *  Returns a fill psMetadataItem ready for insertion into the psMetadata
 *  struct.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
psMetadataItem* psMetadataItemAllocBool(
    const char* name,                  ///< Name of metadata item.
    const char* comment,               ///< Comment for metadata item.
    psBool value                       ///< the value of the metadata item.
);

#ifndef SWIG
/** Create a metadata item with va_list.
 *
 *  Returns a fill psMetadataItem ready for insertion into the psMetadata
 *  struct. The name argument specifies the name to use for this item, and
 *  may include sprintf formatting codes. The format entry specifies both
 *  the metadata type and optional flags and is created by bit-wise or of the
 *  appropriate type and flag. The comment argument is a fixed string used to
 *  comment the metadata item. The arguments to the name formatting codes and
 *  the metadata itself are passed as arguments following the comment string.
 *  The data must be a pointer for any of the elements stored in data.void.
 *  The argument list must be interpreted appropriately by the va_list
 *  operators in the function specified size and type.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
psMetadataItem* psMetadataItemAllocV(
    const char *name,                  ///< Name of metadata item.
    psMetadataType type,               ///< Type of metadata item.
    const char *comment,               ///< Comment for metadata item.
    va_list list                       ///< Arguments for name formatting and metadata item data.
);
#endif

/** Create a metadata collection.
 *
 *  Returns an empty metadata container with fully allocated internal metadata
 *  containers.
 *
 *  @return psMetadata* : Pointer metadata.
 */
psMetadata* psMetadataAlloc(void);

/** Add existing metadata item to metadata collection.
 *
 *  Add a metadata item that has already been created to the metadata
 *  collection.
 *
 *  @return bool: True for success, false for failure.
 */
psBool psMetadataAddItem(
    psMetadata*  md,                   ///< Metadata collection to insert metadat item.
    psMetadataItem*  item,             ///< Metadata item to be added.
    psS32 location,                    ///< Location to be added.
    psS32 flags                        ///< Options flag mask, see psMetadataFlags enum
);

/** Create and add a metadata item to metadata collection.
 *
 * Creates a new metadata item add to the metadata collection.
 *
 * @return bool: True for success, false for failure.
 */
psBool psMetadataAdd(
    psMetadata* md,                    ///< Metadata collection to insert metadata item.
    psS32 location,                    ///< Location to be added.
    const char *name,                  ///< Name of metadata item.
    int type,                          ///< Type of metadata item (psMetadataType) and options (psMetadataFlags)
    const char *comment,               ///< Comment for metadata item.
    ...                                ///< Arguments for name formatting and metadata item data.
);

#ifndef SWIG
/** Create and add a metadata item to metadata collection.
 *
 * Creates a new metadata item add to the metadata collection.
 *
 * @return bool: True for success, false for failure.
 */
psBool psMetadataAddV(
    psMetadata* md,                    ///< Metadata collection to insert metadat item.
    psS32 location,                    ///< Location to be added.
    const char *name,                  ///< Name of metadata item.
    int type,                          ///< Type of metadata item (psMetadataType) and options (psMetadataFlags)
    const char *comment,               ///< Comment for metadata item.
    va_list list                       ///< Arguments for name formatting and metadata item data.
);
#endif

psBool psMetadataAddS32(psMetadata* md, psS32 location, const char* name,
                        const char* comment, psS32 value);
psBool psMetadataAddF32(psMetadata* md, psS32 location, const char* name,
                        const char* comment, psF32 value);
psBool psMetadataAddF64(psMetadata* md, psS32 location, const char* name,
                        const char* comment, psF64 value);
psBool psMetadataAddList(psMetadata* md, psS32 location, const char* name,
                         const char* comment, psList* value);
psBool psMetadataAddStr(psMetadata* md, psS32 location, const char* name,
                        const char* comment, const char* value);
psBool psMetadataAddVector(psMetadata* md, psS32 location, const char* name,
                           const char* comment, psVector* value);
psBool psMetadataAddImage(psMetadata* md, psS32 location, const char* name,
                          const char* comment, psImage* value);
psBool psMetadataAddHash(psMetadata* md, psS32 location, const char* name,
                         const char* comment, psHash* value);
psBool psMetadataAddLookupTable(psMetadata* md, psS32 location, const char* name,
                                const char* comment, psLookupTable* value);
psBool psMetadataAddUnknown(psMetadata* md, psS32 location, const char* name,
                            const char* comment, psPtr value);


/** Remove an item from metadata collection.
 *
 *  Items may be removed from metadata by specifing a key or location. If the
 *  name is null, the where argument is used instead. If name is not null,
 *  where is set to PS_LIST_UNKNOWN. If the item is found, it is removed from
 *  the metadata and true is returned.  If the key is not unique, then all
 *  items corresponding to it are removed.
 *
 * @return bool: True for success, false for failure.
 */
psBool psMetadataRemove(
    psMetadata*  md,           ///< Metadata collection to remove metadata item.
    psS32 where,               ///< Location to be removed.
    const char * key           ///< Name of metadata key.
);

/** Find an item in the metadata collection based on key name.
 *
 *  Items may be found in the metadata by providing a key. If the key is
 *  non-unique, the first item is returned. If the item is not found, null is
 *  returned.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
psMetadataItem* psMetadataLookup(
    psMetadata * md,                   ///< Metadata collection to lookup metadata item.
    const char * key                   ///< Name of metadata key.
);

/** Find an item in the metadata collection based on key name and return its double precision value.
 *
 *  Items may be found in the metadata by providing a key. If the key is
 *  non-unique, the value of the first item is returned. If the item is not found, zero is
 *  returned.
 *
 * @return psF64 : Value of metadata item.
 */
psF64 psMetadataLookupF64(
    psBool *status,                    ///< Status of lookup.
    psMetadata *md,                    ///< Metadata collection to lookup metadata item.
    const char *key                    ///< Name of metadata key.
);

/** Find an item in the metadata collection based on key name and return its single precision value.
 *
 *  Items may be found in the metadata by providing a key. If the key is
 *  non-unique, the value of the first item is returned. If the item is not found, zero is
 *  returned.
 *
 * @return psF32 : Value of metadata item.
 */
psF32 psMetadataLookupF32(
    psBool *status,                    ///< Status of lookup.
    psMetadata *md,                    ///< Metadata collection to lookup metadata item.
    const char *key                    ///< Name of metadata key.
);

/** Find an item in the metadata collection based on key name and return its integer value.
 *
 *  Items may be found in the metadata by providing a key. If the key is
 *  non-unique, the value of the first item is returned. If the item is not found, zero is
 *  returned.
 *
 * @return psS32 : Value of metadata item.
 */
psS32 psMetadataLookupS32(
    psBool *status,                    ///< Status of lookup.
    psMetadata *md,                    ///< Metadata collection to lookup metadata item.
    const char *key                    ///< Name of metadata key.
);

/** Find an item in the metadata collection based on key name and return its boolean value.
 *
 *  Items may be found in the metadata by providing a key. If the key is
 *  non-unique, the value of the first item is returned. If the item is not found, zero is
 *  returned.
 *
 * @return psBool : Value of metadata item.
 */
psBool psMetadataLookupBool(
    psBool *status,                    ///< Status of lookup.
    psMetadata *md,                    ///< Metadata collection to lookup metadata item.
    const char *key                    ///< Name of metadata key.
);

/** Find an item in the metadata collection based on key name and return its integer value.
 *
 *  Items may be found in the metadata by providing a key. If the key is
 *  non-unique, the value of the first item is returned. If the item is not found, zero is
 *  returned.
 *
 * @return void* : Value of metadata item.
 */
psPtr psMetadataLookupPtr(
    psBool *status,                    ///< Status of lookup.
    psMetadata* md,                    ///< Metadata collection to lookup metadata item.
    const char *key                    ///< Name of metadata key.
);

/** Find an item in the metadata collection based on list index.
 *
 *  Items may be found in the metadata by their entry position in the list
 *  container.
 *
 *  @return psMetadataItem* : Pointer metadata item.
 */
psMetadataItem* psMetadataGet(
    psMetadata*  md,                   ///< Metadata collection to insert metadat item.
    psS32 location                     ///< Location to be retrieved.
);

/** Creates a psMetadataIterator to iterate over the specified psMetadata.
 *
 *  Supports the subsetting of the metadata via keyword using regular
 *  expression.  If no regular expression is specified, iteration
 *  over the entire psMetadata is performed.
 *
 *  @return psMetadataIterator*        a new psMetadataIterator, of NULL if error occurred
 */
psMetadataIterator* psMetadataIteratorAlloc(
    psMetadata* md,                    ///< the psMetadata to iterate with
    int location,                      ///< the initial starting point (after subsetting).
    const char* regex
    ///< A regular expression for subsetting the psMetadata.  If NULL, no
    ///< subsetting is performed.
);

/** Set the iterator of the psMetadat to a given position.  If location is
 *  invalid the iterator position is not changed.
 *
 *  @return psBool        TRUE if iterator successfully set, otherwise FALSE.
*/
psBool psMetadataIteratorSet(
    psMetadataIterator* iterator,      ///< psMetadata iterator
    int location                       ///< index number, PS_LIST_HEAD, or PS_LIST_TAIL
);

/** Position the specified iterator to the next matching item in psMetadata,
 *  given the regular expression of the iterator
 *
 *  @return psPtr       the psMetadataItem at the original iterator position
 *                      or NULL if the iterator went past the end of the list.
 */
psMetadataItem* psMetadataGetAndIncrement(
    psMetadataIterator* iterator           ///< iterator to move
);

/** Position the specified iterator to the previous matching item in psMetadata,
 *  given the regular expression of the iterator
 *
 *  @return psPtr       the psMetadataItem at the original iterator position
 *                      or NULL if the iterator went past the beginning of the
 *                      list.
 */
psMetadataItem* psMetadataGetAndDecrement(
    psMetadataIterator* iterator           ///< iterator to move
);

/// @}

#endif

---