The sender of a request (SUBSCRIBE, PUBLISH, FETCH, PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS) can later send a REQUEST_UPDATE on the same bidi stream as the request to modify it. A subscriber can also send REQUEST_UPDATE to modify parameters of a subscription established with PUBLISH.
An endpoint that receives a REQUEST_UPDATE other than in the two cases above
MUST close the session with a PROTOCOL_VIOLATION.
The receiver of a REQUEST_UPDATE MUST respond with exactly one REQUEST_OK or REQUEST_ERROR message indicating if the update was successful, unless it is coalescing failed updates to produce just one REQUEST_ERROR for multiple REQUEST_UPDATE messages.
The number of outstanding REQUEST_UPDATEs on a single request stream is limited by the MAX_REQUEST_UPDATES Setup Option (Section 10.3.1.7).
If a parameter previously set on the request is not present in
REQUEST_UPDATE, its value remains unchanged.
There is no mechanism to remove a parameter from a request.
The format of REQUEST_UPDATE is as follows:
REQUEST_UPDATE Message {
Type (vi64) = 0x2,
Length (16),
Request ID (vi64),
Number of Parameters (vi64),
Parameters (..) ...
}
-
Request ID: See Section 10.1.
-
Parameters: The parameters are defined in Section 10.2.
10.9.1. Updating Subscriptions
When a subscriber decreases the Start Location of the Location Filter (see Section 5.1.2), the Start Location can be smaller than the Track's Largest Location, similar to a new Subscription. FETCH can be used to retrieve any necessary Objects smaller than the current Largest Location.
When a subscriber increases the End Location, the Largest Object at the publisher might already be larger than the previous End Location. This will create a gap in the subscription. The REQUEST_UPDATE_OK will include the LARGEST_OBJECT parameter, and the subscriber can issue a FETCH to retrieve the omitted Objects, if any.
When a subscriber narrows their subscription (increase the Start Location and/or decrease the End Group), it might still receive Objects outside the new range if the publisher sent them before the update was processed.
When a REQUEST_UPDATE is unsuccessful, the publisher MUST also terminate
the subscription by sending a
PUBLISH_DONE with error code UPDATE_FAILED. When a REQUEST_UPDATE fails for
a FETCH, the publisher MUST reset the FETCH data stream. When a REQUEST_UPDATE
fails for a SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS or PUBLISH_NAMESPACE, the
responder MUST close the bidi stream (see Section 3.3.2).
A receiver of multiple REQUEST_UPDATE messages on the same stream MAY coalesce their processing by applying only the cumulative result. Parameter values from later REQUEST_UPDATE messages override values from earlier ones. The receiver MUST still send a REQUEST_OK for each successful update, but it is not required to process intermediate states individually. If the coalesced REQUEST_UPDATE results in REQUEST_ERROR, only a single REQUEST_ERROR will be sent and the sender of the REQUEST_UPDATEs will not always be able to determine which caused an error.
10.9.2. Updating Namespace Subscriptions
A subscriber can update the Track Namespace Prefix of an established SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS by including the TRACK_NAMESPACE_PREFIX parameter (Section 10.2.19) in a REQUEST_UPDATE. The overlap restriction applies independently per type: the new prefix MUST NOT share a common prefix with any other active SUBSCRIBE_NAMESPACE (for a SUBSCRIBE_NAMESPACE update) or SUBSCRIBE_TRACKS (for a SUBSCRIBE_TRACKS update) in the same session. If the update is accepted, NAMESPACE and NAMESPACE_DONE messages following the REQUEST_OK will contain Track Namespace suffixes relative to the updated prefix. Updating the prefix of a SUBSCRIBE_TRACKS has no effect on existing subscriptions. If the subscriber is no longer interested it can cancel the corresponding bidirectional stream.