Skip to main content

ObjectAPI IDL

The ObjectAPI IDL can be used in parallel to the ObjectAPI JSON Schema. In fact the IDL is transformed to the JSON schema and then processed by the same tools.

Vice versa the JSON schema can be transformed to the IDL.

The IDL does more look like an actual developer language. It is more verbose and more powerful. It allows to define more complex types and to define more complex APIs.

module demo 1.0

// Counter is a simple counter object
interface Counter {
// count is the current counter value
count: int
// increment the count property by step
increment(int step)
// decrement the count property by step
decrement(int step)
}

Interfaces

An interface defines a set of properties, operations and signals.

interface name {
`prop-name` : type // property
`method-name` ( params ): `type` // operation
signal `signal-name` ( params ) // signal
}

A type can be either a primitive type or a complex type. A complex type can be a structure, enumeration or another interface.

A primitive type can be one of the following:

  • bool : boolean value
  • int, int32, int64 : integer value
  • float, float32, float64 : floating point value
  • string : string value

A complex type can be one of the following:

  • name of an interface
  • name of an enumeration
  • name of a structure

To define arrays of a type just append the [] to the type.

struct Struct1 {}

interface Demo {
propString: string
propStringArray: string[]
propStruct: Struct1
}
tip

Currently we do not support importing other modules. This is planned for a future version.

Structures

A data structure is a message which can be used to send complex information between objects. A structure is defined as follows:

struct name {
fieldName : type
}

Enumerations

An enumeration is a set of named values. An enumeration is defined as follows:

enum Enum1 {
Value1 = 0
Value2 = 1
Value3 = 2
}

A value can also be a hex number in the format of 0x2. If there is no value specified the next value is used.

Example

Here is a complete example:

module demo 1.0

interface Radio {
// frequency is the current frequency in MHz
frequency: float
// stations is a list of stations
stations: Station[]
// if enabled automatically tunes to the next station
autoTune: bool
// scan for stations
scan()
// tune to a specific frequency
tuneFrequency(float frequency)
// tune to a specific station
tuneStation(stationId: int)
// signal emitted when a new station is found
signal stationFound(stationId: int)
}

struct Station {
// id is the station id
id: int
// name of the station
name: string
// short name of the station
shortName: string
// frequency in MHz
frequency: float
// artwork url
artwork: string
// category of the content
category: Category
}

enum Category {
News = 0
Music = 1
Talk = 2
}

Our ApiGear tooling can create code in different languages. For example in C++ this would look like (simplified):

class Radio {
public:
// scan for stations
void scan();
// tune to a specific frequency
void tuneFrequency(float frequency);
// tune to a specific station
void tuneStation(int stationId);
// signal emitted when a new station is found
void onStationFound(function<void(int stationId)> callback);
public:
// frequency is the current frequency in MHz
float frequency;
// stations is a list of stations
std::vector<Station> stations;
// if enabled automatically tunes to the next station
bool autoTune;
};

struct Station {
// id is the station id
int id;
// name of the station
std::string name;
// short name of the station
std::string shortName;
// frequency in MHz
float frequency;
// artwork url
std::string artwork;
// category of the content
Category category;
};