Holds information for a single packet type in a Das2 stream. More...

#include <das2/packet.h>

Inheritance diagram for PktDesc:

Collaboration diagram for PktDesc:

[legend]

Public Member Functions
DAS_API PktDesc *	new_PktDesc (void)
	Creates a packet descriptor with the default settings. More...

DAS_API PktDesc *	copy_PktDesc (const PktDesc *pOther)
	Make a deep copy of a packet descriptor This is basically the copy constructor.

DAS_API PktDesc *	new_PktDesc_xml (DasBuf pBuf, DasDesc pParent, int nPktId)
	Create a PktDesc from XML data. More...

DAS_API int	PktDesc_getId (const PktDesc *pThis)
	Get the packet ID for this packet. More...

DAS_API const char *	PktDesc_getGroup (const PktDesc *pThis)
	Get the data group for this packet. More...

DAS_API void	PktDesc_setGroup (PktDesc pThis, const char sGroup)
	Set the data group for this packet. More...

DAS_API size_t	PktDesc_recBytes (const PktDesc *pThis)
	Get the size of data records defined by a packet descriptor. More...

DAS_API size_t	PktDesc_getNPlanes (const PktDesc *pThis)
	Get the number of planes in this type of packet. More...

DAS_API size_t	PktDesc_getNPlanesOfType (const PktDesc *pThis, plane_type_t pt)
	Get the number of planes of a particular type in a packet. More...

DAS_API int	PktDesc_addPlane (PktDesc pThis, PlaneDesc pPlane)
	Add a plane to a packet. More...

DAS_API DasErrCode	PktDesc_copyPlanes (PktDesc pThis, const PktDesc pOther)
	Copy in all planes from another a packet descriptor. More...

DAS_API bool	PktDesc_validate (PktDesc *pThis)
	Check to see if a legal plane layout is present. More...

DAS_API plane_type_t	PktDesc_getPlaneType (const PktDesc *pThis, int iPlane)
	Determine the type of plane by index. More...

DAS_API PlaneDesc *	PktDesc_getPlane (PktDesc *pThis, int iplane)
	returns the PlaneDescriptor for plane number iplane This can be used to query properties of the plane, such as units and the name. More...

DAS_API int	PktDesc_getPlaneIdxByType (const PktDesc *pThis, plane_type_t ptype, int iRelIndex)
	Gets the Nth plane of a given type. More...

DAS_API int	PktDesc_getPlaneIdxByName (PktDesc pThis, const char name, plane_type_t planeType)
	returns the plane number for the named plane. More...

DAS_API PlaneDesc *	PktDesc_getXPlane (PktDesc *pThis)
	returns the PlaneDescriptor for the 1st X Tag plane. More...

DAS_API DasErrCode	PktDesc_encode (const PktDesc pThis, DasBuf pBuf)
	Serialize a packet descriptor as XML data. More...

DAS_API DasErrCode	PktDesc_encodeData (const PktDesc pThis, DasBuf pBuf)
	Serialize a packet's current data In addition to holding the format information for Das2 Stream packets PktDesc objects also hold a a single packet's worth of data. More...

DAS_API DasErrCode	PktDesc_decodeData (PktDesc pThis, DasBuf pBuf)
	Decode 1 packet's worth of data from a buffer. More...

DAS_API DasErrCode	PktDesc_setValue (PktDesc *pThis, size_t uPlane, size_t uItem, double val)
	Convenience function for setting a single value in a plane This is just a shortcut for: More...

DAS_API DasErrCode	PktDesc_setValues (PktDesc pThis, size_t uPlane, const double pVals)
	Convenience function for setting an array of values in a plane This is just a shortcut for: More...

#define	DasDesc_type(P) ((P)->type)
	Get the type of this descriptor. More...

DAS_API void	DasDesc_init (DasDesc *pThis, desc_type_t type)
	Initialize a memory location as a valid das descriptor.

DAS_API char *	DasDesc_info (const DasDesc pThis, char sBuf, int nLen, char *sIndent)
	Print 1-line versions of each property in a descriptor.

DAS_API bool	DasDesc_equals (const DasDesc pThis, const DasDesc pOther)
	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...

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

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

