/pps/services/alarm/control

Publishers: Any app
Subscribers: coreServices

Note: This type of object is known as a server object, a special PPS object designed for point-to-point communication between a server and one or more clients. For details, see "Server objects" in the QNX Persistent Publish/Subscribe Developer's Guide.

Message/response format

Commands sent to the /pps/services/alarm/control object are of the form:

msg::command_string\nid::ID_number\ndat:json:{JSON_data}

Responses always reflect the command_string and ID_number that were sent in the message, along with any errors:

res::command_string\nid::ID_number\ndat:json:{JSON_data}\nerr::errno_number\nerrstr::error_description

Commands

msg::	id::	dat:json:
set	Number	`{"parameter":"value", "parameter":"value", ...}` (see below)
delete	Number	`{"alarmid":value}` (number returned from set command)

Note: If you attempt to delete an alarm that doesn't exist or has already expired, the errno_number will be 3 (ESRCH).

Parameters for set command

Parameter	Value
`alarmtype`	`relative`—triggered `n` seconds from now `absolute`—triggered at a certain time Note: If a relative alarm is set, the `seconds` parameter must be given (with optional `milliseconds`) to determine how long before the alarm expires. If an absolute alarm is set, the alarm expiry time must be specified in one of three ways: POSIX time (`posixtime` with optional `milliseconds`) POSIX time in milliseconds (`posixtimems`) date and time (with `year`, `month`, `day`, `hour`, and `minute`; `second` and `millisecond` are optional)
`clientlabel`	Simple label to identify the client.
`day`	The day when an absolute timer expires. You must also specify `year`, `month`, `hour`, and `minute`.
`hour`	The hour when an absolute timer expires. You must also specify `year`, `month`, `day`, and `minute`.
`millisecond`	The millisecond (0-999) when an absolute timer expires. This is optional (default is 0).
`milliseconds`	The milliseconds (0-999) from now when a relative timer will expire. This is optional (default is 0).
`minute`	The minute when an absolute timer expires. You must also specify `year`, `month`, `day`, and `hour`.
`month`	The month when an absolute timer expires. You must also specify `year`, `day`, `hour`, and `minute`.
`posixtime`	The time (in seconds since the epoch) when an absolute timer expires. You may also specify the `millisecond` parameter to indicate a millisecond delay from the given `posixtime`.
`posixtimems`	The time (in milliseconds since the epoch) when an absolute timer expires.
`precise`	Boolean value (`0` or `non-0`) to indicate whether the alarm should be precise. This is optional (default is `non-0`).
`second`	The second when an absolute timer expires. This is optional, but if specified you must also specify `year`, `month`, `day`, `hour`, and `minute`.
`seconds`	The number of seconds from now when a relative timer will expire.
`tolerance`	Specify the timer tolerance in nanoseconds. This is optional (default is 0).
`year`	The year when an absolute timer expires. You must also specify `month`, `day`, `hour`, and `minute`.

Example

Set a relative alarm and observe its status. First we force the shell to keep the file descriptor open:

# exec 3<> /pps/services/alarm/control

Then we issue the set command:

echo 'msg::set\ndat::{alarmtype:"relative", seconds:15, precise:1, clientlabel:"client1"}' >&3; cat <&3

The control object should now look something like this:

@control
res::set
dat:json:{"alarmid":196608}

The name of the /pps/services/alarm/status-<clientlabel> status object reflects the label given in the set command. The object should look like this:

[n]@status-client1
alarm_196608::running