#include <das2/descriptor.h>

Inheritance diagram for DasDesc:

Detailed Description

Base structure for Stream Header Items.

Descriptors have properties associated with them. Stream Descriptors, Packet Descriptors, and Plane Descriptors are all extensions of this object type, thus the functions for this structure may be used with any Descriptor structure in the library.

Note: Properties Cascade

Properties cascade in Das2 Streams. Thus if a particular descriptor does not have a particular property then the various getProperty() functions will search parent descriptors for requested property. The descriptor ownership hierarchy for Das2 Streams is:

StreamDesc's have 1-N PktDesc's
PktDesc's have 1-N PlaneDesc's

Todo:: Move child relationship into the descriptor base class, parent is there but the other direction is missing

Todo:: This implementation is very inefficient requring many small malloc's and order(N) object lookups. It also has types, keys and values all mixed together in the same array or the same value. This makes object lookup a wierd i+=2 iteration with ":" searches. We only get away with this because not much is stored in the properies arrays.

  This class this is just a hobbled dictionary of objects plus some
  string conversion functions.  Using an actual C dictionary
  implementation would improve code quite a bit.  If I were going to go
  to the trouble to do that I would make it multi-lingual as well. -cwp

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

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.

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 )

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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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.

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

das2/descriptor.h

Detailed Description

Descriptor Functions

Member Function Documentation