H5PacketTable.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /* Packet Table wrapper classes
00017  *
00018  * Wraps the H5PT Packet Table C functions in C++ objects
00019  *
00020  * Nat Furrer and James Laird
00021  * February 2004
00022  */
00023 
00024 #ifndef H5PTWRAP_H
00025 #define H5PTWRAP_H
00026 
00027 /* Public HDF5 header */
00028 #include "hdf5.h"
00029 
00030 #include "H5PTpublic.h"
00031 #include "H5api_adpt.h"
00032 
00033 class H5_HLCPPDLL  PacketTable
00034 {
00035 public:
00036     /* Null constructor
00037      * Sets table_id to "invalid"
00038      */
00039     PacketTable() {table_id = H5I_BADID;}
00040 
00041     /* "Open" Constructor
00042      * Opens an existing packet table, which can contain either fixed-length or
00043      * variable-length packets.
00044      */
00045     PacketTable(hid_t fileID, char* name);
00046 
00047     /* Destructor
00048      * Cleans up the packet table
00049      */
00050     ~PacketTable();
00051 
00052     /* IsValid
00053      * Returns true if this packet table is valid, false otherwise.
00054      * Use this after the constructor to ensure HDF did not have
00055      * any trouble making or opening the packet table.
00056      */
00057     bool IsValid();
00058 
00059 #ifdef VLPT_REMOVED
00060     /* IsVariableLength
00061      * Return 1 if this packet table is a Variable Length packet table,
00062      * return 0 if it is Fixed Length.  Returns -1 if the table is
00063      * invalid (not open).
00064      */
00065     int IsVariableLength();
00066 #endif /* VLPT_REMOVED */
00067 
00068     /* ResetIndex
00069      * Sets the "current packet" index to point to the first packet in the
00070      * packet table
00071      */
00072     void ResetIndex();
00073 
00074     /* SetIndex
00075      * Sets the current packet to point to the packet specified by index.
00076      * Returns 0 on success, negative on failure (if index is out of bounds)
00077      */
00078     int SetIndex(hsize_t index);
00079 
00080     /* GetIndex
00081      * Returns the position of the current packet.
00082      * On failure, returns 0 and error is set to negative.
00083      */
00084     hsize_t GetIndex(int& error);
00085 
00086     /* GetPacketCount
00087      * Returns the number of packets in the packet table.  Error
00088      * is set to 0 on success.  On failure, returns 0 and
00089      * error is set to negative.
00090      */
00091     hsize_t GetPacketCount(int& error);
00092 
00093     hsize_t GetPacketCount()
00094     {
00095         int ignoreError;
00096         return GetPacketCount(ignoreError);
00097     }
00098 
00099 protected:
00100     hid_t table_id;
00101 };
00102 
00103 class H5_HLCPPDLL FL_PacketTable : virtual public PacketTable
00104 {
00105 public:
00106     /* Constructor
00107      * Creates a packet table in which to store fixed length packets.
00108      * Takes the ID of the file the packet table will be created in, the name of
00109      * the packet table, the ID of the datatype of the set, the size
00110      * of a memory chunk used in chunking, and the desired compression level
00111      * (0-9, or -1 for no compression).
00112      */
00113     FL_PacketTable(hid_t fileID, char* name, hid_t dtypeID, hsize_t chunkSize, int compression = -1);
00114 
00115     /* "Open" Constructor
00116      * Opens an existing fixed-length packet table.
00117      * Fails if the packet table specified is variable-length.
00118      */
00119     FL_PacketTable(hid_t fileID, char* name);
00120 
00121     /* AppendPacket
00122      * Adds a single packet to the packet table.  Takes a pointer
00123      * to the location of the data in memory.
00124      * Returns 0 on success, negative on failure
00125      */
00126     int AppendPacket(void * data);
00127 
00128     /* AppendPackets (multiple packets)
00129      * Adds multiple packets to the packet table.  Takes the number of packets
00130      * to be added and a pointer to their location in memory.
00131      * Returns 0 on success, -1 on failure.
00132      */
00133     int AppendPackets(size_t numPackets, void * data);
00134 
00135     /* GetPacket (indexed)
00136      * Gets a single packet from the packet table.  Takes the index
00137      * of the packet (with 0 being the first packet) and a pointer
00138      * to memory where the data should be stored.
00139      * Returns 0 on success, negative on failure
00140      */
00141     int GetPacket(hsize_t index, void * data);
00142 
00143     /* GetPackets (multiple packets)
00144      * Gets multiple packets at once, all packets between
00145      * startIndex and endIndex inclusive.  Also takes a pointer to
00146      * the memory where these packets should be stored.
00147      * Returns 0 on success, negative on failure.
00148      */
00149     int GetPackets(hsize_t startIndex, hsize_t endIndex, void * data);
00150 
00151     /* GetNextPacket (single packet)
00152      * Gets the next packet in the packet table.  Takes a pointer to
00153      * memory where the packet should be stored.
00154      * Returns 0 on success, negative on failure.  Index
00155      * is not advanced to the next packet on failure.
00156      */
00157     int GetNextPacket(void * data);
00158 
00159     /* GetNextPackets (multiple packets)
00160      * Gets the next numPackets packets in the packet table.  Takes a
00161      * pointer to memory where these packets should be stored.
00162      * Returns 0 on success, negative on failure.  Index
00163      * is not advanced on failure.
00164      */
00165     int GetNextPackets(size_t numPackets, void * data);
00166 };
00167 
00168 #ifdef VLPT_REMOVED
00169 class H5_HLCPPDLL  VL_PacketTable : virtual public PacketTable
00170 {
00171 public:
00172     /* Constructor
00173      * Creates a packet table in which to store variable length packets.
00174      * Takes the ID of the file the packet table will be created in, the name of
00175      * the packet table, and the size of a memory chunk used in chunking.
00176      */
00177     VL_PacketTable(hid_t fileID, char* name, hsize_t chunkSize);
00178 
00179     /* "Open" Constructor
00180      * Opens an existing variable-length packet table.
00181      * Fails if the packet table specified is fixed-length.
00182      */
00183     VL_PacketTable(hid_t fileID, char* name);
00184 
00185     /* AppendPacket
00186      * Adds a single packet of any length to the packet table.
00187      * Takes a pointer to the location of the data in memory and the length of the data
00188      * in bytes.
00189      * Returns 0 on success, negative on failure.
00190      */
00191     int AppendPacket(void * data, size_t length);
00192 
00193     /* AppendPackets (multiple packets)
00194      * Adds multiple variable-length packets to the packet table.  Takes the
00195      * number of packets to be added and a pointer to an array of
00196      * hvl_t structs in memory.
00197      * Returns 0 on success, negative on failure.
00198      */
00199     int AppendPackets(size_t numPackets, hvl_t * data);
00200 
00201     /* GetPacket (indexed)
00202      * Gets a single variable-length packet from the packet table.  Takes
00203      * the index of the packet (with 0 being the first packet) and a pointer
00204      * to a hvl_t struct in which to store the packet's size and location.
00205      * Returns 0 on success, negative on failure.
00206      */
00207     int GetPacket(hsize_t index, hvl_t * data);
00208 
00209     /* GetPackets (multiple packets)
00210      * Gets multiple variable-length packets at once, all packets between
00211      * startIndex and endIndex inclusive.  Takes a pointer to an array
00212      * of hvl_t structs in memory in which to store pointers to the packets.
00213      * Returns 0 on success, negative on failure.
00214      */
00215     int GetPackets(hsize_t startIndex, hsize_t endIndex, hvl_t * data);
00216 
00217     /* GetNextPacket (single packet)
00218      * Gets the next packet in the packet table.  Takes a pointer to
00219      * an hvl_t struct where the packet should be stored.
00220      * Returns 0 on success, negative on failure.  Index
00221      * is not advanced to the next packet on failure.
00222      */
00223     int GetNextPacket(hvl_t * data);
00224 
00225     /* GetNextPackets (multiple packets)
00226      * Gets the next numPackets packets in the packet table.  Takes a
00227      * pointer to an array of hvl_t structs where pointers to the packets
00228      * should be stored.
00229      * Returns 0 on success, negative on failure.  Index
00230      * is not advanced on failure.
00231      */
00232     int GetNextPackets(size_t numPackets, hvl_t * data);
00233 
00234     /* FreeReadbuff
00235      * Frees the buffers created when variable-length packets are read.
00236      * Takes the number of hvl_t structs to be freed and a pointer to their
00237      * location in memory.
00238      * Returns 0 on success, negative on error.
00239      */
00240     int FreeReadbuff(size_t numStructs, hvl_t * buffer);
00241 };
00242 #endif /* VLPT_REMOVED */
00243 
00244 #endif /* H5PTWRAP_H */