Descriptor Struct Reference

#include <das2/descriptor.h>

Inheritance diagram for Descriptor:

---

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 PacketDesc's
• PacketDesc's have 1-N PlaneDesc's

Todo:

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

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

bool Desc_hasProp	(	const Descriptor *	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.

ErrorCode Desc_setPropStr	(	Descriptor *	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 Desc_getPropDouble	(	const Descriptor *	pThis,
		const char *	propertyName
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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.

---

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

• das2/descriptor.h