Genesis Project
This document is part of the genesis project. See the project homepage at for more information. This document is (or was) hosted by SourceForge.

Object Interface Definition Language (gs6854-10)

Simon Ruoss

Attention: The document is only a draft and GS6854-10 might change.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Revision History
Revision 02004-01-18

Initial Version

Revision 12004-02-26

Renamed "usage" to "description". Added "Object" data type. Added signals.


The OIDL (Object Interface Definition Language) is an XML (cause: easy parsing and human readable) file. You can use the OIDL to document your objects or an OIDL-processor can generate language interfaces (e.g. a C++ interface). OIDL is very basic, it doesn't support structs and arrays - it's only for basic system-objects; a more complex interface definition language should follow.

Sample OIDL File

Example 1. OIDL Example

<?xml version="1.0" encoding="UTF-8"?>

<oidl version="0">
    <name value="HelloWorldObj"/>
      <p>Use this object like this...</p>

    <name value="ConsoleOutputError"/>
    <cid value="0x0015">

    <param name="errorCode" type="Int8"/>
    <param name="fatalError" type="Boolean"/>

    <name value="SayHello"/>
    <cid value="0x0020"/>
      <p>Call this <b>method</b> and it will print
      <li>Hello World</li>.</p>

    <param name="useGerman" type="Boolean"/>

      <param name="printedText" type="StringUTF8"/>
      <param name="usedGerman" type="Boolean"/>

    <throws value="ConsoleOutputError"/>

    <name value="MySignal"/>
    <range from="0x15" to="0x15"/>
      <p>This is a fake-signal</p>


OIDL Documentation


The header (head) has at least:

  • a name (name/value) which gives the object a name. See Names

The header may also have:

  • a description (description) containing Simple HTML Text. Use this tag to describe how to use the object and what it's used for


Methods (method) have at least:

  • a name (name/value). See Names section for legal names.

  • a call-id (cid/value). See Call-IDs section for legal call-IDs.

Methods may have:

  • parameters (param). See Parameters section for more information.

  • return values (returns). See Parameters

  • exceptions (throws). See Exceptions

  • a description (description) which may contain Simple HTML Text. This tag contains a short text how to use the method and what the method is for.


Exceptions (exception) have at least:

  • a name (name/value). See Names

  • a call-id (cid/value). See Call-IDs

Exceptions may have:


Signals (signal) have at least:

  • a name (name/value)

  • a range (range/from and range/to). If range/from is not equal to range/to, then the signal-tag specifies a signal-array (more than one signal).

Signals may have:

Further Information


Names (e.g. used in param/name, method/name/value or exception/name/value) follow these rules: Use a short name (max 32 chars), no spaces or characters other than [a...z], [A...Z], [0...9], [_], [-] are allowed. A literal must begin with a letter (I suggest a capital letter).


Call-IDs can be decimal or hexadecimal numbers from 0 to 2^16-1. If you decide to use hexadecimal numbers, use the prefix "0x". Valid and invalid call-IDs are (some examples):

Example 2. Valid and invalid Call-IDs

0x0000A valid hexadecimal call-id (decimal = 0)
0x00FFA valid hexadecimal call-id (decimal = 255)
2548A valid decimal call-id
0x58G5FAn invalid call-id. Number is too large and G is an invalid hexadecimal digit.

Simple-HTML Text

Simple HTML text supports the HTML tags p (paragraph), b (bold), samp (output from programs, scripts, etc.), ul (unordered list), li (list item) and a (anchor/link). Simple HTML text always begins with the p tag (the p tag is the root tag/top-level tag).


Parameters (param) must have:

  • a name (name). See Names section

  • a type (type). See Types section for more info



Figure 1. Available Integer Types




OIDL supports signed and unsigned integers from 8 up to 64bit. Boolean is an 8bit unsigned integer (0 means false, !0 means true). Object is an object and is the same as the oid_t in buran.

Floating-Point Numbers

Figure 2. Floating Point Numbers


Float32 (single), Float64 (double) and Float128 (quadruple) comply with IEEE 754 standart.

Characters and Strings

Figure 3. Chars and Strings


Char is an extended ASCII (8bit) character. String is a string of Char (String is variable-length).

CharUTF8 is a UTF-8 character (variable-length). StringUTF8 is a string of CharUTF8 (variable-length).


Figure 4. Data Type


This is a variable-length type that can contain everything.

OIDL and Buran (gs6854-01)

How to call a method

Follow these steps to call an OIDL method using Buran:

  1. Setup an input-/output vector (iov_t) with one entry more than you want to pass parameters

  2. Set the first message-part (iov_t[0]) to the call-id of the method

  3. Pass the input parameters. See Parameter Passing how to do that

  4. Call retVal=MsgSend(...) to invoke the method

Now the method is being executed. After the execution MsgSend returns. You might want to check if the method succeeded or whether an exception was thrown, if so, do this:

  1. If retVal equals ret_Success everything succeeded. If retVal is smaller than ret_Success, an error predefined by Buran occurred. If retVal is greater than ret_Success, the exception where (call-ID==retVal) was thrown.

  2. You can now read (call MsgRead) either the return parameters (if everything succeeded) or the exception parameters (if an exception was thrown). See Parameter Passing and MsgRead documentation


Parameter Passing

Fixed-Length Parameters Only

The parameters are passed in the same order as written in the OIDL (e.g. the first parameter is message-part number 1, message part number 0 is the call-id).

Variable-and-Fixed-Length Parameters

First, pass all parameters (like in section Fixed-Length Parameters Only), but replace the variable-length parameters by their size . After that, pass the real data of the variable-length parameters in the same order as written in the OIDL (the first parameter gets into the first message-part).

Little-Endian and Big-Endian

Since two communicating objects might be on two different machines, it could happen, that their integers and floats are incompatible: one machine is a little-endian-machine and one is a big-endian-machine. (See the oid_t-struct in the Buran documentation).

If two integer-incompatible objects communicate, we use big-endian integers and float (and types composed of integers, such as strings).