PRM — Retrieving and setting parameters

PRM-GET — Retrieve the value a patameter from one or more target objects

A client sends this request to the server to ask the server to retrieve the current value of a parameter from one or more target objects.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of object IDs that the command should be sent to

name

yes

string

The name of the parameter whose value is to be retrieved

Response fields

The response is a multi-object async response; each target ID is mapped to the value of the parameter on the target. Typically, parameter values are strings or numbers, but more complex objects are also allowed, depending on the target object.

Example request

{
  "type": "PRM-GET",
  "ids": ["1", "17", "31", "spam"],
  "name": "EK2_ALT_SOURCE"
}

Example response

{
  "type": "PRM-GET",
  "result": {
    "1": 2
  },
  "receipt": {
    "17": "0badcafe-deadbeef:1"
  },
  "error": {
    "31": "No such parameter.",
    "spam": "No such object."
  }
}

PRM-SET — Set the value of a parameter on a target object

A client sends this request to the server to request the server to set the value of a parameter on one or more target objects.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of object IDs where the parameter value should be set

name

yes

string

The name of the parameter whose value is to be set

value

yes

any

The new value of the parameter

Response fields

The response is a multi-object async response; each target ID is mapped to a boolean denoting whether the parameter value was set successfully on the target object.

Example request

{
  "type": "PRM-SET",
  "ids": ["1", "17", "31", "spam"],
  "name": "EK2_ALT_SOURCE",
  "value": 2
}

Example response

{
  "type": "PRM-SET",
  "result": {
    "1": true
  },
  "receipt": {
    "17": "0badcafe-deadbeef:1"
  },
  "error": {
    "31": "No such parameter.",
    "spam": "No such object."
  }
}

PRM-SET-MANY — Set the value of multiple parameters on a target object

A client sends this request to the server to request the server to set the value of multiple parameters on one or more target objects.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of object IDs where the parameter value should be set

parameters

yes

object

The parameters to set, as a map of parameter names to their new values

Response fields

The response is a multi-object async response; each target ID is mapped to an object with a success key that is set to true if the all the parameters were set successfully and false otherwise. Optionally, the object may contain a failed key listing the names of the parameters that were not set successfully on the target object, if this information can be determined unambiguously.

It is an error to send a response where success is set to true and the failed list is not empty.

Example request

{
  "type": "PRM-SET-MANY",
  "ids": ["1", "17", "31", "spam"],
  "parameters": {
    "EK2_ALT_SOURCE": 2,
    "FENCE_ACTION": 0
  }
}

Example response

{
  "type": "PRM-SET-MANY",
  "result": {
    "1": {
      "success": true,
      "failed": []
    }
  },
  "receipt": {
    "17": "0badcafe-deadbeef:1",
    "31": "0badcafe-deadbeef:2"
  },
  "error": {
    "spam": "No such object."
  }
}