H5PT: HDF5 Packet Table
C++ Wrappers

• PacketTable - functions shared by all packet tables
• FL_PacketTable - a packet table storing fixed-length packets
• VL_PacketTable - a packet table storing variable-length packets

Name: Null Constructor

Signature:

PacketTable( )

Purpose:

Creates an invalid packet table object.

Description:

The object created with this call will return false if IsValid() is called on it. To create a valid packet table, use the FL_Packet_Table or VL_Packet_Table constructors. This function does not make any change to the underlying HDF5 file.

Name: "Open" Constructor

Signature:

PacketTable(hid_t fileID, char* name)

Purpose:

Opens an existing packet table.

Description:

Opens an existing packet table, which can contain either fixed-length or variable-length packets.

Parameters:

hid_t fileID

IN: file or group in which the packet table is located

char* name

IN: the packet table's name

Name: Destructor

Signature:

~PacketTable()

Description:

The destructor closes the packet table in the file, so a packet table created or opened with the C++ wrapper does not need to be closed manually.

Name: IsValid

Signature:

bool IsValid()

Purpose:

Determines if this is an valid packet table.

Description:

This function is used to ensure that a PacketTable object corresponds to an open packet table in the file. It should be called after the constructor to check that there were no errors creating or opening the packet table.

Returns:

Returns true if this is an open packet table, false otherwise.

Name: IsVariableLength

Signature:

int IsVariableLength()

Purpose:

Determines if this is a variable-length packet table.

Description:

The PacketTable class has no functions to read from or write to the file. However, this function can be used to determine whether an unknown packet table should be opened using the FL_PacketTable or VL_PacketTable class.

Returns:

Returns 1 if this is a variable-length packet table, 0 if it is fixed-length. If the table is invalid (not open), returns a negative value.

Name: ResetIndex

Signature:

void ResetIndex()

Purpose:

Resets the packet table's index to point to the first packet.

Description:

A packet table keeps track of the user's current location in the table so that the user can iterate through packets. This function should be called before using GetNextPacket.

Name: SetIndex

Signature:

int SetIndex(unsigned int index);

Purpose:

Sets a packet table's current index.

Description:

This function allows the user to begin iterating through packets starting from any arbitrary index. Packet tables are zero-indexed, so packet 0 is the first packet.

Parameters:

unsigned int index

IN: The value to which the packet table's index should be set

Returns:

Returns non-negative on success, negative on error.

Name: GetPacketCount

Signatures:

unsigned int GetPacketCount()

unsigned int GetPacketCount(int& error)

Purpose:

Retrieves the number of packets in the packet table.

Description:

This function is overloaded so that it can be called with or without returning an error value. If error is not supplied, any error value is ignored. Using this parameter allows the user to distinguish between an open packet table with 0 packets and an invalid packet table.

Parameters:

int& error (optional)

OUT: Non-negative if packet count was successfully retrieved, negative if packet table is invalid.

Returns:

Number of packets in packet table. Returns 0 if packet table contains zero packets or on error.

Name: "Create" Constructor

Signature:

FL_PacketTable(hid_t fileID, char* name, hid_t dtypeID, int chunkSize)

Purpose:

Creates a new packet table for storing fixed-length packets.

Description:

This constructor creates and opens a packet table in the file specified by fileID named name. Packets will be of the datatype specified by dtypeID.

Parameters:

hid_t fileID

IN: Identifier of the file or group to create the table within.

const char * dset_name

IN: The name of the packet table to create.

hid_t dtype_id

IN: The datatype of a packet.

hsize_t chunkSize

IN: The packet table uses HDF5 chunked storage to allow it to grow. This value allows the user to set the size of a chunk. The chunk size affects performance.

Name: "Open" Constructor

Signature:

FL_PacketTable(hid_t fileID, char* name)

Purpose:

Opens a fixed-length packet table.

Description:

This constructor opens an existing packet table named name in the location fileID. This packet table must be fixed-length.

Parameters:

hid_t fileID

IN: Identifier of the file or group containing the packet table.

const char * dset_name

IN: The name of the packet table to open.

Name: AppendPacket / AppendPackets

Signature:

int AppendPacket(void * data)

int AppendPackets(unsigned int numPackets, void *data)

Purpose:

Appends fixed-length packets to the packet table.

Description:

This function writes packets to the end of the packet table. If only one argument is given, it is assumed that only a single packet is being written.

Parameters:

unsigned int numPackets (optional)

IN: Number of packets to add. Default is one.

void * data:

IN: Data to write. Must be a buffer of packets of the packet table's datatype.

Returns:

Returns non-negative value on success, negative on error.

Name: GetPacket / GetPackets

Signatures:

int GetPacket(unsigned int index, void * data)

int GetPackets(unsigned int startIndex, unsigned int endIndex, void * data)

Purpose:

Reads packets from the packet table.

Description:

This function fills a buffer, data, with fixed-length packets from the packet table. The one-argument function can be called to retrieve a single packet at the given index, or the two-argument function used to read a range of packets (zero-indexed, inclusive).

