SUBSCRIBE

A subscription causes the publisher to send newly published objects for a track. A subscriber MUST NOT make multiple active subscriptions for a track within a single session and publishers SHOULD treat this as a protocol violation. The only objects prior to the current object that can be requested are those in the current group.

Filter Types

The subscriber specifies a filter on the subscription to allow the publisher to identify which objects need to be delivered.

There are 4 types of filters:

Latest Group (0x1) : Specifies an open-ended subscription with objects from the beginning of the current group. If no content has been delivered yet, the subscription starts with the first published or received group.

Latest Object (0x2): Specifies an open-ended subscription beginning from the current object of the current group. If no content has been delivered yet, the subscription starts with the first published or received group.

AbsoluteStart (0x3): Specifies an open-ended subscription beginning from the object identified in the StartGroup and StartObject fields. If the StartGroup is prior to the current group, the publisher MUST reply with a SUBSCRIBE_ERROR with code 'Invalid Range'.

AbsoluteRange (0x4): Specifies a closed subscription starting at StartObject in StartGroup and ending at EndObject in EndGroup. The start and end of the range are inclusive. EndGroup and EndObject MUST specify the same or a later object than StartGroup and StartObject. If the StartGroup is prior to the current group, the publisher MUST reply with a SUBSCRIBE_ERROR with code 'Invalid Range'.

A filter type other than the above MUST be treated as error.

If a subscriber wants to subscribe to Objects both before and after the Latest Object, it can send a SUBSCRIBE for the Latest Object followed by a FETCH. Depending upon the application, one might want to send both messages at the same time or wait for the first to return before sending the second.

The format of SUBSCRIBE is as follows:

SUBSCRIBE Message {
  Type (i) = 0x3,
  Length (i),
  Subscribe ID (i),
  Track Alias (i),
  Track Namespace (tuple),
  Track Name Length (i),
  Track Name (..),
  Subscriber Priority (8),
  Group Order (8),
  Filter Type (i),
  [StartGroup (i),
   StartObject (i)],
  [EndGroup (i),
   EndObject (i)],
  Number of Parameters (i),
  Subscribe Parameters (..) ...
}

• Subscribe ID: The subscriber specified identifier used to manage a subscription. Subscribe ID is a variable length integer that MUST be unique and monotonically increasing within a session and MUST be less than the session's Maximum Subscribe ID.

• Track Alias: A session specific identifier for the track. Messages that reference a track, such as OBJECT (Section 7.1), reference this Track Alias instead of the Track Name and Track Namespace to reduce overhead. If the Track Alias is already being used for a different track, the publisher MUST close the session with a Duplicate Track Alias error (Section 3.5).

• 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 subscription relative to other subscriptions 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.

• Filter Type: Identifies the type of filter, which also indicates whether the StartGroup/StartObject and EndGroup/EndObject fields will be present.

• StartGroup: The start Group ID. Only present for "AbsoluteStart" and "AbsoluteRange" filter types.

• StartObject: The start Object ID. Only present for "AbsoluteStart" and "AbsoluteRange" filter types.

• EndGroup: The end Group ID. Only present for the "AbsoluteRange" filter type.

• EndObject: The end Object ID, plus 1. A value of 0 means the entire group is requested. Only present for the "AbsoluteRange" filter type.

• Subscribe Parameters: The parameters are defined in Section 6.1.1.

On successful subscription, the publisher MUST reply with a SUBSCRIBE_OK, allowing the subscriber to determine the start group/object when not explicitly specified and the publisher SHOULD start delivering objects.

If a publisher cannot satisfy the requested start or end or if the end has already been published it SHOULD send a SUBSCRIBE_ERROR with code 'Invalid Range'. A publisher MUST NOT send objects from outside the requested start and end.