FETCH

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 delivering all available Objects in the requested range in the requested order. The Objects in the response are delivered on a single unidirectional stream. Any gaps in the Group and Object IDs in the response stream indicate objects that do not exist (eg: they implicitly have status Object Does Not Exist). For Ascending Group Order this includes ranges between the first requested object and the first object in the stream; between objects in the stream; and between the last object in the stream and the Largest Group/Object indicated in FETCH_OK, so long as the fetch stream is terminated by a FIN. If no Objects exist in the requested range, the publisher returns FETCH_ERROR with code No Objects.

If an Original Publisher receives a FETCH with a range that includes an object with unknown status, it MUST return FETCH_ERROR with code Unknown Status in Range.

Fetch Types

There are three types of Fetch messages:

Standalone Fetch (0x1) : A Fetch of Objects performed independently of any Subscribe.

Relative Joining Fetch (0x2) : A Fetch joined together with a Subscribe by specifying the Request ID of an active subscription and a relative starting offset. A publisher receiving a Joining Fetch uses properties of the associated Subscribe to determine the Track Namespace, Track, Start Location, and End Location such that it is contiguous with the associated Subscribe. The Joining Fetch begins the Preceding Group Offset prior to the associated subscription.

Absolute Joining Fetch (0x3) : Identical to a Relative Joining Fetch except that the Start Group is determined by an absolute Group value rather than a relative offset to the subscription.

A Subscriber can use a Joining Fetch to, for example, fill a playback buffer with a certain number of groups prior to the live edge of a track.

A Joining Fetch is only permitted when the associated Subscribe has the Filter Type Largest Object.

A Fetch Type other than 0x1, 0x2 or 0x3 MUST be treated as an error.

A publisher responds to a FETCH request with either a FETCH_OK or a FETCH_ERROR message. The publisher creates a new unidirectional stream that is used to send the Objects. The FETCH_OK or FETCH_ERROR can come at any time relative to object delivery.

A relay that has cached objects from the beginning of the range MAY start sending objects immediately in response to a FETCH. If it encounters an object in the requested range that is not cached and has unknown status, the relay MUST pause subsequent delivery until it has confirmed the object's status upstream. If the upstream FETCH fails, the relay sends a FETCH_ERROR and can reset the unidirectional stream. It can choose to do so immediately or wait until the cached objects have been delivered before resetting the stream.

The Object Forwarding Preference does not apply to fetches.

Fetch specifies an inclusive range of Objects starting at Start Location and ending at End Location. End Location MUST specify the same or a larger Location than Start Location.

The format of FETCH is as follows:

FETCH Message {
  Type (i) = 0x16,
  Length (16),
  Request ID (i),
  Subscriber Priority (8),
  Group Order (8),
  Fetch Type (i),
  [Track Namespace (tuple),
   Track Name Length (i),
   Track Name (..),
   Start Location (Location),
   End Location (Location),]
  [Joining Request ID (i),
   Joining Start (i),]
  Number of Parameters (i),
  Parameters (..) ...
}

Fields common to all Fetch Types:

• Request ID: See Section 8.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 6.

• Group Order: Allows the subscriber to request Objects be delivered in Ascending (0x1) or Descending (0x2) order by group. See Section 6. A value of 0x0 indicates the original publisher's Group Order SHOULD be used. Values larger than 0x2 are a protocol error.

• Fetch Type: Identifies the type of Fetch, whether Standalone, Relative Joining or Absolute Joining.

• Parameters: The parameters are defined in Section 8.2.1.

Fields present only for Standalone Fetch (0x1):

• 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).

• Start Location: The start Location.

• End Location: The end Location, plus 1 Object ID. An Object ID value of 0 means the entire group is requested.

Fields present only for Relative Fetch (0x2) and Absolute Fetch (0x3):

• Joining Request ID: The Request ID of the existing subscription to be joined. If a publisher receives a Joining Fetch with a Request ID that does not correspond to an existing Subscribe in the same session, it MUST respond with a Fetch Error with code Invalid Joining Request ID.

• Joining Start : for a Relative Joining Fetch (0x2), this value represents the group offset for the Fetch prior and relative to the Current Group of the corresponding Subscribe. A value of 0 indicates the Fetch starts at the beginning of the Current Group. For an Absolute Joining Fetch (0x3), this value represents the Starting Group ID.

Objects that are not yet published will not be retrieved by a FETCH. The Largest available Object in the requested range is indicated in the FETCH_OK, and is the last Object a fetch will return if the End Location 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 Start Location is greater than the Largest Object (Section 8.7) the publisher MUST return FETCH_ERROR with error code 'Invalid Range'.