StreamDesc Struct Reference

#include <das2/stream.h>

Inheritance diagram for StreamDesc:

---

Detailed Description

Describes the stream itself, in particular the compression used, current packetDescriptors, etc.

Public Member Functions
StreamDesc *	new_StreamDesc (void)
	Creates a new blank StreamDesc.
StreamDesc *	StreamDesc_copy (const StreamDesc *pThis)
	Creates a deep-copy of an existing StreamDesc object.
ErrorCode	StreamDesc_addPktDesc (StreamDesc *pThis, PktDesc *pPd, int nPktId)
	Attach a standalone packet descriptor to this stream.
void	StreamDesc_setMonotonic (StreamDesc *pThis, bool isMonotonic)
	Indicates if the xtags on the stream are monotonic, in which case there might be optimal ways of processing the stream.
void	StreamDesc_addStdProps (StreamDesc *pThis)
	Adds metadata into the property set of the StreamDesc.
void	StreamDesc_addCmdLineProp (StreamDesc *pThis, int argc, char *argv[])
	Adds the command line into the property set of the StreamDesc.
PktDesc *	StreamDesc_createPktDesc (StreamDesc *pThis, DasEncoding *pXEncoder, UnitType xUnits)
	Creates a descriptor structure that for a stream packet type.
PktDesc *	StreamDesc_clonePktDesc (StreamDesc *pThis, const PktDesc *pd)
	Make a deep copy of a PacketDescriptor on a new stream.
PktDesc *	StreamDesc_clonePktDescById (StreamDesc *pThis, const StreamDesc *pOther, int nPktId)
	Deepcopy a PacketDescriptor from one stream to another.
PktDesc *	StreamDesc_getPktDesc (const StreamDesc *pThis, int id)
	Get the packet descriptor associated with an ID.
ErrorCode	StreamDesc_freePktDesc (StreamDesc *pThis, int nPktId)
	Free any resources associated with this PacketDescriptor, and release it's id number for use with a new PacketDescriptor.
int	StreamDesc_getOffset (StreamDesc *pThis)
	An I/O function that makes sense to use for either operation.
ErrorCode	StreamDesc_encode (StreamDesc *pThis, DasBuf *pBuf)
	Encode a StreamDesc to an XML string.
Data Fields
Descriptor	base
	The base structure.
PktDesc *	pktDesc [100]
	An array of packet descriptors.
void *	pUser
	User data pointer.
Descriptor Functions
These work for any type of Descriptor, including PlaneDesc , PktDesc and StreamDesc. To make your compiler happy you will need to cast Plane, Packet and Stream Descriptor pointers to just the generic type of Descriptor pointer when using these functions. For example: PktDesc* pPktDesc; hasProperty((Descriptor*)pPktDesc, "SomePropName");
bool	Desc_hasProp (const Descriptor *pThis, const char *propertyName)
	Determine if a property is present in a Descriptor or it's ancestors.
const char *	Desc_getPropStr (const Descriptor *pThis, const char *propertyName)
	read the property of type String named propertyName.
ErrorCode	Desc_setPropStr (Descriptor *pThis, const char *sName, const char *sVal)
	SetProperty methods add properties to any Descriptor (stream,packet,plane).
double	Desc_getPropDouble (const Descriptor *pThis, const char *propertyName)
	Read the property of type double named propertyName.
ErrorCode	Desc_setPropDouble (Descriptor *pThis, const char *propertyName, double value)
	Set property of type double.
double	Desc_getPropDatum (Descriptor *pThis, const char *sPropName, UnitType units)
	Get the a numeric property in the specified units.
ErrorCode	Desc_setPropDatum (Descriptor *pThis, const char *sName, double rVal, UnitType units)
	Set property of type Datum (double, UnitType pair).
double *	Desc_getPropDoubleArray (Descriptor *pThis, const char *propertyName, int *nitems)
	Get the values of an array property.
ErrorCode	Desc_setPropDoubleArray (Descriptor *pThis, const char *propertyName, int nitems, double *value)
	Set the property of type double array.
int	Desc_getPropInt (const Descriptor *pThis, const char *propertyName)
	Get a property integer value.
ErrorCode	Desc_setPropInt (Descriptor *pThis, const char *sName, int nVal)
	Set the property of type int.
ErrorCode	Desc_setPropDatumRange (Descriptor *pThis, const char *sName, double beg, double end, UnitType units)
	Set property of type DatumRange (double, double, UnitType triple).
