Sound Control Protocol Digital 6000 (EM 6000 | L 6000)

SSC Developer‘s guide for Digital 6000 | 14/57
SSC subscriptions - /osc/state/subscribe
Optional subscription request parameters related to termination:
• "cancel" "true" cancels the subscription (default false).
• "count" maximum number of notifications to send, default 1000
• "lifetime" maximum lifetime (s) of the subscription, default 10s
The SSC Client may renew a subscription at any time, thereby resetting all of the lifetime limitations.
To renew a subscription, the SSC Client re-requests it; there’s no difference between an initial sub-
scription request and a renewal request.
5.3 Subscribing to multiple addresses
The SSC Client MAY request multiple subscriptions in a single request; either by providing them
explicitly as SSC Address Tree, or by specifying address patterns as subscription addresses, or even
both in the same request.
The SSC Server MAY either treat all those subscription requests separately, as if the addresses had
all been requested for subscription individually. In this case all the subscription notifications would
each contain the SSC Method Reply to a single subscribed address.
Alternatively, the SSC Server MAY bundle subscription notifications which happen to be sent at the
same time into a single notification. The SSC Client MUST be able to handle a bundled notification if it
requests multiple subscriptions in a single request, but it MUST NOT rely on the SSC Server bundling
the notifications.
In any case the SSC Server SHOULD NOT bundle notification causes, meaning that the SSC Server
SHOULD NOT send any subscription notifications for addresses in a bundle with notifications to oth-
er addresses, if they would not be sent if all subscriptions had been requested individually.
If some of the SSC addresses in a subscription request must be rejected with errors, whereas other
subscriptions succeed, then the SSC Server MAY reject the request completely with an error reply
detailing all the failed addresses. If possible, the SSC Server SHOULD instead execute the successful
subscriptions and only reject the erroneous ones. This MUST result in a successful reply message to
the subscription request, with the reply value including only the successful addresses. In this case
the SSC Error state MUST be set to "210 – Partial Success", and MAY be accompanied by a param-
eter named "failed_addresses" with an Array of Address trees composed of all the failed Method
Addresses (erroneous Addresses replaced by {}), in bundled or unbundled representation. The value
of the Address in the Address Tree SHOULD be set to the SSC Error Code relating to the failure of the
specific Address. See also the transaction example.
The SSC Server MAY also send a SSC Error "210 – Partial Success" when in fact all of the subscrip-
tions have failed, because the SSC Client receives sufficient information in this Error Reply to work
out this fact.
5.4 Supscription request and reply syntax
The SSC Address for subscriptions is /osc/state/subscribe.
This SSC Method may be called with a null parameter, which results in a SSC Address tree of all ad-
dresses currently subscribed by the SSC Client on the current connection.
The SSC Method also takes a structured parameter, specified as a JSON array.
Each element of the array is a SSC Address Tree specifying the SSC addresses that the SSC Client
requests to subscribe. The SSC Address Tree MAY contain Address patterns.
A SSC Server that supports subscription MUST be able to interpret a single Address Tree element in
the Method Argument array. Multiple Address Trees MAY be supported, or the SSC Server MAY reject
them with a SSC Error 414 (request too complex).
The Response to the subscription Request will normally echo the Request, if all subscriptions can be
handled successfully. If subscription parameters were requested, then the SSC Server MAY adapt
the requested parameters, and MUST send back the adapted parameter values in the Reply. If mul-
tiple subscriptions are requested in a single Request, then the SSC Server might find it necessary to
adapt subscription parameters differently for different Addresses. In that case, the array in the Re-
ply MAY contain additonal Address trees containing additional adapted parameter objects. The SSC
Server MAY also reject the subscription request completely (with SSC Error code 406), or partially
(with SSC Error code 210) in such a case.