Files
openvehicle-api/export/interfaces/core_idl.idl
2026-01-16 11:40:02 +01:00

651 lines
28 KiB
Plaintext

/**
* @file core_idl.idl
* @brief This file provides all interface definitions for generator of the IDL compiler as part of the core SDV framework.
* @version 0.1
* @date 2023.06.29
* @author erik.verhoeven@zf.com
* @copyright Copyright ZF Friedrichshaven AG (c) 2022-2025
*/
#include "core.idl"
#include "mem.idl"
/**
* @brief Software Defined Vehicle framework.
*/
module sdv
{
/**
* @brief IDL features.
*/
module idl
{
/**
* @brief Compilation error.
*/
exception XCompileError
{
u8string ssReason; ///< Explanation of the compilation error.
u8string ssFile; ///< Path to the file causing the compilation error.
uint32 uiLine; ///< Line in the source file that contains the error (starts at 1).
uint32 uiCol; ///< Column in the source file that contains the error (starts at 1).
u8string ssToken; ///< Token that caused the error.
u8string ssLine; ///< Source code line that contains the error.
};
const u8string ssOptionDevEnvDir = u8"DevEnvDir"; ///< The installation directory of the compiler.
const u8string ssOptionOutDir = u8"OutDir"; ///< Path to the output file directory. Default "." - relative to the file path.
const u8string ssOptionFilename = u8"Filename"; ///< Name of the input file.
const u8string ssOptionFilePath = u8"FilePath"; ///< Path to the input file.
const u8string ssOptionCodeGen = u8"CodeGen"; ///< List of code generators
/**
* @brief Compiler option access.
*/
interface ICompilerOption
{
/**
* @brief Get the compiler option.
* @param[in] rssOption Reference to the string containing the name of the option to retrieve.
* @return The requested compiler option (if available).
*/
u8string GetOption(in u8string rssOption) const;
/**
* @brief Get the amount of option values.
* @param[in] rssOption Reference to the string containing the name of the option to retrieve.
* @return The amount of option values.
*/
uint32 GetOptionCnt(in u8string rssOption) const;
/**
* @brief Get the compiler option.
* @param[in] rssOption Reference to the string containing the name of the option to retrieve.
* @param[in] uiIndex The index of the option value.
* @return The requested compiler option value.
*/
u8string GetOptionN(in u8string rssOption, in uint32 uiIndex) const;
};
/**
* @brief Compiler information access.
*/
interface ICompilerInfo
{
/**
* @brief Get the path of the processed file.
* @return The path string.
*/
u8string GetFilePath() const;
/**
* @brief Return the path to the output directory.
* @return The directory string.
*/
u8string GetOutputDir() const;
};
/**
* @brief The entity type.
* @remarks Const entities, declaration entities and typedef entities return the base type of the entity they declare/define.
*/
enum EEntityType : uint32
{
type_unknown, ///< Unknown entity type
type_variable, ///< Variable entity type
type_enum, ///< Enum entity type
type_struct, ///< Struct entity type
type_union, ///< Union entity type
type_module, ///< Module entity type
type_interface, ///< Interface entity type
type_exception, ///< Interface entity type
type_attribute, ///< Attribute entity type
type_operation, ///< Operation entity type
type_parameter, ///< Parameter entity type
type_enum_entry, ///< Enum entry entity type
type_case_entry, ///< Case entry entity type
type_switch_variable, ///< Switch variable entity type (used by unions)
type_typedef, ///< Typedef entity type
type_meta, ///< Meta data entity type
};
/**
* @brief The entity declaration type.
*/
enum EDeclType : uint32
{
decltype_unknown, ///< Unknown type
decltype_short, ///< Integer type (int16_t)
decltype_long, ///< Integer type (int32_t)
decltype_long_long, ///< Integer type (int64_t)
decltype_octet, ///< Octet type (uint8_t)
decltype_unsigned_short, ///< Integer type (uint16_t)
decltype_unsigned_long, ///< Integer type (uint32)
decltype_unsigned_long_long, ///< Integer type (uint64_t)
decltype_float, ///< Floating point type
decltype_double, ///< Floating point type
decltype_long_double, ///< Floating point type
decltype_fixed, ///< Fixed point templated type
decltype_char, ///< Character type (int8_t)
decltype_char16, ///< UTF-16 character
decltype_char32, ///< UTF-32 character
decltype_wchar, ///< Character type
decltype_boolean, ///< Boolean type
decltype_native, ///< Native type
decltype_string, ///< ASCII templated string type
decltype_u8string, ///< UTF-8 templated string type
decltype_u16string, ///< UTF-16 templated string type
decltype_u32string, ///< UTF-32 templated string type
decltype_wstring, ///< Wide templated string type
decltype_enum, ///< Enum type
decltype_struct, ///< Struct type
decltype_union, ///< Union type
decltype_module, ///< Module type
decltype_interface, ///< Interface type (not used in declarations)
decltype_exception, ///< Interface type (not used in declarations)
decltype_attribute, ///< Attribute type (not used in declarations)
decltype_operation, ///< Operation type (not used in declarations)
decltype_parameter, ///< Parameter type (only for operations)
decltype_enum_entry, ///< Enum entry type (only for enums)
decltype_case_entry, ///< Case entry type (only for unions)
decltype_typedef, ///< Typedef type
decltype_void, ///< Void type (only for operations)
decltype_meta, ///< Meta data type
decltype_pointer, ///< Pointer templated data type
decltype_sequence, ///< Sequence templated data type
decltype_map, ///< Map templated data type
decltype_bitset, ///< Bitset data type
decltype_bitfield, ///< Bitfield templated data type
decltype_bitmask, ///< Bitmask data type
decltype_any, ///< Any composite data type
decltype_interface_id, ///< Interface ID data type
decltype_interface_type, ///< Interface data type
decltype_exception_id, ///< Exception ID data type
};
/**
* @brief Entity base information interface.
*/
interface IEntityInfo
{
/**
* @brief Get the type of the entity. Default type is EEntityType::type_unknown.
* @return Returns the type of the entity.
*/
EEntityType GetType() const;
/**
* @brief Get the name of the entity.
* @return Returns the name string.
*/
u8string GetName() const;
/**
* @brief Get the scoped name of the entity (including the modules separated by the scope separator).
* @details The scoped name is composed of the entities of the parents separated by the scope operator '::'. For
* members of a compound entity (struct, union), the separation is done through the member operator '.'.
* @return The scoped name build from the entities of the parents separated by '::'. An empty name means global
* scope.
*/
u8string GetScopedName() const;
/**
* @brief Is the entity defined as (forward) declaration only?
* @return Returns 'true' when the entity is defined as forward declaration; otherwise returns 'false'.
*/
boolean ForwardDeclaration() const;
/**
* @brief Get the entity ID. This ID is a hash value composed from its definition and all declarative members not
* including const values. The ID can be used to uniquely identify the entity (e.g. as interface ID or exception ID).
* @return The ID of the entity.
*/
uint64 GetId() const;
/**
* @brief Get the parent entity of this entity.
* @return Returns an interface to the parent entity or NULL when this is the root parent (when there is no parent).
*/
IInterfaceAccess GetParent() const;
};
/**
* @brief Iterate through a vector of entities.
*/
interface IEntityIterator
{
/**
* @brief Get amount of entities.
* @return Returns the amount of entities available to this iterator.
*/
uint32 GetCount() const;
/**
* @brief Get entity at supplied index.
* @param[in] uiIndex The index to get the entity for.
* @return The entity at the index or NULL when there is no entity at this index.
*/
IInterfaceAccess GetEntityByIndex(in uint32 uiIndex);
};
/**
* @brief Context information interface.
*/
interface IEntityContext
{
/**
* @brief The location of the parsed file.
*/
enum ELocation : uint32
{
source, ///< Source code or source file.
local_include, ///< Local include file.
global_include ///< Global include file.
};
/**
* @brief Get the location.
* @return Returns context location.
*/
ELocation GetLocation() const;
/**
* @brief Get the path to the file.
* @return Returns the source path string.
*/
u8string GetSourcePath() const;
/**
* @brief Get the position in the file.
* @remarks Not all entities have a position. If no position is available, the position return value has the
* value 0.
* @param[out] ruiLineBegin Reference to the variable receiving the line number of the entity beginning.
* @param[out] ruiColBegin Reference to the variable receiving the column number of the entity beginning.
* @param[out] ruiLineEnd Reference to the variable receiving the line number of the entity ending.
* @param[out] ruiColEnd Reference to the variable receiving the column number of the entity ending.
*/
void GetPosition(out uint32 ruiLineBegin, out uint32 ruiColBegin, out uint32 ruiLineEnd, out uint32 ruiColEnd);
};
/**
* @brief Meta information interface. Exposed by the meta entity.
*/
interface IMetaEntity
{
/**
* @brief Token meta type (valid when token is a meta token).
*/
enum EType : uint32
{
include_local = 10, ///< Local include file
include_global = 11, ///< Global include file
define = 20, ///< Definition
undef = 21, ///< Remove definition
verbatim = 100, ///< Verbatim text to be inserted in the generated code
};
/**
* @brief Get the meta data type.
* @return Returns the meta type.
*/
EType GetMetaType() const;
/**
* @brief Get the meta data content.
* @return Returns a string object.
*/
u8string GetContent() const;
};
/**
* @brief Comment interface.
*/
interface IEntityComments
{
/**
* @brief Comment mask
*/
enum ECommentMask : uint32
{
c_style_javadoc = 0x40001000, ///< Comment of the form "/** ... */"
c_style_javadoc_post = 0x40201000, ///< Comment of the form "/**< ... */"
c_style_qt = 0x40002000, ///< Comment of the form "/*! ... */"
c_style_qt_post = 0x40202000, ///< Comment of the form "/*!< ... */"
c_style = 0x40000000, ///< Comment of the form "/* ... */"
cpp_style_javadoc = 0x80001000, ///< Comment of the form "/// ..."
cpp_style_javadoc_post = 0x80201000, ///< Comment of the form "///< ..."
cpp_style_qt = 0x80002000, ///< Comment of the form "//! ..."
cpp_style_qt_post = 0x80202000, ///< Comment of the form "///< ..."
cpp_style = 0x80000000, ///< Comment of the form "// ..."
loc_succeeding = 0x00200000, ///< Comment location is succeeding statement
format_javadoc = 0x00001000, ///< Comment using javadoc form
format_qt = 0x00002000, ///< Comment using QT form
format_mask = 0x0000f000, ///< Comment formatting mask
};
/**
* @brief Get the comment lines for this entity as one string.
* @remarks For c-style multi-line comments, the indentation and additional asterisk character at the beginning of
* each line is removed.
* @param[out] ruiFlags Reference to the variable receiving the comment flags (a bitmask combination of
* sdv::idl::IEntityComments::ECommentMask).
* @return Returns the comment string. If the comment contains multiple lines, each line is ending with a newline.
*/
u8string GetComments(out uint32 ruiFlags) const;
};
/**
* @brief Entity definition information interface.
*/
interface IDefinitionEntity
{
/**
* @brief Does the entity have an unnamed definition.
* @return Returns 'true' when the entity has an unnamed definition; otherwise returns 'false'.
*/
boolean IsUnnamed() const;
/**
* @brief Get child entity iterator if children are available and supported by the definition.
* @return Returns a pointer to the child entity iterator or NULL when not available.
*/
IEntityIterator GetChildren();
/**
* @brief Get inheritance entity iterator if the definition was inheriting from other entities.
* @return Returns a pointer to the inheritance entity iterator or NULL when not available.
*/
IEntityIterator GetInheritance();
};
/**
* @brief Entities declared in a forward declaration expose this interface.
*/
interface IForwardDeclarationEntity
{
/**
* @brief Get access to the actual declaration (if there is one).
* @return Pointer to the interface of the entity definition or NULL when there is no definition.
*/
IInterfaceAccess GetEntity();
};
/**
* @brief Declaration type interface containing the base type, type string as defined in the code as well as the
* definition object interface and template parameters.
*/
interface IDeclarationType
{
/**
* @brief Return the base type.
* @details The bse type might be a templated type (string, sequence, map, etc.) which means that additional
* information is needed. Furthermore, the type might be a complex type (struct, union, enum) or a typedef. In these
* cases the type definition interface is available.
* @return The base type of this type.
*/
EDeclType GetBaseType() const;
/**
* @brief Return the string that described the type in the code.
* @return The type string.
*/
u8string GetTypeString() const;
/**
* @brief Return the type definition for complex types or typedefs.
* @return Pointer to the interface representing the type definition. Will be NULL for all other types.
*/
IInterfaceAccess GetTypeDefinition() const;
/**
* @brief Fixed length parameter for some templated types.
* @details Fixed length template parameter for "fixed", "string", "sequence", "pointer", "map" and "bitfields".
* When not compulsory (for "fixed", "string", "sequence", "pointer" and "map") could be 0 to indicate a dynamic
* length (or defined over assignment with "fixed"). Bitfields allow a length between 1 and 64 bits.
* @return Returns the fixed length for some templated types or 0 for all other other types.
*/
uint32 GetFixedLength() const;
/**
* @brief The amount of decimals of the "fixed" data type. Must be equal or smaller than the fixed length.
* @return The amount of decimals for the "fixed" data type or 0 for all other data types.
*/
uint32 GetDecimals() const;
/**
* @brief The value type template parameter for the "sequence", "pointer", "map" and "bitfield" data types.
* @return Interface to the value data type for some templated types of NULL for all other types.
*/
IInterfaceAccess GetValueType() const;
/**
* @brief The key type template parameter for the "map" data type.
* @return Interface to the key data type for the "map" type of NULL for all other types.
*/
IInterfaceAccess GetKeyType() const;
};
/**
* @brief Array dimension definition.
* @details Multi-dimensional arrays are possible. Each dimension is defined between square-brackets
* (eg. var[a][b][]). An unbound dimension can only occur as the last dimension. Fixed-bound dimensions can be
* specified using a constant expression. If variables are used in the constant expression, they need to be in
* scope of the array variable.
*/
struct SArrayDimension
{
/**
* @brief Dimension type.
*/
enum EDimensionType : uint32
{
bound = 0, ///< Bound array
unbound = 2, ///< Unbound array
} eType; ///< The dimension type
u8string ssExpression; ///< Expression defining the dimension size either as constant- or as runtime-expression.
};
/**
* @brief Declaration entity information interface.
*/
interface IDeclarationEntity
{
/**
* @brief Get declaration type.
* @return Interface to the declaration type object.
*/
IInterfaceAccess GetDeclarationType() const;
/**
* @brief Is the entity readonly?
* @return Returns 'true' when the declaration is defined as readonly declaration; otherwise returns 'false'.
*/
boolean IsReadOnly() const;
/**
* @brief Is the entity anonymous when used in a struct/union (unnamed and not declared)?
* @details Returns whether the entity is anonymous when used in a struct/union. This allows its members to appear
* directly as members within the struct.
* @return Returns 'true' when the declaration is defined as anonymous declaration; otherwise returns 'false'.
*/
boolean IsAnonymous() const;
/**
* @brief Has array?
* @return Returns 'true' when the declaration is part of an array; otherwise returns 'false'.
*/
boolean HasArray() const;
/**
* @brief Get the array dimensions (if there are any).
* @return Smart pointer to the sequence of array dimensions.
*/
sequence<SArrayDimension> GetArrayDimensions() const;
/**
* @brief Has assignment?
* @return Returns 'true' when the declaration is followed by an assignment; otherwise returns 'false'.
*/
boolean HasAssignment() const;
/**
* @brief Get assignment string.
* @details The assignment can be an algebraic expression composed from constants and variables. If the assignment is an
* array, the expression is composed like this: {{expr1},{expr2},{expr...}}
* @return Returns the assignment string when available.
*/
u8string GetAssignment() const;
};
/**
* @brief Interface entity
*/
interface IInterfaceEntity
{
/**
* @brief Is this interface local?
* @details When set, the interface is defined as local and not intended to be marshalled.
* @return Returns 'true' when the interface is defined as local interface; otherwise returns 'false'.
*/
boolean IsLocal() const;
};
/**
* @brief Operation entity
*/
interface IOperationEntity
{
/**
* @brief Get parameter entity iterator if the definition has any parameters.
* @return Returns a pointer to the parameter entity iterator or NULL when not available.
*/
IEntityIterator GetParameters();
/**
* @brief Get the list of possible exceptions that might be fired for this operation.
* @return Returns a pointer to the exception entity iterator or NULL when not available.
*/
IEntityIterator GetExceptions();
};
/**
* @brief Attribute entity
*/
interface IAttributeEntity
{
/**
* @brief Get the list of possible exceptions that might be fired during a read operation.
* @return Returns a pointer to the exception entity iterator or NULL when not available.
*/
IEntityIterator GetReadExceptions();
/**
* @brief Get the list of possible exceptions that might be fired during a write operation.
* @return Returns a pointer to the exception entity iterator or NULL when not available.
*/
IEntityIterator GetWriteExceptions();
};
/**
* @brief Parameter entity information interface.
*/
interface IParameterEntity
{
/**
* @brief Parameter direction enumeration
*/
enum EParameterDirection : uint32
{
unknown, ///< The parameter direction is not known.
input, ///< The parameter is defined as input parameter.
output, ///< The parameter is defined as output parameter.
in_out, ///< The parameter is defined as input and output parameter.
};
/**
* @brief Get the parameter direction.
* @return Returns the parameter direction.
*/
EParameterDirection GetDirection() const;
};
/**
* @brief Enum entity information interface.
*/
interface IEnumEntity
{
/**
* @brief Get the enumerator base type.
* @param[out] reType Reference to the declaration type. The type if EEntityType::type_unknown if not available.
* @param[out] rpType Reference to the interface pointer if the type is a complex type. Otherwise is NULL.
*/
void GetBaseType(out EDeclType reType, out IInterfaceAccess rpType) const;
};
/**
* @brief Union entity information interface.
*/
interface IUnionEntity
{
/**
* @brief The interpretation of the switch case.
*/
enum ESwitchInterpret : uint32
{
switch_variable, ///< The switch case is determined by a variable of the parent struct.
switch_type, ///< The switch case is determined by the value of a type.
};
/**
* @brief Return the switch interpretation.
* @return The interpretation of the switch case of this union.
*/
ESwitchInterpret GetSwitchInterpretation() const;
/**
* @brief Return type information for the switch case. If the switch case is type base, this is the type information
* that is used to select. If the switch case is variable based, this is the type of the variable.
* @param[out] reType Reference to the declaration type (either enum or an integral type).
* @param[out] rpType Reference to the type entity if existing.
*/
void GetSwitchType(out EDeclType reType, out IInterfaceAccess rpType) const;
/**
* @brief Get the switch variable information if the switch case is variable based. Will be empty/NULL when the switch
* case is type based.
* @param[out] rssVarStr Reference to the string receiving the exact scoped declaration name of the switch variable if
* the interpretation is variable based. The variable name uses the scope separator '::' to define the common parent
* definition and the member separator '.' to define the variable declaration as member from the common parent.
* @param[out] rpVarEntity Reference to the variable entity if the interpretation is variable based.
* @param[out] rpVarContainer Reference to the variable entity of the container of both the switch variable and the
* union.
*/
void GetSwitchVar(out u8string rssVarStr, out IInterfaceAccess rpVarEntity,
out IInterfaceAccess rpVarContainer) const;
};
/**
* @brief Case entity information interface.
*/
interface ICaseEntity
{
/**
* @brief Get the case label string. The case label string will be empty for the default case entry.
* @return Returns the label (of not default).
*/
u8string GetLabel() const;
/**
* @brief Is this case entry the default entry.
* @return Return whether the case entry is the default entry.
*/
boolean IsDefault() const;
};
}; // module idl
}; // module sdv