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 UNEXPECTED_MESSAGE.
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_UPDATE_OK for each successful update, but it is not required to process intermediate states individually. If the coalesced REQUEST_UPDATE results in an error, only a single REQUEST_UPDATE_ERROR will be sent and the sender of the REQUEST_UPDATEs will not always be able to determine which caused an error. A receiver MUST NOT coalesce a REQUEST_UPDATE containing a parameter whose definition prohibits coalescing.
REQUEST_UPDATE messages MUST be processed in order to guarantee consistent behavior. The receiver of a REQUEST_UPDATE MUST respond with exactly one REQUEST_UPDATE_OK or REQUEST_UPDATE_ERROR message indicating if the update was successful, unless it is coalescing failed updates to produce just one REQUEST_UPDATE_ERROR for multiple REQUEST_UPDATE messages. Because REQUEST_UPDATE and REQUEST_UPDATE_OKs are sent on a single in-order stream and REQUEST_UPDATE_OK does not contain a Request ID, REQUEST_UPDATE_OKs MUST be returned in the order the REQUEST_UPDATEs were received.
The number of outstanding REQUEST_UPDATEs on a single request stream is limited by the MAX_REQUEST_UPDATES Setup Option (Section 9.1.7).
If a parameter previously set on the request is not present in
REQUEST_UPDATE, its value remains unchanged.
There is no generic mechanism to remove a parameter from a request.
The format of REQUEST_UPDATE is as follows:
REQUEST_UPDATE Message {
Type (vi64) = 0x2,
Length (vi64),
Request ID (vi64),
Number of Parameters (vi64),
Parameters (..) ...
}
-
Request ID: See Section 6.4.2.1.
-
Parameters: The parameters are defined in Section 9.19. The parameters that can appear depend on the request being updated:
-
Subscription: OBJECT_DELIVERY_TIMEOUT, AUTHORIZATION_TOKEN, SUBGROUP_DELIVERY_TIMEOUT, PAUSED, SUBSCRIBER_PRIORITY, LOCATION_FILTER, FILL_PARAMETERS, SUBGROUP_FILTER, OBJECTID_FILTER, PRIORITY_FILTER, OBJECT_PROPERTY_FILTER, NEW_GROUP_REQUEST
-
FETCH: AUTHORIZATION_TOKEN, SUBSCRIBER_PRIORITY
-
PUBLISH_NAMESPACE: AUTHORIZATION_TOKEN
-
SUBSCRIBE_NAMESPACE: AUTHORIZATION_TOKEN, TRACK_NAMESPACE_PREFIX
-
SUBSCRIBE_TRACKS: AUTHORIZATION_TOKEN, PAUSED, TRACK_PROPERTY_FILTER, TRACK_NAMESPACE_PREFIX
Range Filters are only allowed from the subscriber (see Section 3.3.2).
-
9.5.1. Updating Subscriptions
When a subscriber decreases the Start Location of the Location Filter (see Section 3.3.1), the Start Location can be smaller than the Track's Largest Object, similar to a new Subscription. Including FILL_PARAMETERS (see Section 9.19.15) in the REQUEST_UPDATE causes the publisher to deliver the new fill range by opening a new fill fetch stream (see Section 3.4). FETCH can also be used to retrieve any necessary Objects with Locations less than or equal to the current Largest Object.
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 6.4.2.2).
9.5.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 9.19.20) in a REQUEST_UPDATE. If the update is accepted, NAMESPACE and NAMESPACE_DONE messages following the REQUEST_OK will contain Track Namespace suffixes relative to the updated prefix. For a SUBSCRIBE_NAMESPACE, the REQUEST_OK implies a NAMESPACE_DONE for each advertised namespace that no longer matches the prefix. Updating the prefix of a SUBSCRIBE_TRACKS has no effect on existing subscriptions, and the publisher MUST NOT send another PUBLISH for a Track it already published for that SUBSCRIBE_TRACKS. If the subscriber is no longer interested in a Track it can cancel the corresponding bidirectional stream.