#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. More...

StreamDesc *	StreamDesc_copy (const StreamDesc *pThis)
	Creates a deep-copy of an existing StreamDesc object. More...

DasErrCode	StreamDesc_addPktDesc (StreamDesc pThis, PktDesc pPd, int nPktId)
	Attach a standalone packet descriptor to this stream. More...

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. More...

void	StreamDesc_addCmdLineProp (StreamDesc pThis, int argc, char argv[])
	Adds the command line into the property set of the StreamDesc. More...

PktDesc *	StreamDesc_createPktDesc (StreamDesc pThis, DasEncoding pXEncoder, das_units xUnits)
	Creates a descriptor structure that for a stream packet type. More...

PktDesc *	StreamDesc_clonePktDesc (StreamDesc pThis, const PktDesc pd)
	Make a deep copy of a PacketDescriptor on a new stream. More...

PktDesc *	StreamDesc_clonePktDescById (StreamDesc pThis, const StreamDesc pOther, int nPktId)
	Deepcopy a PacketDescriptor from one stream to another. More...

PktDesc *	StreamDesc_getPktDesc (const StreamDesc *pThis, int id)
	Get the packet descriptor associated with an ID. More...

DasErrCode	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.

DasErrCode	StreamDesc_encode (StreamDesc pThis, DasBuf pBuf)
	Encode a StreamDesc to an XML string. More...

Data Fields
DasDesc	base
	The base structure.

PktDesc *	pktDesc [MAX_PKTIDS]
	An array of packet descriptors. More...

void *	pUser
	User data pointer. More...

Descriptor Functions
These work for any type of Descriptor, including PlaneDesc , PktDesc, StreamDesc, DasDs and DasVar. 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"); DasDesc
bool	DasDesc_equals (const DasDesc pOne, const DasDesc pTwo)
	Check to see if two descriptors contain the same properties Note, the order of the properties may be different between the descriptors but if the contents are the same then the descriptors are considered to be equal. More...

const DasDesc *	DasDesc_parent (DasDesc *pThis)
	The the parent of a Descriptor. More...

size_t	DasDesc_length (const DasDesc *pThis)
	Get the number of properties in a descriptor. More...

const char *	DasDesc_getNameByIdx (const DasDesc *pThis, size_t uIdx)
	Get a property name by an index. More...

const char *	DasDesc_getValByIdx (const DasDesc *pThis, size_t uIdx)
	Get a property value by an index. More...

const char *	DasDesc_getTypeByIdx (const DasDesc *pThis, size_t uIdx)
	Get a data type of a property by an index.

bool	DasDesc_has (const DasDesc pThis, const char propertyName)
	Determine if a property is present in a Descriptor or it's ancestors. More...

DasErrCode	DasDesc_set (DasDesc pThis, const char sType, const char sName, const char sVal)
	Generic property setter. More...

bool	DasDesc_remove (DasDesc pThis, const char propretyName)
	Remove a property from a descriptor, if preset. More...

const char *	DasDesc_getStr (const DasDesc pThis, const char propertyName)
	read the property of type String named propertyName.

DasErrCode	DasDesc_setStr (DasDesc pThis, const char sName, const char *sVal)
	SetProperty methods add properties to any Descriptor (stream,packet,plane). More...

DasErrCode	DasDesc_vSetStr (DasDesc pThis, const char sName, const char *sFmt,...)
	Set a string property in the manner of sprintf.

double	DasDesc_getDouble (const DasDesc pThis, const char propertyName)
	Read the property of type double named propertyName. More...

DasErrCode	DasDesc_setDouble (DasDesc pThis, const char propertyName, double value)
	Set property of type double.

double	DasDesc_getDatum (DasDesc pThis, const char sPropName, das_units units)
	Get the a numeric property in the specified units. More...

DasErrCode	DasDesc_setDatum (DasDesc pThis, const char sName, double rVal, das_units units)
	Set property of type Datum (double, UnitType pair) More...

double *	DasDesc_getDoubleAry (DasDesc pThis, const char propertyName, int *nitems)
	Get the values of an array property. More...

DasErrCode	DasDesc_setDoubleArray (DasDesc pThis, const char propertyName, int nitems, double *value)
	Set the property of type double array.

int	DasDesc_getInt (const DasDesc pThis, const char propertyName)
	Get a property integer value. More...

DasErrCode	DasDesc_setInt (DasDesc pThis, const char sName, int nVal)
	Set the property of type int.

bool	DasDesc_getBool (DasDesc pThis, const char sPropName)
	Get a property boolean value. More...

DasErrCode	DasDesc_setDatumRng (DasDesc pThis, const char sName, double beg, double end, das_units units)
	Set property of type DatumRange (double, double, UnitType triple)

DasErrCode	DasDesc_getStrRng (DasDesc pThis, const char sName, char sMin, char sMax, das_units *pUnits, size_t uLen)
	Get a property of type DatumRange with unconverted strings. More...

DasErrCode	DasDesc_setFloatAry (DasDesc pThis, const char propertyName, int nitems, float *value)
	Set the property of type float array. More...

void	DasDesc_copyIn (DasDesc pThis, const DasDesc source)
	Deepcopy properties into a descriptor. More...

DasErrCode	DasDesc_encode (DasDesc pThis, DasBuf pBuf, const char *sIndent)
	Encode a generic set of properties to a buffer. More...

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

DasErrCode 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,
		das_units	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).
pXEncoder	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.

Parameters

pThis	The stream object which contains the packet descriptors.
id	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

