#include <CDocumentedPacket>
class CDocumentedPacket {CDocumentedPacket(unsigned short nTag, const std::string& rName, const std::string& Description, const std::string& rVersion);const int operator==(const CDocumentedPacket& rhs);const int operator==(const std::string& rhs);const int operator!=(const CDocumentedPacket& rhs);const int operator!=(const std::string& rhs);const unsigned short getTag();const std::string getName();const std::string getDescription();const std::string getVersion();const std::string getInstantiationDate();const unsigned short* getHeaderPtr();const bool getPacketInProgress();std::string Format();unsigned short* Begin(unsigned short* rPointer);unsigned short* End(unsigned short* rBuffer);}
NSCL data taking programs should try to emit self describing event data. This is facilitated by providing code to support the generation of packets. A packet is a chunk of event data with a three word header. The first longword (32 bits), is the number of words in the packet, including the header. The last word of the header is an identifying code. The remainder of the packet are the data read out for that identifying code.
http://groups.nscl.msu.edu/userinfo/daq/nscltags.html defines the set of identifiers (tags) that are defined. The tag assigner for permanent devices is bazin at nscl dot msu dot edu. Contact him if you need a new tag assigned.
The CDocumentedPacket class goes a step further
than encapsulating your data. It registers itself with the framework
in a way that allows the framework to emit data that describes the set
of tags, and versions to expect in the event data.
CDocumentedPacket(unsigned short nTag, const std::string& rName, const std::string& Description, const std::string& rVersion);
Constructs a documented packet. nTag is the
packet id and is the tag assigned to the packet, or one of the user
defined tags.
rName is a short name for the tag. In the tag table
at
http://groups.nscl.msu.edu/userinfo/daq/nscltags.html,
this is the value of the Acronym column.
Description is a more verbose description
and might be the Description column of that
table. rVersion is a string that allows you
to indicate changes in the internal structure of this packet over time.
This can allow analysis software to dynamically adapt to data format
changes by knowing which data format is actually in the packet.
const int operator==(const CDocumentedPacket& rhs);
const int operator==(const std::string& rhs);
const int operator!=(const CDocumentedPacket& rhs);
const int operator!=(const std::string& rhs);
const unsigned short getTag();
Returns the tag that has been assigned to this documented packet.
const std::string getName();
Returns the short name assigned to the packet
const std::string getDescription();
Returns the long description assigned to the packet.
const std::string getVersion();
Returns the packet version string
const std::string getInstantiationDate();
When a packet object is created a timestamp indicating when the object was create is also created. This returns that timestamp. The idea of this is to be able to account for any format changes that might have occured during an experiment that were accidently not reflected by updating the version of the packet.
const unsigned short* getHeaderPtr();
Returns a pointer to the header of the packet. This is only meaningful
if the packet is in the process of being emitted. See
getPacketInProgress below.
const bool getPacketInProgress();
Returns true if the packet is in the process of being built.
std::string Format();
Returns an information string about the packet that can be inserted in to a packet documentation event.
unsigned short* Begin(unsigned short* rPointer);
Starts the creation of a packet. rPointer
points to the location in memory in which the packet will be built.
The function returns a pointer to the packet body. The caller should
not refrence the packet header directly.
unsigned short* End(unsigned short* rBuffer);
Indicates that the packet body has been filled in. rBuffer
points to the first word after the packet. It is used to compute and
fill in the packet length header field.
Under several circumstances, this class can throw a
CInvalidPacketStateException
Specifically attempting to begin a packet that's already begun or ending a packet that's already ended, will cause this to be thrown.
Example 1. Using the CDocumentedPacket class
class MySegment : public CEventSegment
{
private:
CDocumentedPacket m_Packet;
public:
MySegment() :
CDocumentedPacket(0x1234, "Test", "A test packet", "T1.0")
{
}
size_t read(void* pBuffer, size_t maxlen);
...
}
size_t
MySegment::read(void* pBuffer, size_t maxlen)
{
uint16_t* p = reinterpret_cast<uint16_t*>(pBuffer);
uint16_t pBody = m_Packet.Begin(p);
// Fill in packet body incrementing pBody
...
m_Packet.End(pBody);
}