Versioned Structs

Detailed Description

In the various interface and data structs used in the ARA API, callback pointers or data fields may be added in later revisions of the current API generation. Each of these extensible structs starts with a structSize data field that describes how much data is actually contained in the given instance of the struct, thus allowing to determine which of the additional features are supported by the other side. All struct members that are later additions will be marked with the macro ARA_ADDENDUM. Members that are not marked as addendum must always be present in the struct. Accordingly, the minimum value of structSize is the size of the struct in the first API revision. When creating such a struct in your code, the maximum value is the size of the struct in the current API revision used at compile time. When parsing a struct received from the other side, the value may be even larger since the other side may use an even later API revision.
Note that when implementing ARA, it is important not to directly use sizeof() when filling in the structSize values. If you later update to newer API headers, the values of sizeof() will change and your code thus will be broken until you've implemented all additions. Instead, use the ARA_IMPLEMENTED_STRUCT_SIZE macro or similar techniques added in the ARA C++ library dispatcher code, see there.

Macros

#define ARA_IMPLEMENTED_STRUCT_SIZE(StructType, memberName)   (offsetof(ARA::StructType, memberName) + sizeof(static_cast<ARA::StructType *> (nullptr)->memberName))
 Macro that calculates the proper value for the structSize field of a versioned struct based on which features are actually implemented by the code that provides the struct. This may be different from sizeof() whenever features are added in the API, but not yet implemented in the current code base. Only after adding that implementation, the memberName parameter provided to ARA_IMPLEMENTED_STRUCT_SIZE should be updated accordingly.
The ARA library C++ dispatchers implement a similar feature via templates, see ARA::SizedStruct<>.
 
#define ARA_IMPLEMENTS_FIELD(pointerToStruct, StructType, memberName)    ((pointerToStruct)->structSize > offsetof(ARA::StructType, memberName))
 Convenience macro to test if a field is present in a given struct.
The ARA library C++ dispatchers implement a similar feature via templates, see ARA::SizedStructPtr::implements<>().