Parameters:

unsigned int index (single packet)

IN: Index of the single packet to be read

unsigned int startIndex (multiple packets)

IN: Index at which to start reading packets

unsigned int endIndex (multiple packets)

IN: Index at which to stop reading packets

void * data

OUT: Buffer for packets being retrieved

Returns:

Returns non-negative on success, negative on error.

Name: GetNextPacket / Get Next Packets

Signatures:

int GetNextPacket(void * data)

int GetNextPackets(unsigned int numPackets, void * data)

Purpose:

Iterates through packets from the packet table.

Description:

This function reads packets starting from the current index in the packet table and updates the index. It can be used with the ResetIndex and SetIndex functions to iterate through the packet table. There are versions of this function that can be called with or without the numPackets argument; if this argument is not supplied, it defaults to one.

Parameters:

unsigned int numPackets (optional)

IN: How many packets to read. Defaults to one.

void * data

OUT: Buffer to hold packets being read.

Returns:

Returns non-negative on success, negative on error.

Name: "Create" Constructor

Signature:

VL_PacketTable(hid_t fileID, char* name, int chunkSize)

Purpose:

Creates a new packet table for storing variable-length packets.

Description:

This constructor creates and opens a packet table in the file specified by fileID named name.

Parameters:

hid_t fileID

IN: Identifier of the file or group to create the table within.

const char * dset_name

IN: The name of the packet table to create.

hsize_t chunkSize

IN: The packet table uses HDF5 chunked storage to allow it to grow. This value allows the user to set the size of a chunk. The chunk size affects performance.

Name: "Open" Constructor

Signature:

VL_PacketTable(hid_t fileID, char* name)

Purpose:

Opens a variable-length packet table.

Description:

This constructor opens an existing packet table named name in the location fileID. This packet table must be variable-length.

Parameters:

hid_t fileID

IN: Identifier of the file or group containing the packet table.

const char * dset_name

IN: The name of the packet table to open.

Name: AppendPacket (single packet)

Signature:

int AppendPacket(void * data, unsigned int length)

Purpose:

Appends a single variable-length packet to the packet table.

Description:

This function writes a packet to the end of the packet table. The length of the packet must be specified, since it is not known beforehand.

Parameters:

void * data:

IN: Buffer holding a single packet to be written.

unsigned int length

IN: Length of the packet being added in bytes.

Returns:

Returns non-negative value on success, negative on error.

Name: AppendPackets(multiple packets)

Signature:

int AppendPackets(unsigned int numPackets, hvl_t *data)

Purpose:

Appends multiple variable-length packets to the packet table.

Description:

This function writes packets to the end of the packet table. The packets must be packaged as an array of hvl_t structs, which contain a pointer to the packet and its length.

Parameters:

unsigned int numPackets

IN: Number of packets to append.

hvl_t* data:

IN: An array of hvl_t structs containing pointers to the packets to be written.

Returns:

Returns non-negative value on success, negative on error.

Name: GetPacket

Signatures:

int GetPacket(unsigned int index, hvl_t * data)

int GetPackets(unsigned int startIndex, unsigned int endIndex, hvl_t * data)

Purpose:

Reads variable-length packets from the packet table.

Description:

This function fills a buffer of hvl_t structs with variable-length packets from the packet table. A function can be called with one argument to retrieve a single packet at the given index, or the two-argument function can be used to read a range of packets (zero-indexed, inclusive).

Parameters:

unsigned int index (single packet)

IN: Index of the single packet to be read

unsigned int startIndex (multiple packets)

IN: Index at which to start reading packets

unsigned int endIndex (multiple packets)

IN: Index at which to stop reading packets

hvl_t * data

OUT: Buffer of hvl_t structs for packets being retrieved

Returns:

Returns non-negative on success, negative on error.

Name: GetNextPacket

Signatures:

int GetNextPacket(hvl_t * data)

int GetNextPacket(unsigned int numPackets, hvl_t * data)

Purpose:

Iterates through packets from the packet table.

Description:

This function reads packets starting from the current index in the packet table and updates the index. It can be used with the ResetIndex and SetIndex functions to iterate through the packet table. Different versions of this function can be called with or without the numPackets argument; if this argument is not supplied, it defaults to one.

Parameters:

unsigned int numPackets (optional)

IN: How many packets to read. Defaults to one.

hvl_t * data

OUT: Buffer of hvl_t structs to hold packets being read.

Returns:

Returns non-negative on success, negative on error.

Name: FreeReadbuff

Signature:

int FreeReadbuff(unsigned int numStructs, hvl_t * buffer)

Purpose:

Frees buffers used to hold variable-length packets

Description:

When variable-length packets are read, memory must be allocated to hold them; hvl_t structs hold pointers to this memory. This memory should be freed by passing the array of hvl_t structs used in reading to this function, along with the size of the array.

Parameters:

unsigned int numStructs

IN: Number of hvl_t structs in the array.

hvl_t * buffer

IN: Buffer used to read packets whose memory should now be freed.

Returns:

Returns non-negative on success, negative on error.