GTIRB  v1.10.4
GrammaTech Intermediate Representation for Binaries: C++ API
Files | Classes | Functions
AuxData

AuxData objects can be attached to the IR or individual Modules to store additional client-specific data in a portable way. More...

Files

file  AuxData.hpp
 Types and operations for auxiliary data.
 
file  AuxDataSchema.hpp
 Type schema for sanctioned AuxData types.
 

Classes

struct  gtirb::auxdata_traits< T, Enable >
 Provides type information and serialization functions for types which can be stored in AuxData. More...
 
struct  gtirb::is_mapping< T >
 Trait class that identifies whether T is a mapping container type. More...
 
struct  gtirb::is_sequence< T >
 Trait class that identifies whether T is a sequential container type. More...
 

Functions

static bool gtirb::auxdata_traits< T, Enable >::fromBytes (T &Object, FromByteRange &FBR)=delete
 Deserialize an object from a sequence of bytes. More...
 
static void gtirb::auxdata_traits< T, Enable >::toBytes (const T &Object, ToByteRange &TBR)=delete
 Serialize an object to a sequence of bytes. More...
 
static std::string gtirb::auxdata_traits< T, Enable >::type_name ()=delete
 String representation of the serialized type of T. More...
 

Detailed Description

AuxData objects can be attached to the IR or individual Modules to store additional client-specific data in a portable way.

AuxData can store the following types:

Supporting Additional Types

Support for additional containers can be added by specializing is_sequence or is_mapping. Once serialized, the data does not depend on any specific container type, and its contents can be deserialized into different containers of the same kind (e.g. std::list to std::vector).

Support for other types can be added by specializing auxdata_traits to provide serialization functions. However, AuxData containing these types will not be accessible to other clients which are not compiled with support for those types. It is preferable to store data using the basic types whenever possible, in order to maximize interoperability.

'Sanctioned' AuxData Tables

We specify a small number of standard AuxData table schemata to support interoperability. For details, see md_AuxData. C++ schemata for the sanctioned tables are present in AuxDataSchema.hpp.

Adding Custom AuxData Tables

Clients may add their own AuxData tables in the C++ API by defining their own schemata. Schemata should be defined by extending the gtirb::schema namespace. Each schema should be a struct declaring public members for the type's name and its C++ type. One can follow the model provided by the schemata in AuxDataSchema.hpp.

Serialization Format

AuxData is serialized by packing the contents into a byte array, which is stored in a protobuf message along with a string which identifies the type in a portable fashion.

Fixed-size types such as integers, Addr, etc are packed by swapping their bytes to little-endian order and writing them directly to the byte array. Containers first write out the number of elements (as a uint64_t), then write each element one after another. Tuples are similar but omit the size, since it can be inferred from the type.

Function Documentation

◆ fromBytes()

template<class T , class Enable = void>
static bool gtirb::auxdata_traits< T, Enable >::fromBytes ( T &  Object,
FromByteRange &  FBR 
)
staticdelete

#include <AuxData.hpp>

Deserialize an object from a sequence of bytes.

Parameters
ObjectThe object to deserialize.
FBRRead bytes from here.
Returns
True/false dependending on if the bytes were deserialized successfully.

◆ toBytes()

template<class T , class Enable = void>
static void gtirb::auxdata_traits< T, Enable >::toBytes ( const T &  Object,
ToByteRange &  TBR 
)
staticdelete

#include <AuxData.hpp>

Serialize an object to a sequence of bytes.

Parameters
ObjectThe object to serialize.
TBRStore byte sequence here.

◆ type_name()

template<class T , class Enable = void>
static std::string gtirb::auxdata_traits< T, Enable >::type_name ( )
staticdelete

#include <AuxData.hpp>

String representation of the serialized type of T.

This identifier is portable and independent of the specific container types. Integral types are represented with an exact size (e.g. "uint32_t"). Sequential containers are represented as "sequence<...>", and mapping containers are represented as "mapping<...>".