das2/descriptor.h File Reference

---

Detailed Description

#include <stdbool.h>
#include <das2/units.h>
#include <das2/util.h>
#include <das2/buffer.h>

Go to the source code of this file.

Data Structures
struct	Descriptor
	Base structure for Stream Header Items. More...
Enumerations
enum	desc_type_t
	enumeration of Descriptor types, used internally for type checking. More...
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");
void	Desc_init (Descriptor *pThis, desc_type_t type)
Descriptor *	new_Descriptor (void)
void	Desc_freeProps (Descriptor *pThis)
bool	Desc_equals (const Descriptor *pOne, const Descriptor *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.
Descriptor *	Desc_getParent (Descriptor *pThis)
	The the parent of a Descriptor.
size_t	Desc_getNProps (const Descriptor *pThis)
	Get the number of properties in a descriptor.
const char *	Desc_getPropNameByNum (const Descriptor *pThis, size_t uIdx)
	Get a property name by an index.
const char *	Desc_getPropValByNum (const Descriptor *pThis, size_t uIdx)
	Get a property value by an index.
ErrorCode	Desc_setProp (Descriptor *pThis, const char *sType, const char *sName, const char *sVal)
	Generic property setter.
const char *	Desc_getProp (const Descriptor *pThis, const char *propertyName)
bool	Desc_getPropBool (Descriptor *pThis, const char *sPropName)
	Get a property boolean value.
ErrorCode	Desc_setPropBool (Descriptor *pThis, const char *sPropName, bool bVal)
	Set a boolean property Encodes the value as either the string "true" or the string "false".
ErrorCode	Desc_encode (Descriptor *pThis, DasBuf *pBuf, const char *sIndent)
	Encode a generic set of properties to a buffer.

---

Enumeration Type Documentation

enum desc_type_t

enumeration of Descriptor types, used internally for type checking.

May have one of the following values:

1. Plane
2. Packet
3. Stream

---

Function Documentation

void Desc_init	(	Descriptor *	pThis,
		desc_type_t	type
	)

bool Desc_equals	(	const Descriptor *	pOne,
		const Descriptor *	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:

	pDesc1	The first descriptor
	pDesc2	The second descriptor

Descriptor* Desc_getParent

(

Descriptor *

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 Desc_getNProps

(

const Descriptor *

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:

getPropNameByNum()

getPropValByNum()

Parameters:

pThis

A pointer to the descriptor to query

Returns:

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

const char* Desc_getPropNameByNum	(	const Descriptor *	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:

Desc_getNProps()

Parameters:

	pThis	A pointer to the descriptor to query
	uNum	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* Desc_getPropValByNum	(	const Descriptor *	pThis,
		size_t	uIdx
	)

Get a property value 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. sv

See also:

Desc_getNProps()

Parameters:

	pThis	A pointer to the descriptor to query
	uNum	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.

ErrorCode Desc_setProp	(	Descriptor *	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 Desc_getPropBool	(	Descriptor *	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.

ErrorCode Desc_setPropBool	(	Descriptor *	pThis,
		const char *	sPropName,
		bool	bVal
	)

Set a boolean property Encodes the value as either the string "true" or the string "false".

Parameters:

	pThis	The descriptor to receive the property
	propertyName	the name of the property
	value	either true or false.

ErrorCode Desc_encode	(	Descriptor *	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.