DAS_API const DasProp *	DasDesc_getPropByIdx (const DasDesc *pThis, size_t uIdx)
	Get a property name by an index. More...

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

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

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

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

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

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

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

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

DAS_API size_t	DasDesc_getStrAry (DasDesc pThis, const char sName, char pBuf, size_t uBufSz, char *psVals, size_t uMaxVals)
	Get a multi-valued string property. More...

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

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

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

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

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

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

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

DAS_API DasErrCode	DasDesc_setDoubleArray (DasDesc pThis, const char sName, int nItems, double *pValues)
	Set the property of type double array.

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

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

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

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

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

DAS_API DasErrCode	DasDesc_setFloatAry (DasDesc pThis, const char sName, int nItems, float *pValues)
	Set the property of type float array. More...

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

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

Data Fields
void *	pUser
	User data pointer. More...

Detailed Description

Holds information for a single packet type in a Das2 stream.

A Das2 Stream may consist of up to 99 different types of packets. In the following Das2 Stream snippet two different types of packets are defined:

[00]000234<stream>
  <properties xMonotonic="true" xLabel="Time (s)" yLabel="Frequency (s!U-1!N)"
              zLabel="Electric Field (V m!U-1!N)" title="Voyager 1 PWS SA"
              Datum:xTagWidth="256.0 s" double:zFill="0.0" />
</stream>

[01]000201<packet>
  <x type="time24" units="us2000" ></x>
  <yscan name="averages" nitems="5" type="ascii9" yUnits="Hz" zUnits="V/m" 
         yTags="10.0,17.8,31.1,56.2,100.0">
    <properties zSummary="Average value within the interval"/>
  </yscan>
</packet>

[02]000201<packet>
  <x type="time24" units="us2000" ></x>
  <yscan name="peaks" nitems="5" type="ascii9" yUnits="Hz" zUnits="V/m" 
         yTags="10.0,17.8,31.1,56.2,100.0">
    <properties zSummary="Peak value within the interval"/>
  </yscan>
</packet>

:01:2012-01-01T12:56:22.792 1.91e-06 8.92e-07 7.80e-07 6.04e-07 2.43e-07
:02:2012-01-01T12:56:22.792 3.12e-06 4.10e-06 2.47e-06 1.42e-06 9.36e-07 
:01:2012-01-01T13:00:38.792 1.98e-06 4.63e-07 7.64e-07 7.56e-07 5.09e-07 
:02:2012-01-01T13:00:38.792 2.91e-06 1.46e-06 2.97e-06 1.42e-06 1.55e-06 

Each <packet> element above is a serialized PacketDescriptor. This structure and it's associated functions are responsible for:

Holding the definition of a single packet type within the stream
Writing data values onto the stream
Serializing data values from a stream

To help them do their jobs, PacketDescriptors hold and array of PlaneDescriptors, as well a byte field containing up to one data packet's worth of bytes.

Creating Packet Descriptors

Packet Descriptors are part of a Das2 Stream. To define a new packet type call:

createPacketDescriptor(StreamDesc* sd, DataType xDataType, UnitType xUnits)

StreamDesc

#define StreamDesc

Compatability macro For backwards compatability, all functions with the name pattern DasStream are al...

Definition: stream.h:132

or a similar function. This particular version creates a PacketDescriptor that only has an <x> plane. Using the following to add <y> and/or <yscan> planes to the packet.

addPlaneY()

addPlaneYScan()

Optionally additions properties such as labels may be added to each <y> or <yscan> plane using:

setPropertyString()

and related functions.

When reading Das2 Streams PacketDescriptors are created automatically as the input is read by the processStream() method of the StreamHandler.

Emitting Packet Data

The PacketDiscriptor has a 1-Packet wide buffer. This buffer is used to build up the output data for a single packet. To set the value for the various planes use:

setDataPacketDouble() // For <x> and <y> planes

setDataPacketYScanDouble() // For <yscan> planes

and related functions. Once that job is complete, transmit the data packet using:

sendPacket()

The details of encoding the data according the format stored in the packet descriptor are handled by the library.

Reading Data

Member Function Documentation

