FARGOS/VISTA Object Management Environment Core
..
|
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... | |
Facilities to read/write/transform self-describing meta data files.
#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.
n | member name of structure element |
t | type of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc. |
className | is the name of the struct or class representing the record |
#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.
shortName | text label for field; this is a text string. |
n | member name of structure element |
t | type of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc. |
className | is the name of the struct or class representing the record |
Field is declared to be member of group 1.
#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.
group | specifies id for field group (1-63) |
n | member name of structure element |
t | type of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc. |
className | is the name of the struct or class representing the record |
#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.
group | specifies id for field group (1-63) |
shortName | text label for field |
n | member name of structure element |
t | type of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc. |
className | is the name of the struct or class representing the record |
#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.
group | specifies id for field group (1-63) |
n | member name of structure element |
t | type of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc. |
className | is the name of the struct or class representing the record |
#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.
group | specifies id for field group (1-63) |
shortName | text label for field |
n | member name of structure element |
t | type of element from one of the SMV_TYPE SharedMemoryVariable enums, like SMV_TYPE_INT32, SMV_TYPE_FLOAT, etc. |
className | is the name of the struct or class representing the record |
#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.
className | specifies the type of the structure. |
n | names the field of interest. |
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.
sourceDescr | points to the description of the incoming field. If null, the end of the record is being announced. |
destDescr | points to the description of the corresponding outgoing field. If null, there is no field in the output record corresponding to the field being delivered. |
sourceRecord | points to the base of the incoming record. If null, the source did not provide this optional field. |
destinationRecord | points 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.
0 | field was not handled |
1 | field was processed assigned. |
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.
References fast_ascii_to_fixedpoint(), UniversalMetaData_FieldDescription::fieldLength, UniversalMetaData_FieldDescription::fieldOffset, UniversalMetaData_FieldDescription::fieldType, fixedpoint_to_ascii(), float_to_ascii(), htonl, int_to_ascii(), n4to_uint32(), OME_EXPECT_FALSE, OME_EXPECT_TRUE, powersOf10, VariableFixedPointValue::precision, SharedMemoryVariable::SMV_TYPE_DOUBLE, SharedMemoryVariable::SMV_TYPE_FIXED, SharedMemoryVariable::SMV_TYPE_FLOAT, SharedMemoryVariable::SMV_TYPE_INT32, SharedMemoryVariable::SMV_TYPE_INT64, SharedMemoryVariable::SMV_TYPE_STRING, SharedMemoryVariable::SMV_TYPE_TINY_STRING, SharedMemoryVariable::SMV_TYPE_UINT32, SharedMemoryVariable::SMV_TYPE_UINT64, SharedMemoryVariable::SMV_TYPE_UNSIGNED, uint_to_ascii(), and VariableFixedPointValue::value.
int inspectMetaDataHeaderInFile | ( | struct UniversalMetaData_ReferenceFileHeader * | hdr, |
const char * | fileName | ||
) |
Retrieve the meta data file header from a file.
hdr | points to the meta data header structure to be populated. |
fileName | specifies the file to be accessed. |
0 | indicates the contents were retrieved successfully. |
-1 | indicates 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.
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.
fileName | specifies the file containing the meta data. |
recTotal | specifies a pointer to the location into which the total number of records processed will be stored before the routine returns. |
transferFunction | specifies the callback function to be invoked on each meta data record. |
userData | specifies optional user-provided data that will be passed onto the callback function. This is normally used to provide state between invocations. |
nullptr | indicates an error occurred, usually due to the file not being opened successfully. |
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.
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.
fieldTotal | indicates the total fields per record. |
fieldDescTbl | points to a table of field description records |
magicNumber | points to the data which will identify the format of the file. |
fileName | is a path that names the file to be created. |
totalRecords | indicates the total number of product records to be output. |
tableBase | points to the base of the product record table. |
outputRecordLength | indicates the length of the product record. |
-1 | indicates 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 |