Initial: 2003-09-20
Modified: 2003-09-20

MRPT-RPC

The goal is to be an RPC style protocol based on MRPT (or a similar transport). The exact encoding will be left to whatever is used as a transport (one could use XML if so desired).
I will define that tags for this protocol are in the protocol class "mrptrpc" (exculding extensions, which have rules defined elsewhere).
It is allowable to drop the class if being used on a transport where the class would normally not be included.

MRPT-RPC will use a "dynamic friendly" type representation. It will be the job of the reciever to complian if the types/argument counts/... do not match.
This will follow practices similar to XML-RPC.

Types

It is not assumed that all implementations can handle and retransmit all types correctly, thus "general" interfaces should refrain from relying on either correct dynamic typing behavior or that the types will be sent/recieved as expected (ie: a symbol converts to a string, date->string, character->integer, boolean->integer, ...). Statically typed implementations should be able to mashall types that are close but not exactly the same.

Primitive Types

Tag	Class	Description
integer	Value, Integer	Integer value.
boolean	Value, Integer	Boolean value, 0=false, 1=true
string	Value, String	String value.
float	Value, Float	Floating point value.
data	Value, Raw	Raw Data.
date	Value, String	Date String, 'YYYY-MM-DD hh:mm:ss', UTC.
symbol	Value, Name, String	Symbolic value, trated as string if symbols are unsupported.
character	Value, Integer	Character literal, integers if characters are unknown.

Compound Types

Tag	Class	Contents	Description
array	Value	values	Array Object, Contains a Values object. It may also have some options.
values	Piece	value...	Values, a glob of values. This is contained in arrays or used for calls.
terminal	Piece	value	Terminal, Defines a terminal value for an array (aka: list). To be ignored for implementations that don't support terminal values.
struct	Value	member...	Structure Object, contains Member objects which associate names to values.
member	Piece	name value	Member, Contains a name and a value. This is found in structures.
vector	Value	values	Vector Object, for implementations that distinguish lists and vectors. Otherwise to be treated like array.
link	Value	url target mode	Link Object, provides a link to a resource on another node. url identifies the node, target the obj on the node. Mode is even for bi-directional targets and odd for unidirectional ones. The next 7 bits define what the object is, for now: 0=unused, 1=generic uni-directional, 2=generic bi-directional, 3=process, 4=function.

Messages

Tag	Contents	Description
call	target values contid	Calls target with values. Contid is sent with the return.
return	value contid	Return from a call, contid came from the call.
error	name values description contid	Error occured with call, name and values identify the error, description describes it, contid indicates what call failed.
pass	target values	Pass values to target. Pass is not gueranteed reliable.

Targets are either:
Strings, identifying an exported resource by name;
Integers, identifying a resource by an implementation dependant integer;
Links, it may be possibly for an implementation to forward messages, in this case links may be allowed, otherwise passes may be dropped and calls will generate errors.

Contid is to allways be an integer.