◆ new_PktDesc()

DAS_API PktDesc * new_PktDesc ( void )

Creates a packet descriptor with the default settings.

Returns: A pointer to a new PktDesc allocated on the heap, or NULL on an error.

◆ new_PktDesc_xml()

DAS_API PktDesc * new_PktDesc_xml	(	DasBuf *	pBuf,
		DasDesc *	pParent,
		int	nPktId
	)

Create a PktDesc from XML data.

Parameters

pBuf	The buffer to read. Reading will start with the read point and will run until DasBuf_remaining() is 0 or the end tag is found, which ever comes first.
pParent	The parent packet descriptor, this may be NULL
nPktId	The packet's ID within it's parent's array. May be 0 if and only if the pParent is NULL

Returns: A pointer to a new PktDesc allocated on the heap, or NULL on an error.

◆ PktDesc_getId()

DAS_API int PktDesc_getId ( const PktDesc * pThis )

Get the packet ID for this packet.

Each packet type within a Das 2 Stream has a unique ID form 1 to 99 inclusive. Note that ID's can be reused! So processing code must be on the lookout for re-definition packets.

Returns: the packet id, a number between 1 and 99 or -1 if there is on packet id assigned.

◆ PktDesc_getGroup()

DAS_API const char * PktDesc_getGroup ( const PktDesc * pThis )

Get the data group for this packet.

Packets with the same group should be able to be plotted on the same graph. This is the same as a join in QDataset terms

Parameters

pThis A pointer to a packet desciptor structure

Returns: NULL if the packet has no specified group, or the group string which follows the rules for valid identifers in das_assert_valid_id()

◆ PktDesc_setGroup()

DAS_API void PktDesc_setGroup	(	PktDesc *	pThis,
		const char *	sGroup
	)

Set the data group for this packet.

Parameters

pThis	A pointer to a packet descriptor structure
sGroup	The new group name which must be a valid id.

◆ PktDesc_recBytes()

DAS_API size_t PktDesc_recBytes ( const PktDesc * pThis )

Get the size of data records defined by a packet descriptor.

Parameters

pThis The packet descriptor to query

Returns: The size in bytes of a single packet's worth of data.

◆ PktDesc_getNPlanes()

DAS_API size_t PktDesc_getNPlanes ( const PktDesc * pThis )

Get the number of planes in this type of packet.

Parameters

pThis the packet descriptor in question

Returns: The number of planes defined in this packet.

◆ PktDesc_getNPlanesOfType()

DAS_API size_t PktDesc_getNPlanesOfType	(	const PktDesc *	pThis,
		plane_type_t	pt
	)

Get the number of planes of a particular type in a packet.

Parameters

pThis	The packet descriptor to check
pt	the plane type to check

Returns: The number of planes of a particular type in this packet descriptor

◆ PktDesc_addPlane()

DAS_API int PktDesc_addPlane	(	PktDesc *	pThis,
		PlaneDesc *	pPlane
	)

Add a plane to a packet.

All data in a das2 stream are sent via packets, each packet type has 1-100 planes. A plane can be a single column of numbers, which has one value per data packet, or in the case of <yscan> planes they can be more like sub-tables which have many values per packet. The newly added plane will have this PktDesc assigned as it's parent.

Planes have types. A Packet must have at least 1 <x> plane. In general it may have as many <y> <yscan> planes as it likes up to the plane limit. For packets with <z> planes, no <yscan> planes are allowed and one and only one <y> plane must be preset. This function enforces the packet formation rules. In summary the following patterns are legal.

X [X]
X [X] Y [Y Y ...]
X [X] YScan [YScan YScan ...]
X [X] Y [Y Y ...] YScan [YScan YScan ...] (see note)
X [X] Z [Z Z ...]

where [] indicates optional planes. Note: Y and YScan planes can be interleaved in any order.

This function adds the plane after all existing planes. Thus the index of any existing planes is not altered.

Parameters

pThis	The packet descriptor to receive the new plane definition
pPlane	The plane to add

Returns: On success the index of the new plane is returned, or -1 on an error

◆ PktDesc_copyPlanes()

