pub struct SubscribeRange {
pub start_group: u64,
pub start_object: u64,
pub end: SubscribeEnd,
}Expand description
The range one AnyConnection::subscribe_range asks for.
The start is a plain Location on all the drafts and needs no type; the
end is SubscribeEnd, which is the whole point. What the drafts do to the
end Group is handled here rather than by the caller: drafts 08 through 16
write it out in full, drafts 17 through 20 write it as a delta from the start
Group, and this type takes the absolute value and derives the delta — the
same split, and the same direction of travel, as FetchRange.
§Which filter this is
SubscribeEnd::Open is the AbsoluteStart filter and everything else is
AbsoluteRange. The Filter Type is never taken as an argument beside the
fields, because that is the bug this type exists to make unavailable: a
SUBSCRIBE naming AbsoluteStart with no Start Location beside it is a frame
whose declared length is short by the fields its own type promised, and the
publisher reading it runs off the end of the message with nothing local to
complain. See AnyConnection::subscribe, which refuses both filters for
exactly that reason and points here.
Fields§
§start_group: u64The Group the range starts in.
start_object: u64The Object within start_group the range starts at, inclusive.
end: SubscribeEndWhere the range stops.
Implementations§
Source§impl SubscribeRange
impl SubscribeRange
Sourcepub fn starting_at(start_group: u64, start_object: u64) -> Self
pub fn starting_at(start_group: u64, start_object: u64) -> Self
From this Location onward, with no end: the AbsoluteStart filter.
Sourcepub fn through_end_of_group(
start_group: u64,
start_object: u64,
end_group: u64,
) -> Self
pub fn through_end_of_group( start_group: u64, start_object: u64, end_group: u64, ) -> Self
From this Location through the whole of end_group.
end_group is absolute and must not be below start_group — drafts 17
and later encode it as an unsigned delta from the start and have no way
to say “backwards”.
Sourcepub fn through_object(
start_group: u64,
start_object: u64,
end_group: u64,
end_object: u64,
) -> Self
pub fn through_object( start_group: u64, start_object: u64, end_group: u64, end_object: u64, ) -> Self
From this Location through end_object of end_group, inclusive.
Drafts 07 and 20 only. See SubscribeEnd::ThroughObject.
Sourcepub fn whole_group(group: u64) -> Self
pub fn whole_group(group: u64) -> Self
The whole of one Group, from its first Object.
The shape a caller asking “what has this track carried in group N” wants, and the one that is expressible on all the drafts.
Sourcepub fn filter_type(&self) -> FilterType
pub fn filter_type(&self) -> FilterType
Which of the two filters this range names.
Sourcepub fn start_location(&self) -> Location
pub fn start_location(&self) -> Location
The Start Location every draft carrying this range puts on the wire.
Sourcepub fn inline_end_location(
&self,
) -> Result<Option<Location>, AnyConnectionError>
pub fn inline_end_location( &self, ) -> Result<Option<Location>, AnyConnectionError>
The End Location draft-07 carries inline: the end Group, and the end
Object plus one, with 0 meaning the whole Group.
Draft-07 Section 6.4 gives its AbsoluteRange filter FETCH’s two fields
and FETCH’s two conventions, in the same words, which is why
moqtap_codec::types::check_location_range checks both. So this is
FetchRange::inline_end_object’s arithmetic on the one draft where a
subscription needs it, and it lives here rather than being reached for
from there so that the two cannot drift into disagreeing about a
sentence they share.
§Errors
SubscribeEnd::ThroughObject with end_object at u64::MAX: the plus
one leaves the number space, and wrapping it to 0 would silently widen
the range to the whole Group. Draft-20 can express that range and
draft-07 cannot.
Sourcefn group_only_end(
&self,
draft: DraftVersion,
) -> Result<Option<u64>, AnyConnectionError>
fn group_only_end( &self, draft: DraftVersion, ) -> Result<Option<u64>, AnyConnectionError>
The end Group drafts 08 through 19 carry, which is a Group and never a Location.
§Errors
SubscribeEnd::ThroughObject, which those twelve drafts deleted the
field for. Refused rather than widened to the whole Group: see
SubscribeEnd.
Sourcepub fn end_group_delta(&self) -> Result<Option<u64>, AnyConnectionError>
pub fn end_group_delta(&self) -> Result<Option<u64>, AnyConnectionError>
The end Group as drafts 17 and later write it: a delta from the start Group.
§Errors
An end_group below start_group. The delta is unsigned and there is no
such filter; drafts 08 through 16 have an absolute field and would put
the range on the wire, where the publisher refuses it. The difference is
where the refusal happens, not whether the range is legal.
Sourcepub fn subscription_filter(
&self,
draft: DraftVersion,
delta: bool,
) -> Result<SubscriptionFilter, AnyConnectionError>
pub fn subscription_filter( &self, draft: DraftVersion, delta: bool, ) -> Result<SubscriptionFilter, AnyConnectionError>
This range as the filter parameter drafts 15 through 19 carry it in.
delta is what those drafts disagree about among themselves: 15 and 16
write the End Group out in full, and 17 introduced the delta. The codec’s
SubscriptionFilter
refuses a filter whose end is spelled the other draft’s way, so the two
cannot be mixed up silently here.
§Errors
SubscribeEnd::ThroughObject, which these five drafts have no field
for — the same wall drafts 08 through 14 hit, one layer along. It is
worth saying twice because it is not obvious from the shape of the code:
the filter these drafts carry has a Start Location and an End Group,
so a range ending inside a group has nowhere to put its Object and would
otherwise be written out as the whole group with nothing to say it had
been widened.
And an end_group below start_group on the drafts that write a delta.
Sourcepub fn location_filter_draft20(
&self,
) -> Result<LocationFilter, AnyConnectionError>
pub fn location_filter_draft20( &self, ) -> Result<LocationFilter, AnyConnectionError>
This range as the draft-20 LOCATION_FILTER that carries it.
Two fields for an open-ended range, three for one through the end of a Group, four for one ending at an Object — Section 5.1.2 selects the shape by how many fields the value holds, so each of the three is a different constructor rather than the same one with values left out.
§{0, 0} means the opposite here, and is refused
On drafts 07 through 19 an AbsoluteStart at {0, 0} is the beginning of
the track. Draft-20 Section 5.1.2 gives the two-field filter {0, 0} to
Next Object — {Largest Object.Group, Largest Object.Object + 1},
or {0,0} where nothing has been delivered — which is the live edge and
not the beginning. The identical call would therefore ask thirteen drafts
for everything and draft-20 for nothing that has already happened, and
nothing on the wire says which was meant.
So it is refused, and the error names both ways round it: a range
(through_end_of_group, which is three fields and unambiguous) for the
beginning of the track, and
LocationFilter::next_object
through the draft-20 variant for the live edge. This is the only value on
the only draft where the two readings collide: a {0, 0} start with an
end beside it is three or four fields and means what it says, and any
other start location is unambiguous with or without one.
§Errors
The {0, 0} collision above, and an end_group below start_group, for
which see Self::end_group_delta.
The name carries the draft because the type does: LOCATION_FILTER
is draft-20’s and later’s, and each draft’s fill module declares its
own LocationFilter. An unsuffixed name would be two inherent methods
of one name the moment a second draft defines the parameter.
Sourcepub fn location_filter_draft21(
&self,
) -> Result<LocationFilter, AnyConnectionError>
pub fn location_filter_draft21( &self, ) -> Result<LocationFilter, AnyConnectionError>
This range as the draft-21 LOCATION_FILTER that carries it.
Two fields for an open-ended range, three for one through the end of a Group, four for one ending at an Object — Section 9.20.10 selects the shape by how many fields the value holds, so each of the three is a different constructor rather than the same one with values left out.
§{0, 0} means the opposite here, and is refused
On drafts 07 through 19 an AbsoluteStart at {0, 0} is the beginning of
the track. Draft-21 Section 9.20.10 gives the two-field filter {0, 0} to
Next Object — {Largest Object.Group, Largest Object.Object + 1},
or {0,0} where nothing has been delivered — which is the live edge and
not the beginning. The identical call would therefore ask thirteen drafts
for everything and draft-21 for nothing that has already happened, and
nothing on the wire says which was meant.
So it is refused, and the error names both ways round it: a range
(through_end_of_group, which is three fields and unambiguous) for the
beginning of the track, and
LocationFilter::next_object
through the draft-21 variant for the live edge. This is the only value on
the only draft where the two readings collide: a {0, 0} start with an
end beside it is three or four fields and means what it says, and any
other start location is unambiguous with or without one.
§Errors
The {0, 0} collision above, and an end_group below start_group, for
which see Self::end_group_delta.
The name carries the draft because the type does: LOCATION_FILTER
is draft-21’s and later’s, and each draft’s fill module declares its
own LocationFilter. An unsuffixed name would be two inherent methods
of one name the moment a second draft defines the parameter.