Automatic Component Toolkit

Specification of the Interface Description Language of the Automatic Component Toolkit (ACT-IDL)

Version	1.5.0

Disclaimer

THESE MATERIALS ARE PROVIDED "AS IS." The contributors expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL ANY MEMBER BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Preface

Document Conventions

Except where otherwise noted, syntax descriptions are expressed in the ABNF format as defined in RFC 4234.

Glossary terms are formatted like this.

Syntax descriptions and code are formatted as Markdown code blocks.

Replaceable items, that is, an item intended to be replaced by a value, are formatted in monospace cursive type.

Notes are formatted as follows:

Note: This is a note.

Language Notes

In this specification, the words that are used to define the significance of each requirement are written in uppercase. These words are used in accordance with their definitions in RFC 2119, and their respective meanings are reproduced below:

MUST. This word, or the adjective "REQUIRED," means that the item is an absolute requirement of the specification.
SHOULD. This word, or the adjective "RECOMMENDED," means that there may exist valid reasons in particular circumstances to ignore this item, but the full implications should be understood and the case carefully weighed before choosing a different course.
MAY. This word, or the adjective "OPTIONAL," means that this item is truly optional.

Elements and types in the ACT-IDL

1. Component

Element <component> of type CT_Component

Attributes

Name	Type	Use	Default	Annotation
libraryname	ST_LibraryName	required		Specifies the name of the component. Can contain spaces.
namespace	ST_NameSpace	required		Specifies the namespace for the components's functionality.
copyright	xs:string	required		The legal copyright holder.
basename	ST_BaseName	required		The basename will be used as prefix for generated filenames and all sorts of identifiers in the generated source code.
version	ST_Version	required		The semantic version of this component.
year	ST_Year	optional	the current year	The year associcated with the copyright.
@anyAttribute

It is RECOMMENDED that components generated with ACT follow the semantic versioning scheme. The "version" attribute encodes the semantic version of this component. Major, Minor and Micro-version info MUST be included. Pre-release information and build information MAY be included.

The <component> element is the root element of a ACT-IDL file. There MUST be exactly one <component> element in a ACT-IDL file. A component MUST have exactly one child license element, one child bindings element, one child implementations element, one child errors element and one child global element.

The names of the <struct>-, <enum>-, <functiontype>- and <class>-elements MUST be unique within the <component>.

Note: Regarding the "uniqueness" of attributes of type xs:string. Within this specification strings are considered equal regardless of the case of the individual letters.

2. License

Element <license> of type CT_License

The <license> element contains a list of at least one child line element. The license lines will be included as comments at the start of all generated source code files.

3. Line

Element <line> of type CT_LicenseLine

Attributes

Name	Type	Use	Default	Annotation
value	xs:string	required		A line of the license.

4. Bindings

Element <bindings> of type CT_BindingList

The CT_BindingList type contains a list of binding elements. The <binding> elements in the <bindings> element determine the language bindings that will be generated.

5. Implementations

Element <implementations> of type CT_ImplementationsList

The CT_ImplementationsList type contains a list of implementation elements. The <implementation> elements in the <implementations> element determine the languages for which implementation stubs will be generated.

6. Export

Element <binding>

Element <implmentation>

of type CT_Export

Attributes

Name	Type	Use	Default	Annotation
language	ST_Language	required		The programming langugage of this export.
indentation	ST_Indentation	optional	4spaces	Which string should be used to denote a single level of indentation in the generated source code files.
stubidentifier	ST_StubIdentifier	optional	""	Generated sources files of this export will follow the naming schme "...${BaseName}_${stubidentifier}...". Only used in <implementation> right now.
classidentifier	ST_ClassIdentifier	optional	""	Generated classes of this export will follow the naming schme "...${ClassIdentifier}_${ClassName}...". The only binding that supports this are the C++-bindings.

7. Global

Element <global> of type CT_Global

Attributes

Name	Type	Use	Annotation
baseclassname	ST_Name	required	Specifies the name of a class that is the base class for all classes of the generated component.
releasemethod	ST_Name	required	Specifies the name of the method used to release a class instance owned by the generated component.
versionmethod	ST_Name	required	Specifies the name of the method used to obtain the major, minor and micro version of the component.
prereleasemethod	ST_Name	required	Specifies the name of the method used to obtain the prerelease information of the component.
buildinfomethod	ST_Name	required	Specifies the name of the method used to obtain the build information of the component.
errormethod	ST_Name	required	Specifies the name of the method used to query the last error that occured during the call of class's method.
journalmethod	ST_Name	optional	Specifies the name of the method used to set the journal file. If ommitted, journalling will not be built into the component.