DasErrCode 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 DasDesc_equals	(	const DasDesc *	pOne,
		const DasDesc *	pTwo
	)

inherited

Check to see if two descriptors contain the same properties Note, the order of the properties may be different between the descriptors but if the contents are the same then the descriptors are considered to be equal.

Note that parent descriptor properties are not checked when handling the comparison.

Todo:: maybe check parents too.

Parameters

pOne	The first descriptor
pTwo	The second descriptor

const DasDesc * DasDesc_parent ( DasDesc * pThis )

inherited

The the parent of a Descriptor.

Plane descriptors are owned by packet descriptors and packet descriptors are owned by stream descriptors. This function lets you craw the ownership hierarchy

Parameters

pThis

Returns: The owner of a descriptor, or NULL if this is a top level descriptor, (i.e. a Stream Descriptor)

size_t DasDesc_length ( const DasDesc * pThis )

inherited

Get the number of properties in a descriptor.

Descriptor's have a hierarchy. In general when a property is requested, if a given Descriptor does not have a property the request is passed to the parent descriptor. This function only returns the number of properties in the given descriptor. It does not include properties owned by parents or ancestors.

This is useful when iterating over all properties in a descriptor.

See Also: DasDesc_getNameByIdx(); DasDesc_getValByIdx(); DasDesc_getTypeByIdx()

Parameters

pThis A pointer to the descriptor to query

Returns: The number of properties in this, and only this, descriptor.

const char * DasDesc_getNameByIdx	(	const DasDesc *	pThis,
		size_t	uIdx
	)

inherited

Get a property name by an index.

This is useful when iterating over all properties in a Descriptor. Only properties owed by a descriptor are queried in this manner. Parent descriptors are not consulted.

See Also: DasDesc_length()

Parameters

pThis	A pointer to the descriptor to query
uIdx	The index of the property, will be a value between 0 and the return value from Desc_getNProps()

Returns: A pointer the requested property name or NULL if there is no property at the given index.

const char * DasDesc_getValByIdx	(	const DasDesc *	pThis,
		size_t	uIdx
	)

inherited

Get a property value by an index.

This is useful when iterating over all properties in a Descriptor. Only properties owned by a descriptor are queried in this manner. Parent descriptors are not consulted.

See Also: DasDesc_length()

Parameters

pThis	A pointer to the descriptor to query
uIdx	The number of the property, will be a value from 0 and 1 less than the return value from Desc_getNProps()

Returns: A pointer the requested property value or NULL if there is no property at the given index.

bool DasDesc_has	(	const DasDesc *	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.

DasErrCode DasDesc_set	(	DasDesc *	pThis,
		const char *	sType,
		const char *	sName,
		const char *	sVal
	)

inherited

Generic property setter.

All properties are stored internally as strings. The various typed Desc_setProp* functions all call this function after converting their arguments to strings.

Warning: To insure that the string to type conversions are consistent it is strongly recommended that you use one of the typed functions instead of this generic version unless you have no choice.

Parameters

pThis	The Descriptor to receive the property
sType	The Type of property should be one of the strings: boolean double doubleArray Datum DatumRange int String Time TimeRange
sName	The property name, which cannot contain spaces
sVal	The value, which may be anything including NULL

Returns: 0 on success or a positive error code if there is a problem.

bool DasDesc_remove	(	DasDesc *	pThis,
		const char *	propretyName
	)

inherited

Remove a property from a descriptor, if preset.

It is safe to call this function for properties not present on the descriptor, it simply does nothing and returns false.

Returns: false if the property wasn't present to begin with, true otherwise

DasErrCode DasDesc_setStr	(	DasDesc *	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 DasDesc_getDouble	(	const DasDesc *	pThis,
		const char *	propertyName
	)

inherited

Read the property of type double named propertyName.

The property value is parsed using sscanf.

double DasDesc_getDatum	(	DasDesc *	pThis,
		const char *	sPropName,
		das_units	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 DAS_FILL_VALUE if conversion to the desired units is not possible.

DasErrCode DasDesc_setDatum	(	DasDesc *	pThis,
		const char *	sName,
		double	rVal,
		das_units	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 * DasDesc_getDoubleAry	(	DasDesc *	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 DasDesc_getInt	(	const DasDesc *	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()

bool DasDesc_getBool	(	DasDesc *	pThis,
		const char *	sPropName
	)

inherited

Get a property boolean value.

Parameters

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

Returns: True if the value is "true", or any positive integer, false otherwise.

DasErrCode DasDesc_getStrRng	(	DasDesc *	pThis,
		const char *	sName,
		char *	sMin,
		char *	sMax,
		das_units *	pUnits,
		size_t	uLen
	)

inherited

Get a property of type DatumRange with unconverted strings.

This version is handy if you just want to know the intrinsic units of the range without converting the values to some specific type of double value.

DasErrCode DasDesc_setFloatAry	(	DasDesc *	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 DasDesc_copyIn	(	DasDesc *	pThis,
		const DasDesc *	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.

DasErrCode DasDesc_encode	(	DasDesc *	pThis,
		DasBuf *	pBuf,
		const char *	sIndent
	)

inherited

Encode a generic set of properties to a buffer.

Parameters

pThis	The descriptors who's properties should be encoded
pBuf	A buffer object to receive the XML data
sIndent	An indent level for the property strings, makes 'em look nice

Returns: 0 if the operation succeeded, a non-zero return code otherwise.

Field Documentation

PktDesc* pktDesc[MAX_PKTIDS]

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* 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

Detailed Description

Public Member Functions

Data Fields

Descriptor Functions

Member Function Documentation

Field Documentation