ErrorCode	Desc_setPropFloatArray (Descriptor *pThis, const char *propertyName, int nitems, float *value)
	Set the property of type float array.
void	Desc_copyProperties (Descriptor *pThis, const Descriptor *source)
	Deepcopy properties into a descriptor.

---

Member Function Documentation

StreamDesc * new_StreamDesc

(

void

)

Creates a new blank StreamDesc.

The returned structure has no packet descriptors, no properties are defined. The compression attribute is set to 'none' and the version is set to 2.2

StreamDesc * StreamDesc_copy

(

const StreamDesc *

pThis

)

Creates a deep-copy of an existing StreamDesc object.

An existing stream descriptor, probably one initialized automatically by reading standard input, can be used as a template for generating a second stream descriptor. This is a deep copy, all owned objects are copied as well and may be changed with out affecting the source object or it components.

Parameters:

pThis

The stream descriptor to copy

Returns:

A new stream descriptor allocated on the heap with all associated packet descriptors attached and also allocated on the heap

ErrorCode StreamDesc_addPktDesc	(	StreamDesc *	pThis,
		PktDesc *	pPd,
		int	nPktId
	)

Attach a standalone packet descriptor to this stream.

Parameters:

	pThis	The stream to receive the packet descriptor. The PkdDesc object will have it's parent pointer set to this object.
	pPd	The stand alone packet descriptor, it's parent pointer must be null
	nPktId	The ID for the new packet descriptor.

Returns:

0 on success or a positive error code on failure.

void StreamDesc_addStdProps

(

StreamDesc *

pThis

)

Adds metadata into the property set of the StreamDesc.

These include the creation time, the source Id, the process id, the command line, and hostname.

void StreamDesc_addCmdLineProp	(	StreamDesc *	pThis,
		int	argc,
		char *	argv[]
	)

Adds the command line into the property set of the StreamDesc.

This can be useful when debugging.

PktDesc * StreamDesc_createPktDesc	(	StreamDesc *	pThis,
		DasEncoding *	pXEncoder,
		UnitType	xUnits
	)

Creates a descriptor structure that for a stream packet type.

Initially this descriptor will only have xtags, but additional data planes are added. The packet ID for the new descriptor is automatically assigned so to be the lowest legal ID not currently in use.

Parameters:

	pThis	The stream descriptor object that will receive the new packet type.
	xUnits	is a UnitType (currently char *) that describes the data. Generally this is used to identify times (e.g.UNIT_MJ1958,UNIT_US2000) or is UNIT_DIMENSIONLESS, but other UnitTypes are defined (e.g. UNIT_HERTZ, UNIT_DB).
	The	encoder for X-plane values on this stream. The StreamDesc object takes ownership of the encoder's memory.

Returns:

A pointer to new PacketDescriptor object allocated on the heap. This pointer is also stored in the StreamDesc::packetDescriptors member variable of pThis.

PktDesc * StreamDesc_clonePktDesc	(	StreamDesc *	pThis,
		const PktDesc *	pd
	)

Make a deep copy of a PacketDescriptor on a new stream.

This function makes a deep copy of the given packet descriptor and places it on the provided stream. Note, packet ID's are not preserved in this copy. The newly allocated PacketDescriptor may not have the same packet ID as the old one.

Parameters:

	pThis	the stream to get the new packet descriptor
	pd	The packet descriptor to clone onto the stream

Returns:

The newly created packet descriptor

PktDesc * StreamDesc_clonePktDescById	(	StreamDesc *	pThis,
		const StreamDesc *	pOther,
		int	nPktId
	)

Deepcopy a PacketDescriptor from one stream to another.

The copy made by this function handles recursing down to all the planes and properties owned by the given packet descriptor. Unlike the the function clonePacketDescriptor() the packet ID is preserved across the copy.

Parameters:

	pThis	the stream descriptor to get the new packet descriptor
	pOther	the stream descriptor who's packet descriptor is copied
	nPktId	the id of the packet to copy, a value in the range of 0 to 99 inclusive.

Returns:

The newly created packet descriptor, or NULL if there was no packet descriptor with that ID in the source.

PktDesc * StreamDesc_getPktDesc	(	const StreamDesc *	pThis,
		int	id
	)

Get the packet descriptor associated with an ID.

The stream object which contains the packet descriptors. The numeric packet ID, a value from 1 to 99 inclusive.

Returns:

NULL if there is no packet descriptor associated with the given Packet ID

ErrorCode StreamDesc_encode	(	StreamDesc *	pThis,
		DasBuf *	pBuf
	)