The <global> element contains a list of method elements that define the exported global functions of the component. The names of the <method> elements MUST be unique within the <global> element.

The baseclassname-attribute must be the name of a <class> element within the components list of classes. This class will be the base class for all classes of the generated component.

The releasemethod-attribute must be the name of a <method> within the <global> element of a component that has exactly one parameter with type="class", class="BaseClass" and pass="in". The versionmethod-attribute must be the name of a <method> within the <global> element of a component that has exactly three parameters. The three parameters MUST be of type type="uint32" and pass="out". The prereleasemethod-attribute is optional an can be the name of a <method> within the <global> element of a component that has two parameters. The first parameter MUST be of type type="bool" and pass="return", the second parameter MUST be of type type="string" and pass="out". The buildinfomethod-attribute is optional an can be the name of a <method> within the <global> element of a component that has two parameters. The first parameter MUST be of type type="bool" and pass="return", the second parameter MUST be of type type="string" and pass="out".

The errormethod-attribute must be the name of a <method> within the <global> element of a method that has exactly three parameters:

type="class", class="$BASECLASSNAME" and pass="in", where "$BASECLASSNAME" is the value of the baseclassname attribute of the <global> element.
type="string" and pass="out": outputs the last error message
type="bool" and pass="return": returns the instance of the baseclass has an error.

If the journalmethod attribute is given, it must be the name of a <method> within the <global> element of a method that has exactly one parameter with type="string" and pass="in".

Note type="handle" is equivalent to type="class" for backwards compatibility. It will be removed in a later version.

8. Class

Element <class> of type CT_Class

Attributes

Name	Type	Use	Annotation
name	ST_Name	required	The name of this class.
parent	ST_Name	optional	The name of the parent class of this class.
description	ST_Description	optional	A description of this class.

The <class> element contains a list of method elements that define the exported member functions of this class. The names of the <method> elements MUST be unique in this list.

If the parent-attribute is empty, and the name of this class differs from the baseclassname-attribute of the <global> element, baseclassname will be considered as the parent class of this class.

A class MUST be defined in the list of <class> elements before it is used as parent-class of another class. This restiction rules out circular inheritance. Moreover, the default baseclassname MUST be defined as the first <class> within the IDL-file.

9. Function Type

Element <functiontype>

Element <method>

of Complex type CT_FunctionType

Attributes

Name	Type	Use	Default	Annotation
name	ST_Name	required		The name of this function type.
description	ST_Description	required		A description of this function type.

The CT_FunctionType-type describes the signature of a function in the interface. Each element of type CT_FunctionType contains a list of param elements. The names of the param in this list MUST be unique. This list MUST contain zero or one param-elements with the pass-value "return".

The <functiontype>-element can be used to define callback functions into the consumer's code.

10. Param

Element <param> of type CT_Param

Attributes

Name	Type	Use	Annotation
name	ST_Name	required	The name of this parameter.
description	ST_Description	required	A description of this parameter.
pass	ST_Pass	required	Specifies whether the parameter is passed "in", "out" or as "return"-value of the enclosing functiontype.
type	ST_Type	required	The type of this parameter.
class	ST_Name	optional	Required if the type is an ST_ComposedType

11. Enum

Element <enum> of type CT_Enum

Attributes

Name	Type	Use	Default	Annotation
name	ST_Name	required		The name of this Enumeration.

