Attention: The document is only a draft and GS6854-10 might change.
Copyright © 2004 Simon Ruoss
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".
Table of Contents
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.
Example 1. OIDL Example
<?xml version="1.0" encoding="UTF-8"?> <oidl version="0"> <head> <name value="HelloWorldObj"/> <description> <p>Use this object like this...</p> </description> </head> <exception> <name value="ConsoleOutputError"/> <cid value="0x0015"> <param name="errorCode" type="Int8"/> <param name="fatalError" type="Boolean"/> </exception> <method> <name value="SayHello"/> <cid value="0x0020"/> <description> <p>Call this <b>method</b> and it will print <li>Hello World</li>.</p> </description> <param name="useGerman" type="Boolean"/> <returns> <param name="printedText" type="StringUTF8"/> <param name="usedGerman" type="Boolean"/> </returns> <throws value="ConsoleOutputError"/> </method> <signal> <name value="MySignal"/> <range from="0x15" to="0x15"/> <description> <p>This is a fake-signal</p> </description> </signal> </oidl>
The header (head) has at least:
The header may also have:
Methods (method) have at least:
Methods may have:
Exceptions (exception) have at least:
Exceptions may have:
Signals (signal) have at least:
Signals may have:
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):
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:
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.
Float32 (single), Float64 (double) and Float128 (quadruple) comply with IEEE 754 standart.
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).
Follow these steps to call an OIDL method using Buran:
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:
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).
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).
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).