PktDesc Struct Reference

#include <das2/packet.h>

Inheritance diagram for PktDesc:

---

Detailed Description

Hold 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:

1. Holding the definition of a single packet type within the stream
2. Writing data values onto the stream
3. 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)

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

Public Member Functions
PktDesc *	new_PktDesc (void)
	Creates a packet descriptor with the default settings.
PktDesc *	new_PktDesc_xml (DasBuf *pBuf, Descriptor *pParent, int nPktId)
	Create a PktDesc from XML data.
int	PktDesc_getId (const PktDesc *pThis)
	Get the packet ID for this packet.
size_t	PktDesc_recBytes (const PktDesc *pThis)
	Get the size of data records defined by a packet descriptor.
size_t	PktDesc_getNPlanes (const PktDesc *pThis)
	Get the number of planes in this type of packet.
size_t	PktDesc_getNPlanesOfType (const PktDesc *pThis, plane_type_t pt)
	Get the number of planes of a particular type in a packet.
int	PktDesc_addPlane (PktDesc *pThis, PlaneDesc *pPlane)
	Add a plane to a packet.
ErrorCode	PktDesc_copyPlanes (PktDesc *pThis, const PktDesc *pOther)
	Copy in all planes from another a packet descriptor.
bool	PktDesc_validate (PktDesc *pThis)
	Check to see if a legal plane layout is present.
plane_type_t	PktDesc_getPlaneType (const PktDesc *pThis, int iPlane)
	Determine the type of plane by index.
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.
int	PktDesc_getPlaneNum (const PktDesc *pThis, plane_type_t ptype, int iRelIndex)
	Gets the Nth plane of a given type.
int	PktDesc_getPlaneNumByName (PktDesc *pThis, const char *name, plane_type_t planeType)
	returns the plane number for the named plane.
PlaneDesc *	PktDesc_getXPlane (PktDesc *pThis)
	returns the PlaneDescriptor for the 1st X Tag plane.
ErrorCode	PktDesc_encode (const PktDesc *pThis, DasBuf *pBuf)
	Serialize a packet descriptor as XML data.
ErrorCode	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.
ErrorCode	PktDesc_decodeData (PktDesc *pThis, DasBuf *pBuf)
	Decode 1 packet's worth of data from a buffer.
ErrorCode	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:.
ErrorCode	PktDesc_setValues (PktDesc *pThis, size_t uPlane, double *pVals)
	Convenience function for setting an array of values in a plane This is just a shortcut for:.
Data Fields
void *	pUser
	User data pointer.
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

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.

PktDesc * new_PktDesc_xml	(	DasBuf *	pBuf,
		Descriptor *	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.

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.

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.

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.

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

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

ErrorCode 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

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.

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

int PktDesc_getPlaneNum	(	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.

int PktDesc_getPlaneNumByName	(	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.

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

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

ErrorCode PktDesc_decodeData	(	PktDesc *	pThis,
		DasBuf *	pBuf
	)

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

Parameters:

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

Returns:

0 if successful, or a positive integer if not.

ErrorCode 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);

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

ErrorCode PktDesc_setValues	(	PktDesc *	pThis,
		size_t	uPlane,
		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

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

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

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
	)			[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 FILL_VALUE if conversion to the desired units is not possible.

ErrorCode Desc_setPropDatum	(	Descriptor *	pThis,
		const char *	sName,
		double	rVal,
		UnitType	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 * Desc_getPropDoubleArray	(	Descriptor *	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 Desc_getPropInt	(	const Descriptor *	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()

ErrorCode Desc_setPropFloatArray	(	Descriptor *	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 Desc_copyProperties	(	Descriptor *	pThis,
		const Descriptor *	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.

---

Field Documentation

void* PktDesc::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