The <enum> element defines an enumerated type (see https://en.wikipedia.org/wiki/Enumerated_type), i.e. a set of named values.
It contains a list of at least one option element. The names as well as the values of the options in this list MUST be unique within a <enum> element.

12. Option

Element <option> of type CT_Option

Attributes

Name	Type	Use	Default	Annotation
name	ST_Name	required		The name of this option.
value	xs:nonNegativeInteger	required		The numerical value of this option.

13. Struct

Element <struct> of type CT_Struct

Attributes

Name	Type	Use	Default	Annotation
name	ST_Name	required		The name of this struct.

The <struct> element defines a composite data type (see https://en.wikipedia.org/wiki/Composite_data_type).
It contains a list of at least one member element. The names of the member elements MUST be unique within a struct element.

14. Member

Element <member> of type CT_Member

Attributes

Name	Type	Use	Default	Annotation
name	ST_Name	required		The name of this member.
type	ST_ScalarType	required		The scalar type of this member.
rows	xs:positiveInteger	optional	1	The number of rows of this member.
columns	xs:positiveInteger	optional	1	The number of columns of this member.

The <member> element defines a member (or "field") within a struct. Only ST_ScalarType is allowed within structs. By default, the member defines a single value of its type within the enclusing struct. One- or two-dimensional arrays of fixed size can be defined by setting the rows and colums attributes to the desired size of the array.

15. Errors

Element <errors> of type CT_ErrorList

The <errors> element contains a list of <error> elements. The names and codes of the <error> elements in this list MUST be unique within the <errors> element.

Each ACT-component MUST contain at least the following 8 error codes:

NOTIMPLEMENTED, INVALIDPARAM, INVALIDCAST, BUFFERTOOSMALL, GENERICEXCEPTION, COULDNOTLOADLIBRARY, COULDNOTFINDLIBRARYEXPORT, INCOMPATIBLEBINARYVERSION

16. Error

Element <error> of type CT_Error

Attributes

Name	Type	Use	Annotation
name	ST_ErrorName	required	The name of this error.
code	xs:positiveInteger	required	The numerical error code of this error.
description	ST_ErrorDescription	otpional	A short description of this error.

17. Simple Types

The simple types of this specification encode features, concepts, data types, and naming rules used in or required by programming languages.

For now, please look the up in the ACT.xsd.

17.1 Type

Supported types are:

bool: denotes a boolean value (true or false). Although this can be encoded in a single bit, the thin C89-layer APIs generated by ACT will use an unsigned 8 bit value (a uint8 in ACT terms) to encode a boolean value. A numerical value of 0 encodes false, all oher values encode true. Implementations and bindings should use the definition of a boolean value that is native to the respective language of the implementation or binding.
uint8, uint16, uint32, uint64: An unsigned integer vaules ranging from 0 - 2⁸-1, 0 - 2¹⁶-1, 0 - 2³²-1, 0 - 2⁶⁴-1, respectively.
int8, int16, int32, int64: A signed integer vaules ranging from -2⁷ - 2⁷-1, -2¹⁵ - 2¹⁵-1, -2³¹ - 2³¹-1, -2⁶³ - 2⁶³-1, respectively.
pointer: An address in memory without knowledge of the kind of data that resides there. In C++, this corresponds to a void*.
string denotes a null-terminated string. If a component requires arbitrary strings that can contain null-characters, one should use the type basicarray of class uint8.
single: Single precision floating point number.
double: Double precision floating point number.
struct: see 13. Struct
enum: see 11. Enum
basicarray: an array of ST_ScalarTypes
enumarray: an array of enums
structarray: an array of structs
handle: the identifier (address, unique identifier, hash, ...) of a class instance class instance
functiontype: see 9. Function Type

17.2 ScalarType

A subset of scalar or integral of ST_Type:

bool, uint8, uint16, uint32, uint64, int8, int16, int32, int64, single, double, pointer.

17.3 ComposedType

A subset of more complex types, or types composed of other ST_Types:

string, enum, basicarray, enumarray, structarray, handle, functiontype

Files

IDL.md

Latest commit

History

IDL.md

File metadata and controls

Automatic Component Toolkit

Specification of the Interface Description Language of the Automatic Component Toolkit (ACT-IDL)

Disclaimer

Table of Contents

Preface

Document Conventions

Language Notes

Elements and types in the ACT-IDL

1. Component

Attributes

2. License

3. Line

Attributes

4. Bindings

5. Implementations

6. Export

Attributes

7. Global

Attributes

8. Class

Attributes

9. Function Type

Attributes

10. Param

Attributes

11. Enum

Attributes

12. Option

Attributes

13. Struct

Attributes

14. Member

Attributes

15. Errors

16. Error

Attributes

17. Simple Types

17.1 Type

17.2 ScalarType

17.3 ComposedType

17.4 Name

17.5 Description

17.6 ErrorName

17.7 ErrorDescription

17.8 Pass

17.9 Language

17.10 Indentation

17.11 Year

17.12 Version

17.13 Stub Identifier

17.14 Class Identifier

17.16 NameSpace

17.15 Library Name

17.16 Base Name

Appendix A. XSD Schema of ACT-IDL

Appendix B. Example of ACT-IDL