Sound Control Protocol for SpeechLine Digital Wireless

SSC Developer‘s guide for SpeechLine Digital Wireless | 16/109
SSC subscriptions - /osc/state/subscribe
5. SSC subscriptions - /osc/state/subscribe
A subscription request is sent by a client to a server for an address pattern to subscribe to. The SSC
Server normally accepts the subscription request, and remembers that the requesting client wishes
to be notified about value changes of the subscribed addresses.
The SSC Server MAY refuse subscription requests, subject to device-specific policy or implementa-
tion specific limitations. The SSC Server MUST reply on the subscription request immediately either
by acknowledging the request, or by sending an error reply.
The SSC Server MUST send an initial subscription notification to the client, which contains the re-
sult of calling the subscribed SSC Methods immediately with null-argument when the subscription
request is handled. This initial notification MAY be bundled with the reply to the subscription request
itself.
Each subscription notification MUST have identical contents to the reply to an imagined SSC Method
invocation with null-argument to the subscribed SSC Method Address at the time that the notifica-
tion is sent.
The SSC Client MAY bundle a call to /osc/xid with the subscription request. If a xid is supplied,
a reply to /osc/xid MAY be bundled with each subscription notification, with the xid of the reply
identical to that supplied by the client.
The SSC Server MUST send value changes of the subscribed addresses to the SSC Client. By default,
the SSC Server will send subscription notifications if and only if the subscribed addresses change
in value. The SSC Client can modify this behaviour by supplying optional parameters with the sub-
scription request, allowing to either throttle the rate of notifications, or stimulate additional periodic
notifications even if the subscribed addresses do not change in value.
Every subscription is specific to the connection between SSC Client and SSC Server. Also each SSC
Method can only be subscribed once per connection. This means, that if a SSC Client requests a sub-
scription which is already subscribed by that client on that connection, then the SSC Server MUST
treat this as if the existing subscription was silently terminated and immediately requested anew.
5.1 Subscription cancelling and expiration
The SSC Server MUST terminate a subscription in these cases:
• the subscribed client cancels the subscription explicitly
• a maximum number of notifications has been sent
• a maximum lifetime relating to the begin of the subscription expires
• the SSC Client closes the connection
• the transport layer of the SSC connection signals a communication error
If the SSC Server decides to terminate the connection because the lifetime or notification count ex-
pires, then it MUST inform the SSC Client by sending an error reply "310 – subscription terminated"
to the SSC address that terminates subscription together with or immediately after the last subscrip-
tion notification.
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.