/** @file  psMetadataIO.h
*
*  @brief Contains metadata input/output functions.
*
*  This file defines functions to read and write metadata to/from an external file.
*
*  @ingroup Metadata
*
*  @author Ross Harman, MHPCC
*
*  @version $Revision: 1.7 $ $Name: not supported by cvs2svn $
*  @date $Date: 2004-12-06 20:00:03 $
*
*  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
*/
#ifndef PS_METADATAIO_H
#define PS_METADATAIO_H


/// @addtogroup Metadata
/// @{


/** Print metadata item to file.
 *
 *  Metadata items may be printed to an open file descriptor based on a
 *  provided format. The format is a sprintf format statement with exactly
 *  one % formatting command. If the metadata item type is a numeric type,
 *  this formatting command must also be numeric, and the type conversion
 *  performed to the value to match the format type. If the metadata type is
 *  a string, the fromatting command must also be for a string. If the
 *  metadata type is any other data type, printing is not allowed.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
bool psMetadataItemPrint(
    FILE * fd,                         ///< Pointer to file to write metadata item.
    const char *format,                ///< Format to print metadata item.
    const psMetadataItem* metadataItem ///< Metadata item to print.
);

/** Read metadata header.
 *
 *  Read a metadata header from file. If the file is not found, an error is
 *  reported.
 *
 *  @return psMetadata* : Pointer to resulting metadata.
 */
psMetadata* psMetadataReadHeader(
    psMetadata* output,                ///< Resulting metadata from read.
    char *extName,                     ///< File name extension string.
    psS32 extNum,                      ///< File name extension number. Starts at 1.
    char *fileName                     ///< Name of file to read.
);

/** Read metadata configuration file.
 *
 *  Loads pre-defined settings by parsing a configuration file into a psMetadata structure.
 *
 *  @return psMetadata* : Resulting metadata from read.
 */
psMetadata* psMetadataParseConfig(
    psMetadata* md,                    ///< Resulting metadata from read.
    psU32 *nFail,                      ///< Number of failed lines.
    const char *fileName,              ///< Name of file to read.
    psBool overwrite                   ///< Allow overwrite of duplicate specifications.
);

/** Read XML metadata configuration file.
 *
 *  Loads pre-defined XML settings by parsing a configuration file into a psMetadata structure.
 *
 *  @return psMetadata* : Resulting metadata from read.
 */

psMetadata*  psMetadataParseConfigXml(
    psMetadata* md,                    ///< Resulting metadata from read.
    psU32 *nFail,                      ///< Number of failed lines.
    const char *fileName,              ///< Name of file to read.
    psBool overwrite                   ///< Allow overwrite of duplicate specifications.
);

/// @}

#endif
