FETCH

9.16.1. Standalone Fetch

A Fetch of Objects performed independently of any Subscribe.

A Standalone Fetch includes this structure:

Standalone Fetch {
  Track Namespace (tuple),
  Track Name Length (i),
  Track Name (..),
  Start Location (Location),
  End Location (Location)
}

• 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. A Location.Object value of 0 means the entire group is requested.

9.16.2. Joining Fetches

A Joining Fetch is associated with a Subscribe request by specifying the Request ID of an active subscription. A publisher receiving a Joining Fetch uses properties of the associated Subscribe to determine the Track Namespace, Track Name and End Location such that it is contiguous with the associated Subscribe. The subscriber can set the Start Location to an absolute Location or a Location relative to the current group.

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; any other value results in closing the session with a PROTOCOL_VIOLATION.

If no Objects have been published for the track, and the SUBSCRIBE_OK has a Content Exists value of 0, the publisher MUST respond with a FETCH_ERROR with error code INVALID_RANGE.

A Joining Fetch includes this structure:

Joining Fetch {
  Joining Request ID (i),
  Joining Start (i)
}

• 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 : A relative or absolute value used to determing the Start Location, described below.

9.16.3. Fetch Handling

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),
  [Standalone (Standalone Fetch)],
  [Joining (Joining Fetch)],
  Number of Parameters (i),
  Parameters (..) ...
}

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

• Group Order: Allows the subscriber to request Objects be delivered in Ascending (0x1) or Descending (0x2) order by group. See Section 7. 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.

• Standalone: Standalone Fetch structure included when Fetch Type is 0x1

• Joining: Joining Fetch structure included when Fetch Type is 0x2 or 0x3.

• Parameters: The parameters are defined in Section 9.2.1.

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.

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.

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 for Standalone and Absolute Joining Fetches.

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.

If Start Location is greater than the Largest Object (Section 9.7) the publisher MUST return FETCH_ERROR with error code INVALID_RANGE.

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