ARA implements two patterns for its ongoing evolution of the API: incremental, fully-backwards compatible additions by appending features to it versioned structs, and major, potentially incompatible updates through its API generations.
Subpages | |
| API Generations | |
| While purely additive features can be handled through ARA's versioned structs, ARA API generations allow for non-backwards-compatible, fundamental API changes. For hosts that rely on a certain minimum ARA feature set provided by the plug-ins, it also offers a convenient way to filter incompatible plug-ins. Plug-ins on the other hand can use the API generation chosen by the host to optimize their feature set for the given environment, such as disabling potentially costly fallback code required for older hosts when running in a modern host. | |
| Versioned Structs | |
| 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. | |