das2/plane.h

Go to the documentation of this file.

#ifndef _das2_plane_h_
#define _das2_plane_h_

#include <stdbool.h>

#include <das2/buffer.h>
#include <das2/descriptor.h>
#include <das2/units.h>
#include <das2/encoding.h>

/* ************************************************************************* */
typedef enum plane_type {Invalid=-1, X=2001, Y=2003, Z=2004, YScan=2012
} plane_type_t;

plane_type_t str2PlaneType(const char * type);

const char* PlaneType_toString( plane_type_t type );


/* ************************************************************************* */
typedef struct plane_descriptor{
   Descriptor base;

   plane_type_t planeType;
   char* sName;
    
   /* The encoder/decoder used to read and write values for this plane. */
   DasEncoding* pEncoding;
    
   /* The units of measurement for values in this plane */
   UnitType units;
    
   /* The number of values in each packet of this plane.
    * For planes other than <yscan>'s this is always 1
    */
   size_t uItems;
   
   double* pData;
   double value;  /* Convenience for planes that only store one data point */
   bool bAlloccedBuf; /* true if hand to allocate a data buffer (<yscan> only)*/
   
   double* pYTags;
   UnitType yTagUnits;
   DasEncoding* pYEncoding;
   
   /* set to true setValues or decode is called, set to false when encode is 
    * called */
   bool bPlaneDataValid;
    
   /* 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 Plane Descriptor is created otherwise the library
    * doesn't deal with it in any other way. */
   void* pUser;  
   
} PlaneDesc;

PlaneDesc* new_PlaneDesc_empty(void);

PlaneDesc* new_PlaneDesc( 
   plane_type_t pt, const char* sName, DasEncoding* pType, UnitType units
);

PlaneDesc* new_PlaneDesc_yscan(
   const char* sName, DasEncoding* pZType, UnitType zUnits, size_t uItems,
   DasEncoding* pYType, const double* pYTags, UnitType yUnits
);

/* Creates a new plane descriptor from attribute strings
 * 
 * Unlike the other top-level descriptor objects in a Das2 Stream planes
 * are not independent XML documents.  This constructor is called from
 * the new_PktDesc_xml constructor to build plane descriptor object from
 * keyword / value stlye string lists.  The top level XML parsing is handled
 * by the PktDesc class.
 *
 * @param pParent the Properties parent for the new plane descriptor, this
 *        is always a PktDesc object pointer.
 *
 * @param pt The ::PlaneType, must be one of: 
 *    - X
 *    - Y 
 *    - YScan
 *    - Z
 *
 * @param attrs A null terminated array of strings.  It is assumed that
 *        the strings represent keyword value pairs.  i.e the first string
 *        is a setting name, such as 'units' the second string is the the
 *        value for 'units'.  Strings are processed in pairs until a NULL
 *        pointer is encountered.
 * 
 * @todo When encountering ASCII times, change the units to us2000 to better
 *       preserve precision for fine times for down stream processors.
 *  
 * @returns A pointer to new PlaneDesc allocated on the heap or NULL on an 
 *          error
 * @memberof PlaneDesc
 */
PlaneDesc* new_PlaneDesc_pairs(
   Descriptor* pParent, plane_type_t pt, const char** attrs
);

PlaneDesc* PlaneDesc_copy(const PlaneDesc* pThis);


void del_PlaneDesc(PlaneDesc* pThis);

plane_type_t PlaneDesc_getType(const PlaneDesc* pThis);

size_t PlaneDesc_getNItems(const PlaneDesc* pThis);

double PlaneDesc_getValue(const PlaneDesc* pThis, size_t uIdx);

ErrorCode PlaneDesc_setValue(PlaneDesc* pThis, size_t uIdx, double value);

ErrorCode PlaneDesc_setTimeValue(
   PlaneDesc* pThis, const char* sTime, size_t idx
);

DasEncoding* PlaneDesc_getValEncoder(PlaneDesc* pThis);

void PlaneDesc_setValEncoder(PlaneDesc* pThis, DasEncoding* pEnc);

const double* PlaneDesc_getValues(const PlaneDesc* pThis);


void PlaneDesc_setValues(PlaneDesc* pThis, const double* pData);


double PlaneDesc_getFill(const PlaneDesc* pThis );

bool PlaneDesc_isFill(const PlaneDesc* pThis, double value );

void PlaneDesc_setFill( PlaneDesc* pThis, double value );
                            
const char* PlaneDesc_getName(const PlaneDesc* pThis );

void PlaneDesc_setName(PlaneDesc* pThis, const char* sName);
 
UnitType PlaneDesc_getUnits(const PlaneDesc* pThis );

void PlaneDesc_setUnits(PlaneDesc* pThis, UnitType units);



UnitType PlaneDesc_getYTagUnits( PlaneDesc* pThis );

const double* PlaneDesc_getYTags(const PlaneDesc* pThis);


ErrorCode PlaneDesc_encode(
   PlaneDesc* pThis, DasBuf* pBuf, const char* sIndent, bool bDependant
);

ErrorCode PlaneDesc_encodeData(PlaneDesc* pThis, DasBuf* pBuf, bool bLast);

ErrorCode PlaneDesc_decodeData(const PlaneDesc* pThis, DasBuf* pBuf);

#endif /* _das2_plane_h_ */

---