Changeset 1288 for trunk/psLib/src/collections/psMetadata.h

Timestamp:

Jul 23, 2004, 8:46:13 AM (22 years ago)

Author:

harman

Message:

Added more function prototypes

File:

• trunk/psLib/src/collections/psMetadata.h (modified) (3 diffs)

trunk/psLib/src/collections/psMetadata.h

@@ -10 +10 @@
  *  @author Ross Harman, MHPCC
  *
- *  @version $Revision: 1.1 $ $Name: not supported by cvs2svn $
- *  @date $Date: 2004-07-23 01:30:29 $
+ *  @version $Revision: 1.2 $ $Name: not supported by cvs2svn $
+ *  @date $Date: 2004-07-23 18:46:13 $
  *
  *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
@@ -71 +71 @@
         psPTR     V;                    ///< Pointer to other type of data.
     }
-    data;                             ///< Union for data types.
+    data;                               ///< Union for data types.
     char *comment;                      ///< Optional comment ("", not NULL).
     psList *restrict items;             ///< List of psMetadataItems with same name.
@@ -142 +142 @@
  */
 psMetadata *psMetadataAlloc(
-    void                                ///< Void
-);
-
+    void                                ///< 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.
+ */
+bool *psMetadataAddItem(
+    psMetadata *restrict md,            ///< Metadata collection to insert metadat item.
+    int where,                          ///< Location to be added.
+    psMetadataItem *restrict item       ///< Metadata item to be added.
+);
+
+/** 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.
+ */
+bool *psMetadataAdd(
+    psMetadata *restrict md,            ///< Metadata collection to insert metadat item.
+    int where,                          ///< Location to be added.
+    const char *name,                   ///< Name of metadata item.
+    int format,                         ///< Binary OR combination of metadata type and metadata flag.
+    const char *comment,                ///< Comment for metadata item.
+    ...                                 ///< Arguments for name formatting and metadata item data.
+);
+
+/** 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.
+ */
+bool *psMetadataRemove(
+    psMetadata *restrict md,            ///< Metadata collection to insert metadat item.
+    int where,                          ///< Location to be removed.
+    const char *restrict 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 *restrict md,            ///< Metadata collection to insert metadat item.
+    const char *restrict 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 *restrict md,            ///< Metadata collection to insert metadat item.
+    int where                           ///< Location to be retrieved.
+);
+
+/** Set or reset metadata iterator.
+ *
+ * Metadata may be iterated by setting or resetting an iterator to a location in the metadata list.
+ *
+ * @return void: void.
+ */
+bool psMetadataSetIterator(
+    psMetadata *restrict md,            ///< Metadata collection to iterate.
+    int where                           ///< Location of iterator.
+);
+
+/** Get next metadata item.
+ *
+ * Get next metadata item in iterator list.
+ *
+ * @return psMetadataItem*: Pointer metadata item.
+ */
+psMetadataItem *psMetadataGetNext(
+    psMetadata *restrict md,            ///< Metadata collection to iterate.
+    const char *restrict match,         ///< Beginning of key name.
+    int which                           ///< Iterator to be used.
+);
+
+/** Get previous metadata item.
+ *
+ * Get previous metadata item in iterator list.
+ *
+ * @return psMetadataItem*: Pointer metadata item.
+ */
+psMetadataItem *psMetadataGetPrevious(
+    psMetadata *restrict md,            ///< Metadata collection to iterate.
+    const char *restrict match,         ///< Beginning of key name.
+    int which                           ///< Iterator to be used.
+);
+
+/** 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 br for a string. If the
+ * metadata type is any other data type, printing is not allowed.
+ *
+ * @return psMetadataItem*: Pointer metadata item.
+ */
+void psMetadataItemPrint(
+    FILE *fd,                           ///< Pointer to file to write metadata item.
+    const char *format,                 ///< Format to print metadat item.
+    const psMetadataItem *restrict md   ///< 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 metadata.
+ */
+psMetadata *psMetadataReadHeader(
+    psMetadata *output,                 ///< Resulting metadata frim read.
+    const char *extname,                ///< File name extension string.
+    int extnum,                         ///< File name extension number.
+    const char *filename                ///< Name of file to read.
+);
+
+/** Read metadata header.
+ *
+ * Read a metadata header from file. If the file is not found, an error is reported.
+ *
+ * @return psMetadata*: Pointer metadata.
+ */
+psMetadata *psMetadataFReadHeader(
+    psMetadata *output,                 ///< Resulting metadata frim read.
+    const char *extname,                ///< File name extension string.
+    int extnum,                         ///< File name extension number.
+    FILE *fd                            ///< Pointer to file to read.
+);
 /// @}