FARGOS/VISTA Object Management Environment Core  ..
FARGOS/VISTA Object Management Environment Core Table of Contents
FARGOS Meta Data Classes

Facilities to read/write/transform self-describing meta data files. More...

Classes

struct  UniversalMetaData_FieldDescription
 Field Description record for self-describing meta data. More...
 
struct  UniversalMetaData_ReferenceFileHeader
 File header for self-describing meta data file format. More...
 
struct  UniversalMetaData_ReferenceRecordHeader
 Optional meta data record header used in meta data files containing variable-length records. More...
 
struct  GENERIC_META_RECORD
 Typename for qualifying MetaDataLoaderForFormat members. More...
 
class  MetaDataLoaderForFormat< RECORD_CLASS >
 Templated interface to static data that provides the description of a specific layout of meta data. It can also load/save such formats from/to a file. More...
 

Macros

#define RELATIVE_FIELD_OFFSET(className, n)   (reinterpret_cast<unsigned char *>(&(((className *)(8192))-> n)) - reinterpret_cast<unsigned char *>(8192))
 Return relative offset of a field within a structure by pretending the structure was on a page-aligned boundary. More...
 
#define DESCRIBE_NAMED_FIELD_OF_CLASS(shortName, n, t, className)   { 1, SharedMemoryVariable:: t, (uint16_t) RELATIVE_FIELD_OFFSET(className,n), sizeof(((className *)(0))-> n), {""}, { shortName } }
 Convenience macro to describe an element of a structure. More...
 
#define DESCRIBE_OPTIONAL_NAMED_FIELD_OF_CLASS(group, shortName, n, t, className)   { group, SharedMemoryVariable:: t, (uint16_t) RELATIVE_FIELD_OFFSET(className,n), sizeof(((className *)(0))-> n), {""}, { shortName } }
 Convenience macro to describe an optional element of a structure. More...
 
#define DESCRIBE_OPTIONAL_OR_ZERO_FILLED_NAMED_FIELD_OF_CLASS(group, shortName, n, t, className)   { __ZERO_FILL_BIT | (group), SharedMemoryVariable:: t, (uint16_t) RELATIVE_FIELD_OFFSET(className,n), sizeof(((className *)(0))-> n), {""}, { shortName } }
 Convenience macro to describe an optional element of a structure that should be treated as zero-filled if not present. More...
 
#define DESCRIBE_FIELD_OF_CLASS(n, t, className)   DESCRIBE_NAMED_FIELD_OF_CLASS(#n, n, t, className)
 Convenience macro which is a simpler case of DESCRIBE_NAMED_FIELD_OF_CLASS. The text name of the field is the same as the name of the member element. More...
 
#define DESCRIBE_OPTIONAL_FIELD_OF_CLASS(group, n, t, className)   DESCRIBE_NAMED_FIELD_OF_CLASS(group, #n, n, t, className)
 Convenience macro which is a simpler case of DESCRIBE_OPTIONAL_NAMED_FIELD_OF_CLASS. The text name of the field is the same as the name of the member element. More...
 
#define DESCRIBE_OPTIONAL_OR_ZERO_FILLED_FIELD_OF_CLASS(group, n, t, className)   DESCRIBE_NAMED_FIELD_OF_CLASS(__ZERO_FILL_BIT | (group), #n, n, t, className)
 Convenience macro which is a simpler case of DESCRIBE_OPTIONAL_NAMED_FIELD_OF_CLASS and tags the field as to be viewed as zero-filled if not present. The text name of the field is the same as the name of the member element. More...
 

Typedefs

typedef int(* ConvertAndTransferFieldFP) (const UniversalMetaData_FieldDescription *sourceDescr, const UniversalMetaData_FieldDescription *destDescr, const unsigned char *sourceRecord, unsigned char *destinationRecord, void *userData)
 Protototype for metadata conversion callback. More...
 

Functions

int inspectMetaDataHeaderInFile (struct UniversalMetaData_ReferenceFileHeader *hdr, const char *fileName)
 Retrieve the meta data file header from a file. More...
 
int64_t writeUniversalMetaDataMetaDataToFile (const uint32_t fieldTotal, const UniversalMetaData_FieldDescription *fieldDescTbl, const char *magicNumber, const char *fileName, const uint32_t totalRecords, const void **tableBase, const uint32_t outputRecordLength)
 Generic routine to write a meta data description file. More...
 
int defaultConvertAndTransferField (const UniversalMetaData_FieldDescription *sourceDescr, const UniversalMetaData_FieldDescription *destDescr, const unsigned char *sourceRecord, unsigned char *destinationRecord, void *userData)
 Default conversion routine to convert from one described format to another. More...
 
template<typename TO_FORMAT , typename FROM_FORMAT = GENERIC_META_RECORD>
TO_FORMAT * loadAndConvertMetaData (const char *fileName, uint32_t *recTotal, ConvertAndTransferFieldFP transferFunction=defaultConvertAndTransferField, void *userData=nullptr)
 Load an existing metadata file and process the records. Normally this is used to convert from one format into another, but this is not required. More...
 

Detailed Description

