This document is part
of the genesis project. See the project homepage at
genesisae.sf.net
for more information. This document is (or was) hosted by
SourceForge.
|
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".
| Revision History | |
|---|---|
| Revision 0 | 2004-01-18 |
|
Initial Version | |
| Revision 1 | 2004-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.
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:
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:
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:
Exceptions may have:
parameters (param). See Parameters
a description (description) which contains Simple HTML Text
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:
a description (description) which contains Simple HTML Test
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:
Setup an input-/output vector (iov_t) with one entry more than you want to pass parameters
Set the first message-part (iov_t[0]) to the call-id of the method
Pass the input parameters. See Parameter Passing how to do that
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:
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.
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
Done.
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).