A subscriber issues a FETCH to a publisher to request a range of already published objects within a track. The publisher responding to a FETCH is responsible for retrieving all available Objects. If there are gaps between Objects, the publisher omits them from the fetch response. All omitted objects have status Object Not Available.
A publisher responds to a FETCH request with either a FETCH_OK or a FETCH_ERROR message. If it responds with FETCH_OK, the publisher creates a new unidirectional stream that is used to send the Objects. A relay MAY start sending objects immediately in response to a FETCH, even if sending the FETCH_OK takes longer because it requires going upstream to populate the latest object.
The Object Forwarding Preference does not apply to fetches.
Fetch specifies an inclusive range of Objects starting at StartObject in StartGroup and ending at EndObject in EndGroup. EndGroup and EndObject MUST specify the same or a later object than StartGroup and StartObject.
The format of FETCH is as follows:
FETCH Message {
Type (i) = 0x16,
Length (i),
Subscribe ID (i),
Track Namespace (tuple),
Track Name Length (i),
Track Name (..),
Subscriber Priority (8),
Group Order (8),
StartGroup (i),
StartObject (i),
EndGroup (i),
EndObject (i),
Number of Parameters (i),
Parameters (..) ...
}
-
Subscribe ID: The Subscribe ID identifies a given fetch request. Subscribe ID is a variable length integer that MUST be unique and monotonically increasing within a session.
-
Track Namespace: Identifies the namespace of the track as defined in (Section 2.4.1).
-
Track Name: Identifies the track name as defined in (Section 2.4.1).
-
Subscriber Priority: Specifies the priority of a fetch request relative to other subscriptions or fetches in the same session. Lower numbers get higher priority. See Section 4.
-
Group Order: Allows the subscriber to request Objects be delivered in Ascending (0x1) or Descending (0x2) order by group. See Section 4. A value of 0x0 indicates the original publisher's Group Order SHOULD be used. Values larger than 0x2 are a protocol error.
-
StartGroup: The start Group ID.
-
StartObject: The start Object ID.
-
EndGroup: The end Group ID.
-
EndObject: The end Object ID, plus 1. A value of 0 means the entire group is requested.
-
Parameters: The parameters are defined in Section 6.1.1.
Objects that are not yet published will not be retrieved by a FETCH. The latest available Object is indicated in the FETCH_OK, and is the last Object a fetch will return if the EndGroup and EndObject have not yet been published.
A publisher MUST send fetched groups in the determined group order, either ascending or descending. Within each group, objects are sent in Object ID order; subgroup ID is not used for ordering.
If StartGroup/StartObject is greater than the latest published Object group, the publisher MUST return FETCH_ERROR with error code 'No Objects'.
A publisher MUST send fetched groups in group order, either ascending or descending. Within each group, objects are sent in Object ID order; subgroup ID is not used for ordering.