This document describes the Application Programming Interface (API) for controlling a RI System remotely.
System Requirements
Guru connection to RI System Controller
Guru can be installed on Win, Mac, Linux, ArcaOS (OS/2)
Introduction
Sockets are used to communicate with Guru. Open a socket connection and send RIRI Commands.
GURU RIRI Commands
1.0 Comments and Syntax
Separators are ^ (16r1C)for first (top) level and + (16r1D) for second level. ~ (16r1E) for third level
(16r1F) for fourth level
[] enclose RIRI submessages
Command is the first parameter and consists of a command string
optionally followed by a 16r1D and 1 or more keyName=value pairs
separated by 16r1D. These are referred to as command attributes.
Within a value 16r1E can be used to show multiple values
KeyList is +keyName+keyName...
KeyValList is +keyName=keyValue+keyName=keyValue...
ValList is ^+val11+val12...^+val21+val22.. Where ValXY is the value
for key X and Object Y. X is assigned by the order in the keyList
and Y by the sort criteria. If an Object does not have a
corresponding value then and empty string is used
Query is KeyValList+Sort where sort is hist:n, max:n, last, or all
all is all objects selected
last is the most recent as determined by guruTime
(lower part of cid)
last:n is up to n most recent objects
max:n is up to n objects in no order
hist:n is the n prior objects with the same ri.sys.RevisionOf
only applies to KeyValues command
KeyName='' is allowed in a query and means that a KeyName
must have a value, any value, '' is an zero length string
KeyName!=value is allowed in a query and means that a KeyName
must have a value, but not equal to value. Value can be value~value~value...
KeyName!=value~value~value... is allowed in a query and means that a KeyName
must have a value, but not equal to any of the values in the list.
KeyName=value~value~value... is allowed in a query and means
that a KeyName must have a value equal to one of the values
KeyName>=value is allowed in a query and means that a KeyName
must have a value, that is more than or equal to value
KeyName<=value is allowed in a query and means that a KeyName
must have a value, that is less than or equal to value
Searching, Obsoleted and Undo
Only the latest object in a revision tree is searchable. A revision tree
is where the value of ri.sys.RevisionOf is shared by all objects.
Obsolete objects have ri.sys.Obsoleted=true. The default sort criteria
is for ri.sys.Obsoleted=false. These objects become history and can be
accessed via the hist:n sort until the object is removed due to need for
storage space.
Undo works by allowing an user to select an older copy and then doing a
save to the same revisionTree making it the most recent. In addition SaveAs
is supported to allow recovery of specific objects
Usage of ExpireOn keys
The local.ri.sys.ExpireOn and ri.sys.ExpireOn keys act to remove an object
from visibility.
Currently the implementation is as follows;
If either local.ri.sys.ExpireOn or ri.sys.ExpireOn is exceeded then all objects
with a RevisionOf equal to the object expiring are removed (not obsoleted)
from the local guru's tables and file system.
Warnings and errors
Errors are returned by a special message format so there is no need to check
the reply contents as well. If an error is returned it is in key=val format using 1Dx
as the separator.
Supported keys are:
error = for error number
reason= for message string
Currently Defined errors ( error, reason)
100 Attribute not supported
101 Action not allowed
102 No Object Found when an CID was specified
103 Object Obsolete
104 Object exists
105 Too many objects selected
106 Access Denied
107 Request Timed out
108 Syntax error
109 Hash check failed
110 Communication failure, action aborted
Command Attributes
TTL=aInteger max number of guru hops. default =infinite
SRC=aList semicolon separated list of guruIds which have been passed
SCOPE=LOCAL limited to the local guru only
SCOPE=REMOTE ALL excluding the contents of the local cache
SCOPE=ALL default ex GR,KA,KV,OX goes to entire update chain plus backup
SCOPE=SYSTEM system wide
SANDBOX=aName Sandbox for this item
ENCRYPT=aGuruID guru which can decrypt this object
USER=16c 16c is revisionID of the user for determining permissions
USER=System Used to indicate that system permissions are requested
default is current user's permissions
CHECKSIGNER=TRUE Forces the signer to be checked on each access
default is false
GURU Commands (client to server, and server to server)
-Attribute Query:
[^AQ^KeyList] ==> [KeyValList]
Queries Guru Attributes.
Private means available to local connections only and not CQ
[^AQ^all] returns all attributes
Server Supported Query Attributes
Name Guru Name from Guru key
GuruID Guru ID from Gury key
SystemID Guru ID for the system
userID revisionOf of current user
GuruTime Current Guru time as integer seconds
launchCid CID of the launching guru object
channel 2 char channel HEX string (ms nibble first)
localTImeOffset seconds to add to GMT time
localTime local time in date syntax
appPn part number for application (if set by client)
appVer version of application (if set by client)
systemSn user serial number in the RiSystem object
systemName user name in the RiSystem object
sessionId string identifier for the session
disableSystemMessages
controls system messages
Client Supported Query Attributes
appPn part number for application
appVer version of application
Error responses
ER,100,Attr not Supported (only if all requested keys are missing)
-Attribute Set:
[^AS^KeyValList] ==> [OK]
Sets Guru Attributes
Client to Server
buttonText string to put in button for launcher,
empty string terminates use of button
appPn the part number for the application
appVer the version of the application
smClientEnable true/false
enables system messages to the client. The client
is the end which initiates the connection
smMasterEnable
indicates that the master ( upstream connection)
will accept sm from the client
debugSystemMessages ( not yet )
sends all SM to this connection
sessionId string identifier for the session, only valid on open
loopback=n
Sets the number of milliseconds of inactivity (time-out period) for the connection
to be automatically closed by the server. IF loopback=0
precludes connection from automatically closed because of time out.
Server to client
GuruID Guru ID
SystemID Guru ID for the system
GuruITime Guru time in seconds
localTimeOffset seconds to be added to GMT to make local time
launchCid CID of the launching RiAutoStart
launchKeys KeyValues used in the SA command
userID revisionOf of current user
Top puts main window on top in display
channel 2 char channel hex string (ms nibble first)
logLevel a integer string indicating debug log detail, higher number
means more detail. '0' is no debug logging.
sessionId string identifier for the session
Error responses
ER,100,Attr not Supported. Only if an illegal name is specified
-Local Encode:
[^LE^String] ==> [Mod Power Bytes Hex String]
For local client to server only.
String to be encoded by the servers private key, returns the encoded string in Mod Power
Bytes Hex String (private).
Error responses
ER,106, Access Denied
-Local Decode:
[^LD^Mod Power Bytes Hex String ] ==> [String]
For local client to server only
Mod Power Bytes Hex String to be decoded by the servers private key, returns the
decoded string (private)
Error responses
ER,106, Access Denied
-Local Key Delete:
[^KD^Query^KeyList] ==> [OK]
For any items matching the query
Deletes the specified keys from them (if they exist)
Error responses
ER,101, Cannot Change non local keys
-Local Key Set:
[^KS^Query^KeyValList] ==> [OK]
For each item that matches the query
Set its keys as per the given "key=val" list
Error responses
ER,101, Cannot Change non local keys
-Log Message:
[^LM^KeyValList] ==> [OK]
posts a message to a logging/viewing function
supported keys:
message text message to show
severity Fatal System, Fatal application Error, Messages
level Applies to messages only, All, major
source application identifier string
Error responses
none
-Log Messages Query:
[^LQ^Query^KeyList] ==> [ValList]
Given the set of items that match the query criteria.
Returns a Val list covering each matching message.
Queried items are removed from list
-Key Names:
[^KQ^Query] ==> [KeyList]
Returns list of used key names by items that match the query.
Note: If multiple items match, returns the union
of all used keys. Used by selectors to get allowed names
Returns the union of the scoped gurus. Duplicates are removed
Error responses
ER,102, No Object Found
-Key Range
[^KR^Query^KeyList] ==> [ValList]
Given the set of items that match the query criteria. and
returns 0 or more items each of which is a list of unique values
for that key (ie: per key in keylist order, used for creating
select lists for menus etc.)
Returns the union of the scoped gurus. Duplicates are removed
Error responses
ER,102, No Object Found
-Key Values:
[^KV^Query^KeyList] ==> [ValList]
Given the set of items that match the query criteria.
Returns a parameter list for each matching object.
(ie: per object, used for indexing, getting values of objects...).
KeyList must include ri.sys.Cid, ri.sys.Rid and ri.sys.Permission
if not they are added
Returns the union of the scoped gurus.
Duplicate Cids are removed
Expired and Obsolete objects removed
Only latest in Rid tree provided
Permissions applied
Error responses
ER,102, No Object Found
-Object Key Values:
[^KA^Query] ==> [KeyValList]
Retrieves all keys (local and global) for item matching the query
If more than one item matches then returns error
It is recommended that The Query specifies ri.sys.Cid only
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied
-Object Retrieve:
[^OR^Query] ==> [objectBytes]
Retrieves data bytes for item matching the query
If more than one item matches then returns error and no action occurs
If CID is specified and no object available then error is sent
If newer version found update the local Guru
If the object is encrypted and this guru has the decryption key
and the Client has permission the object is decrypted before transfer
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied for CID
-Object All:
[^OA^Query] ==> [KeyValList][objectBytes]
Retrieves attributes and data bytes for item matching the query
Does not return local attributes
If more than one item matches then returns error and no action occurs
If CID is specified and no object available then error is sent
If newer version found update the local Guru
If the object is encrypted and this guru has the decryption key
and the Client has permission the object is decrypted before transfer
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied
-Object Partial:
[^OP^Query] ==> [KeyValList][objectBytes]
Retrieves attributes and 20K max data bytes for item matching the query
If more than one item matches then returns error and no action occurs
If CID is specified and no object available then error is sent
If newer version found update the local Guru
If the object is encrypted and this guru has the decryption key
and the Client has permission the object is decrypted before transfer
The attributes
info.ri.sys.Partial is set to true
info.ri.sys.ObjectSize is set to the size
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied
-Object Save:
[^OS^KeyValList][GuruFile] ==> [KeyValList]
Creates a new item with attributes as specified in the "key=val" list
and with the given data. The returned KeyValList has all of the keys
in it.
If local attributes are specified they are removed and not saved
Error responses
ER,102, No Object Found for CID
ER,106, Access Denied
-Object Delete:
[^OD^Query] ==> [OK]
Deletes (obsoletes) this object from the guru file system.
Does this by saving a copy of the object with ri.sys.Obsolete=true
Still available via history query
Query must be ri.sys.Cid= only
Error responses
ER,101, Action Denied
ER,102, No Object Found for CID
ER,106, Access Denied