RPC Message

Message exchanged in SHV is IMap with meta-data attached from RPC Value point of view.

There are three kinds of RPC messages defined:

• Request
• Response
• Signal

RPC message can have meta-data attribute defined.

Second part of RPC message is IMap with following possible keys.

RequestId can be any unique number assigned by side that sends request initially. It is used to pair up requests with their responses. The common approach is to just use request message counter as request ID.

CallerIds are related to the broker and unless you are implementing a broker you need to know only that they are additional identifiers for the message alongside the RequestId to pair requests with their responses and thus should be always included in the response message if they were present in the request.

The ShvPath is used to select exact node of method in the SHV tree.

AccessLevel is the way to specify access level. It is numerical with predefined range (0-63) and brokers on the way can lower this number to even further limit access. Broker are prohibited to increase this number. Access should be used to get level if this field is not present. Admin access level should be considered as the base limit if neither AccessLevel nor Access field is present.

userId is string containing information about the login names and the broker names along the RPC message path through the brokers hierarchy. The format isuser-name1:broker-name1;user-name2:broker-name2;..., for example: john@foo.bar:broker1;broker1-login:broker2. User name and broker name is delimited by :, user:broker pairs are delimited by ';'.

Access is older approach for the access control. It is assigned to request by broker according to user rights. Multiple grants can be specified and separated by comma. This is no longer the primary way and is used only for pre-SHV 3.0 peers or if additional access fields are specified.

The following are all defined AccessLevels and their Access representations:

Request

Message used to invoke remote method.

Methods invoked using this request needs to be idempotent, because RPC transport layers do not ensure deliverability. You might also want to try to send request again when you receive no response because of this.

Attributes:

Keys (only one can be used in the single message):

Examples

RPC call invocation, method switchLeft on path test/pme/849V with request ID 56 and parameter true.

<1:1,8:56,9:"test/pme/849V",10:"switchLeft">i{1:true}

Response

Response to Request. The response should be generated as soon as possible. If some work has to be performed before full response can be generated then Response Delay can be sent in reasonable intervals, until Result or Error is prepared.

Attributes:

Keys (only one can be used in the single message):

RpcResponse is invalid when both keys (Result and Error) are present.

RPC Error

RPC Error is IMap with following keys defined

Error codes:

Examples

Successful response to method call from example above

<1:1,8:56>i{2:true}

Exception when unknown method is called

<1:1,8:11>i{3:i{1:8,2:"method: foo path:  what: Method: 'foo' on path 'shv/cze' doesn't exist"}}

Signal

Spontaneous message sent without prior request and thus without RequestId. It is used mainly notify clients that some technological value had changed without need to poll.

Attributes:

Keys:

Warning: all signal names ending with chng (that includes chng and others such as fchng) are considered as property changes of the method they are associated with, and thus cache can use to update its state them instead of method call. If your method emits signals with different parameter than response's result then do not use signal names ending with chng.

Examples

Spontaneous notification about change of status/motorMoving property to true.

<1:1,9:"shv/test/pme/849V/status/motorMoving",10:"chng",11:"get">i{1:true}