Facilities to read/write/transform self-describing meta data files.

Macro Definition Documentation

◆ DESCRIBE_FIELD_OF_CLASS

#define DESCRIBE_FIELD_OF_CLASS (   n,
  t,
  className 
)    DESCRIBE_NAMED_FIELD_OF_CLASS(#n, n, t, className)

Convenience macro which is a simpler case of DESCRIBE_NAMED_FIELD_OF_CLASS. The text name of the field is the same as the name of the member element.

Parameters
nmember name of structure element
ttype of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc.
classNameis the name of the struct or class representing the record

◆ DESCRIBE_NAMED_FIELD_OF_CLASS

#define DESCRIBE_NAMED_FIELD_OF_CLASS (   shortName,
  n,
  t,
  className 
)    { 1, SharedMemoryVariable:: t, (uint16_t) RELATIVE_FIELD_OFFSET(className,n), sizeof(((className *)(0))-> n), {""}, { shortName } }

Convenience macro to describe an element of a structure.

Parameters
shortNametext label for field; this is a text string.
nmember name of structure element
ttype of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc.
classNameis the name of the struct or class representing the record

Field is declared to be member of group 1.

◆ DESCRIBE_OPTIONAL_FIELD_OF_CLASS

#define DESCRIBE_OPTIONAL_FIELD_OF_CLASS (   group,
  n,
  t,
  className 
)    DESCRIBE_NAMED_FIELD_OF_CLASS(group, #n, n, t, className)

Convenience macro which is a simpler case of DESCRIBE_OPTIONAL_NAMED_FIELD_OF_CLASS. The text name of the field is the same as the name of the member element.

Parameters
groupspecifies id for field group (1-63)
nmember name of structure element
ttype of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc.
classNameis the name of the struct or class representing the record

◆ DESCRIBE_OPTIONAL_NAMED_FIELD_OF_CLASS

#define DESCRIBE_OPTIONAL_NAMED_FIELD_OF_CLASS (   group,
  shortName,
  n,
  t,
  className 
)    { group, SharedMemoryVariable:: t, (uint16_t) RELATIVE_FIELD_OFFSET(className,n), sizeof(((className *)(0))-> n), {""}, { shortName } }

Convenience macro to describe an optional element of a structure.

Parameters
groupspecifies id for field group (1-63)
shortNametext label for field
nmember name of structure element
ttype of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc.
classNameis the name of the struct or class representing the record

◆ DESCRIBE_OPTIONAL_OR_ZERO_FILLED_FIELD_OF_CLASS

#define DESCRIBE_OPTIONAL_OR_ZERO_FILLED_FIELD_OF_CLASS (   group,
  n,
  t,
  className 
)    DESCRIBE_NAMED_FIELD_OF_CLASS(__ZERO_FILL_BIT | (group), #n, n, t, className)

Convenience macro which is a simpler case of DESCRIBE_OPTIONAL_NAMED_FIELD_OF_CLASS and tags the field as to be viewed as zero-filled if not present. The text name of the field is the same as the name of the member element.

Parameters
groupspecifies id for field group (1-63)
nmember name of structure element
ttype of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc.
classNameis the name of the struct or class representing the record

◆ DESCRIBE_OPTIONAL_OR_ZERO_FILLED_NAMED_FIELD_OF_CLASS

#define DESCRIBE_OPTIONAL_OR_ZERO_FILLED_NAMED_FIELD_OF_CLASS (   group,
  shortName,
  n,
  t,
  className 
)    { __ZERO_FILL_BIT | (group), SharedMemoryVariable:: t, (uint16_t) RELATIVE_FIELD_OFFSET(className,n), sizeof(((className *)(0))-> n), {""}, { shortName } }

Convenience macro to describe an optional element of a structure that should be treated as zero-filled if not present.

Parameters
groupspecifies id for field group (1-63)
shortNametext label for field
nmember name of structure element
ttype of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc.
classNameis the name of the struct or class representing the record

◆ RELATIVE_FIELD_OFFSET

#define RELATIVE_FIELD_OFFSET (   className,
 
)    (reinterpret_cast<unsigned char *>(&(((className *)(8192))-> n)) - reinterpret_cast<unsigned char *>(8192))

Return relative offset of a field within a structure by pretending the structure was on a page-aligned boundary.

Parameters
classNamespecifies the type of the structure.
nnames the field of interest.
Returns
the offset of the field in number of bytes from the base of the object.

Typedef Documentation

◆ ConvertAndTransferFieldFP

typedef int(* ConvertAndTransferFieldFP) (const UniversalMetaData_FieldDescription *sourceDescr, const UniversalMetaData_FieldDescription *destDescr, const unsigned char *sourceRecord, unsigned char *destinationRecord, void *userData)

Protototype for metadata conversion callback.

Parameters
sourceDescrpoints to the description of the incoming field. If null, the end of the record is being announced.
destDescrpoints to the description of the corresponding outgoing field. If null, there is no field in the output record corresponding to the field being delivered.
sourceRecordpoints to the base of the incoming record. If null, the source did not provide this optional field.
destinationRecordpoints to the base of the outgoing record.