Encode a StreamDesc to an XML string.

Parameters:

	pThis	The stream descriptor to encode
	pBuf	A DasBuffer item to receive the bytes

Returns:

0 if encoding succeeded, a non-zero error code otherwise

bool Desc_hasProp	(	const Descriptor *	pThis,
		const char *	propertyName
	)			[inherited]

Determine if a property is present in a Descriptor or it's ancestors.

Parameters:

	pThis	the descriptor object to query
	propertyName	the name of the property to retrieve.

Returns:

true if the descriptor or one of it's ancestors has a property with the given name, false otherwise.

ErrorCode Desc_setPropStr	(	Descriptor *	pThis,
		const char *	sName,
		const char *	sVal
	)			[inherited]

SetProperty methods add properties to any Descriptor (stream,packet,plane).

The typed methods (e.g. setPropertyDatum) property tag the property with a type so that it will be parsed into the given type.

double Desc_getPropDouble	(	const Descriptor *	pThis,
		const char *	propertyName
	)			[inherited]

Read the property of type double named propertyName.

The property value is parsed using sscanf.

double Desc_getPropDatum	(	Descriptor *	pThis,
		const char *	sPropName,
		UnitType	units
	)			[inherited]

Get the a numeric property in the specified units.

Descriptor properties my be provided as Datums. Datums are a double value along with a specified measurement unit.

Parameters:

	pThis	The Descriptor containing the property in question.
	sPropName	The name of the property to retrieve.
	units	The units of measure in which the return value will be represented. If the property value is stored in a different set of units than those indicated by this parameter than the output will be converted to the given unit type.

Returns:

The converted value or FILL_VALUE if conversion to the desired units is not possible.

ErrorCode Desc_setPropDatum	(	Descriptor *	pThis,
		const char *	sName,
		double	rVal,
		UnitType	units
	)			[inherited]

Set property of type Datum (double, UnitType pair).

If a property with this name already exists it is 1st deleted and then the new property is added in its place.

Parameters:

	pThis	The descriptor to receive the property
	sName	The name of the property to set
	rVal	The numeric value of the property
	units	The units of measure for the property

double * Desc_getPropDoubleArray	(	Descriptor *	pThis,
		const char *	propertyName,
		int *	nitems
	)			[inherited]

Get the values of an array property.

Space for the array is allocated by getDoubleArrayFromString. and nitems is set to indicate the size of the array.

Parameters:

[in]	pThis	the descriptor object to query
[in]	propertyName	the name of the proprety to retrieve
[out]	nitems	a pointer to a an integer containing the number of values in the returned array.

Returns:

A pointer to a double array allocated on the heap. It is the caller's responsibility to depose of the memory when it is no longer needed. If the named property doesn't exist the program exits.

See also:

hasProperty()

int Desc_getPropInt	(	const Descriptor *	pThis,
		const char *	propertyName
	)			[inherited]

Get a property integer value.

Parameters:

	pThis	the descriptor object to query
	propertyName	the name of the proprety to retrieve

Returns:

The value of the named property or exits the program if the named proprety doesn't exist in this descriptor.

See also:

hasProperty()

ErrorCode Desc_setPropFloatArray	(	Descriptor *	pThis,
		const char *	propertyName,
		int	nitems,
		float *	value
	)			[inherited]

Set the property of type float array.

Note the array is cast to a double array before encoding.

void Desc_copyProperties	(	Descriptor *	pThis,
		const Descriptor *	source
	)			[inherited]

Deepcopy properties into a descriptor.

Parameters:

	pThis	the descriptor to receive a copy of the properties
	source	the descriptor with the properties to be copied.

---

Field Documentation

PktDesc* StreamDesc::pktDesc[100]

An array of packet descriptors.

The lookup ID is the same value used as the PacketID in the stream. Legal packet ID's are 1 to 99. 0 is reserved for the stream header packet and thus item 0 in this array should always be NULL.

Note that Das2 Streams can re-use packet ID's. So the PacketDescriptor at, for example, ID 2 may be completely different from one invocation of a stream handler callback to another.

void* StreamDesc::pUser

User data pointer.

The stream->packet->plane hierarchy provides a good organizational structure for application data, especially for applications whose purpose is to filter streams. This pointer can be used to hold a reference to information that is not serialized. It is initialized to NULL when a PacketDescriptor is created otherwise the library doesn't deal with it in any other way.

---

The documentation for this struct was generated from the following file:

• das2/stream.h