DAS_API DasErrCode PktDesc_copyPlanes	(	PktDesc *	pThis,
		const PktDesc *	pOther
	)

Copy in all planes from another a packet descriptor.

Deepcopy's the plane descriptors in pOther and attaches the newly allocated planes to this PktDesc object. This packet descriptor must not already have any planes defined or this function will fail.

Parameters

pThis	the destination for the newly allocated PlaneDescriptors
pOther	the source of the PlaneDescriptors

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

◆ PktDesc_validate()

DAS_API bool PktDesc_validate ( PktDesc * pThis )

Check to see if a legal plane layout is present.

Since not all checks for a legal packet layout can be made while the sub-objects are being added to the packet descriptor, this function is provided to check the layout after adding all planes to a packet.

See also: PktDesc_addPlane()

Parameters

pThis The packet descriptor to check

Returns: true if this packet descriptor has a legal set of planes, false otherwise.

◆ PktDesc_getPlaneType()

DAS_API plane_type_t PktDesc_getPlaneType	(	const PktDesc *	pThis,
		int	iPlane
	)

Determine the type of plane by index.

Parameters

pThis	the packet descriptor to query
iPlane	the index in question. Valid values for this parameter are 0 to MAXPLANES - 1

Returns

If the index corresponds to a data plane, then one of the enum values is return:

X
Y
YSCAN
Z

is returned, otherwise:

Invalid

is returned

◆ PktDesc_getPlane()

DAS_API PlaneDesc * PktDesc_getPlane	(	PktDesc *	pThis,
		int	iplane
	)

returns the PlaneDescriptor for plane number iplane This can be used to query properties of the plane, such as units and the name.

Parameters

pThis	The packet descriptor to query
iplane	The index of the plane to retrieve. The 0th plane is an <x> plane if one is present in the stream.

◆ PktDesc_getPlaneIdxByType()

DAS_API int PktDesc_getPlaneIdxByType	(	const PktDesc *	pThis,
		plane_type_t	ptype,
		int	iRelIndex
	)

Gets the Nth plane of a given type.

This is useful for iterating over all planes of a given type.

Parameters

pThis	A packet descriptor structure pointer.
ptype	The plane type, one X, Y, Z, YScan
iRelIndex	The number of the plane of a given type to find. The lowest index will be 0 for a given type.

Returns: The absolute plane index for the Nth plane of a given type. If No planes of the given type are present, or iIndex is out of range -1 is returned.

◆ PktDesc_getPlaneIdxByName()

DAS_API int PktDesc_getPlaneIdxByName	(	PktDesc *	pThis,
		const char *	name,
		plane_type_t	planeType
	)

returns the plane number for the named plane.

Parameters

pThis	The packet descriptor to query.
name	The name in of the plane to find
planeType	if not set to 0, then PlaneType must also match. Note that typically the 0th plane is typically the <x> plane.

◆ PktDesc_getXPlane()

DAS_API PlaneDesc * PktDesc_getXPlane ( PktDesc * pThis )

returns the PlaneDescriptor for the 1st X Tag plane.

◆ PktDesc_encode()

DAS_API DasErrCode PktDesc_encode	(	const PktDesc *	pThis,
		DasBuf *	pBuf
	)

Serialize a packet descriptor as XML data.

Parameters

pThis	The packet descriptor to store as string data
pBuf	A buffer object to received the string data

Returns: 0 if successful, or a positive integer if not.

◆ PktDesc_encodeData()

DAS_API DasErrCode PktDesc_encodeData	(	const PktDesc *	pThis,
		DasBuf *	pBuf
	)

Serialize a packet's current data In addition to holding the format information for Das2 Stream packets PktDesc objects also hold a a single packet's worth of data.

Use this function to encode the current data values for output.

Parameters

pThis	The packet descriptor that has been loaded with data
pBuf	A buffer to receive the encoded bytes

Returns: 0 if successful, or a positive integer if not.

◆ PktDesc_decodeData()

DAS_API DasErrCode PktDesc_decodeData	(	PktDesc *	pThis,
		DasBuf *	pBuf
	)

Decode 1 packet's worth of data from a buffer.

Parameters