NOTE: a call is made to announce every mandatory field described by the the source description, which allows the conversion routine to see fields that it has no desire to retain. A call can also be made to announce the description of fields from optional groups that are not present. Normally an optional field is not announced if it was not present in the source record, but a field can be tagged to always be announced. In those situations where the field was not provided in the source, the sourceRecord will be null. Typically the conversion routine would zero-fill the destination field.

Return values
0field was not handled
1field was processed assigned.

Function Documentation

◆ defaultConvertAndTransferField()

◆ inspectMetaDataHeaderInFile()

int inspectMetaDataHeaderInFile ( struct UniversalMetaData_ReferenceFileHeader hdr,
const char *  fileName 
)

Retrieve the meta data file header from a file.

Parameters
hdrpoints to the meta data header structure to be populated.
fileNamespecifies the file to be accessed.
Return values
0indicates the contents were retrieved successfully.
-1indicates the data could not be retrieved.

NOTE: a successful read of the data does not imply that the file really held the expected content. The contents of the magicNumber field should always be checked for validity before referencing the remaining fields.

◆ loadAndConvertMetaData()

template<typename TO_FORMAT , typename FROM_FORMAT = GENERIC_META_RECORD>
TO_FORMAT* loadAndConvertMetaData ( const char *  fileName,
uint32_t *  recTotal,
ConvertAndTransferFieldFP  transferFunction = defaultConvertAndTransferField,
void *  userData = nullptr 
)

Load an existing metadata file and process the records. Normally this is used to convert from one format into another, but this is not required.

This function is templated by two parameters that indicate instances of MetaDataLoaderForFormat<>. The optional FROM_FORMAT is used to specify the expected magic number; it defaults to GENERIC_META_RECORD, which is designed to match any incoming file. When feasible, the correct FROM_FORMAT should be provided to obtain the safety of verifying that the expected magic number was present in the header.

The TO_FORMAT specifies the format of the target records. If no actual transfer of data is to be performed, the GENERIC_META_RECORD structure can be specified. This is commonly done when the result is variable length records, like those generated by a pretty-printer.

Parameters
fileNamespecifies the file containing the meta data.
recTotalspecifies a pointer to the location into which the total number of records processed will be stored before the routine returns.
transferFunctionspecifies the callback function to be invoked on each meta data record.
userDataspecifies optional user-provided data that will be passed onto the callback function. This is normally used to provide state between invocations.
Returns
A pointer to an array of TO_FORMAT records is returned. The caller should eventually recover the storage by doing a delete[].
Return values
nullptrindicates an error occurred, usually due to the file not being opened successfully.
Note
Field names are treated in a case-insensitive way.

References UniversalMetaData_ReferenceFileHeader::fieldDescriptionLength, UniversalMetaData_FieldDescription::fieldName, UniversalMetaData_ReferenceRecordHeader::fieldsPresentMask, UniversalMetaData_ReferenceFileHeader::headerLength, MetaDataLoaderForFormat< RECORD_CLASS >::loadMetaDataHeader(), UniversalMetaData_ReferenceFileHeader::metaRecordLength, OME_EXPECT_TRUE, UniversalMetaData_ReferenceFileHeader::totalFields, UniversalMetaData_ReferenceRecordHeader::totalRecordLength, and UniversalMetaData_ReferenceFileHeader::totalRecords.

◆ writeUniversalMetaDataMetaDataToFile()

int64_t writeUniversalMetaDataMetaDataToFile ( const uint32_t  fieldTotal,
const UniversalMetaData_FieldDescription fieldDescTbl,
const char *  magicNumber,
const char *  fileName,
const uint32_t  totalRecords,
const void **  tableBase,
const uint32_t  outputRecordLength 
)

Generic routine to write a meta data description file.

Parameters
fieldTotalindicates the total fields per record.
fieldDescTblpoints to a table of field description records
magicNumberpoints to the data which will identify the format of the file.
fileNameis a path that names the file to be created.
totalRecordsindicates the total number of product records to be output.
tableBasepoints to the base of the product record table.
outputRecordLengthindicates the length of the product record.
Returns
the total number of bytes written is returned.
Return values
-1indicates the file could not be created

NOTE: a filename qualified by the process id is created first, then renamed in an atomic step to the desired output file name. This prevents two distinct processes from writing the same file simultaneously and corrupting it. Instead, the content from the one who finishes last will be retained.

References UniversalMetaData_ReferenceFileHeader::fieldDescriptionLength, UniversalMetaData_ReferenceFileHeader::headerLength, LOG_CERR, LOG_ENDLINE, UniversalMetaData_ReferenceFileHeader::magicNumber, UniversalMetaData_ReferenceFileHeader::metaRecordLength, NULL, UniversalMetaData_ReferenceFileHeader::totalFields, UniversalMetaData_ReferenceRecordHeader::totalRecordLength, and UniversalMetaData_ReferenceFileHeader::totalRecords.

Referenced by MetaDataLoaderForFormat< RECORD_CLASS >::dumpMetaDataToFile().

Generated: Tue Jul 28 2020 16:03:26
Support Information