pThis	the packet descriptor to handle decoding
pBuf	The buffer with the data, data will be read from the current read point.

Returns: 0 if successful, or a positive integer if not.

◆ PktDesc_setValue()

DAS_API DasErrCode PktDesc_setValue	(	PktDesc *	pThis,
		size_t	uPlane,
		size_t	uItem,
		double	val
	)

Convenience function for setting a single value in a plane This is just a shortcut for:

PlaneDesc* pPlane = PktDesc_getPlane(pPkt, uPlane);

PlaneDesc_setValue(pPlane, uItem, value);

PktDesc::PktDesc_getPlane

DAS_API PlaneDesc * PktDesc_getPlane(PktDesc *pThis, int iplane)

returns the PlaneDescriptor for plane number iplane This can be used to query properties of the plane...

PlaneDesc

Describes a data plane within a packet type.

Definition: plane.h:120

Parameters

pThis	The packet descriptor in question.
uPlane	The index of the plane to receive the values
uItem	The index of the item in the plane to be set to the new value
val	The new value for this item in this plane.

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

◆ PktDesc_setValues()

DAS_API DasErrCode PktDesc_setValues	(	PktDesc *	pThis,
		size_t	uPlane,
		const double *	pVals
	)

Convenience function for setting an array of values in a plane This is just a shortcut for:

PlaneDesc* pPlane = PktDesc_getPlane(pPkt, uPlane);

PlaneDesc_setValues(pPlane, pVals);

Parameters

pThis	The packet descriptor in question.
uPlane	The index of the plane to receive the values
pVals	The array of values to set. The array is assumed to be the same length as the number of items in plane uPlane

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

◆ DasDesc_equals()

DAS_API bool DasDesc_equals	(	const DasDesc *	pThis,
		const DasDesc *	pOther
	)

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

pThis	The first descriptor
pOther	The second descriptor

◆ DasDesc_parent()

DAS_API 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)

◆ DasDesc_length()

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

◆ DasDesc_getPropByIdx()

DAS_API const DasProp * DasDesc_getPropByIdx	(	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 valid 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_length(). For efficient storage properties that have been erased or over-written are left in place internally and just marked as invalid.

Returns: A pointer the requested property, or NULL if the property is not valid. A NULL return does not mean than the next higher index has an invalid property

◆ DasDesc_getNameByIdx()

DAS_API 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_length()

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

◆ DasDesc_getValByIdx()

DAS_API 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_length()

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

◆ DasDesc_has()

DAS_API bool DasDesc_has	(	const DasDesc *	pThis,
		const char *	sName
	)

inherited

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

Parameters

pThis	the descriptor object to query
sName	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.

◆ DasDesc_set()

DAS_API 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. This value is passed down to DasProp_init2(), see that function for a list of known values.
sName	The property name. For das2 & das3 this can't 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.

◆ DasDesc_remove()

DAS_API bool DasDesc_remove	(	DasDesc *	pThis,
		const char *	sName
	)

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

◆ DasDesc_getStrAry()

DAS_API size_t DasDesc_getStrAry	(	DasDesc *	pThis,
		const char *	sName,
		char *	pBuf,
		size_t	uBufSz,
		char **	psVals,
		size_t	uMaxVals
	)

inherited

Get a multi-valued string property.

Some properties, especially those from DSDF files, contain multiple string values in a single field separated by pipe "|" characters. For example:

data_01 = 'efield | Electric field intensity | V m**-1'

This function breaks these values into multiple strings without requiring heap memory.

Output bytes are copied into the given val_buf. Then null values are then written over all leading and trailing whitespace for each element as well as the pipe characters.

Finally a pointer to each starting string is copied into ptr_buf. If an element contains not data, for example:

coord_01 = 'frequency | | Hz'

then the corresponding character pointer will be NULL, but the number of character pointers is unchanged.

Parameters

[in]	pThis	the descriptor to query
[in]	name	the name of the property to retrieve
[out]	val_buf	will hold the full output property data
[in]	val_buf_sz	the maximum number of bytes to copy out including the terminating null character.
[out]	ptr_buf	will hold pointers to the start of each property value. If a value is empty, the corresponding pointer is null.
[in]	ptr_buf_sz	the maximum number of string pointers write to ptr_buf.

Returns: The number of string values for this property, which is zero if a property with the given name is not present.

See also: DasDesc_getStr to retrieve the original property value in a single buffer unaltered.

◆ DasDesc_setStr()

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

◆ DasDesc_getDouble()

DAS_API double DasDesc_getDouble	(	const DasDesc *	pThis,
		const char *	sName
	)

inherited

Read the property of type double named sName.

The property value is parsed using sscanf.

◆ DasDesc_setDouble()

DAS_API DasErrCode DasDesc_setDouble	(	DasDesc *	pThis,
		const char *	sName,
		double	value
	)

inherited

Set property of type double.

◆ DasDesc_getDatum()

DAS_API double DasDesc_getDatum	(	DasDesc *	pThis,
		const char *	sName,
		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.
sName	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.

◆ DasDesc_setDatum()

DAS_API 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

◆ DasDesc_getDoubleAry()

DAS_API double * DasDesc_getDoubleAry	(	DasDesc *	pThis,
		const char *	sName,
		int *	pNumItems
	)

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]	sName	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: DasDesc_has()

◆ DasDesc_getInt()

DAS_API int DasDesc_getInt	(	const DasDesc *	pThis,
		const char *	sName
	)

inherited

Get a property integer value.

Parameters

pThis	the descriptor object to query
sName	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: DasDesc_has()

◆ DasDesc_getBool()

DAS_API bool DasDesc_getBool	(	DasDesc *	pThis,
		const char *	sName
	)

inherited

Get a property boolean value.

Parameters

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

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

◆ DasDesc_getStrRng()

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

◆ DasDesc_setFloatAry()

DAS_API DasErrCode DasDesc_setFloatAry	(	DasDesc *	pThis,
		const char *	sName,
		int	nItems,
		float *	pValues
	)

inherited

Set the property of type float array.

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

◆ DasDesc_copyIn()

DAS_API void DasDesc_copyIn	(	DasDesc *	pThis,
		const DasDesc *	pOther
	)

inherited

Deepcopy properties into a descriptor.

Parameters

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

◆ DasDesc_encode2()

DAS_API DasErrCode DasDesc_encode2	(	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

◆ pUser

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 packet descriptor 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/packet.h

Public Member Functions

Data Fields

Detailed Description

Creating Packet Descriptors

Emitting Packet Data

Reading Data

Member Function Documentation

◆ new_PktDesc()

◆ new_PktDesc_xml()

◆ PktDesc_getId()

◆ PktDesc_getGroup()

◆ PktDesc_setGroup()

◆ PktDesc_recBytes()

◆ PktDesc_getNPlanes()

◆ PktDesc_getNPlanesOfType()

◆ PktDesc_addPlane()

◆ PktDesc_copyPlanes()

◆ PktDesc_validate()

◆ PktDesc_getPlaneType()

◆ PktDesc_getPlane()

◆ PktDesc_getPlaneIdxByType()

◆ PktDesc_getPlaneIdxByName()

◆ PktDesc_getXPlane()

◆ PktDesc_encode()

◆ PktDesc_encodeData()

◆ PktDesc_decodeData()

◆ PktDesc_setValue()

◆ PktDesc_setValues()

◆ DasDesc_equals()

◆ DasDesc_parent()

◆ DasDesc_length()

◆ DasDesc_getPropByIdx()

◆ DasDesc_getNameByIdx()

◆ DasDesc_getValByIdx()

◆ DasDesc_has()

◆ DasDesc_set()

◆ DasDesc_remove()

◆ DasDesc_getStrAry()

◆ DasDesc_setStr()

◆ DasDesc_getDouble()

◆ DasDesc_setDouble()

◆ DasDesc_getDatum()

◆ DasDesc_setDatum()

◆ DasDesc_getDoubleAry()

◆ DasDesc_getInt()

◆ DasDesc_getBool()

◆ DasDesc_getStrRng()

◆ DasDesc_setFloatAry()

◆ DasDesc_copyIn()

◆ DasDesc_encode2()

Field Documentation

◆ pUser