pub struct FillParameters {
inner: Vec<KeyValuePair>,
}Expand description
A draft-23 FILL_PARAMETERS (Parameter Type 0x23), Section 9.19.15.
Putting one of these on a SUBSCRIBE or on a REQUEST_UPDATE for a
subscription is what asks the publisher to open a fill fetch stream: a
unidirectional stream beginning with a FETCH_HEADER, delivered exactly as a
FETCH response, carrying the Objects behind the live edge that the
subscription itself will not deliver. Its mere presence is the request;
FillParameters::inherited asks for a fill with every setting taken from
the subscription.
The nested parameters override the subscription’s for the fill alone. A
LOCATION_FILTER nested here selects the fill range and is evaluated
with Fetch rules, so it never reaches past Largest Object; it is independent
of the subscription’s own filter.
§The value is a count and the parameters
Section 9.19.15: “Its value is a Number of Parameters (vi64) followed by
that many Parameters that apply to the fill fetch stream (see Section 3.4),
encoded as if they were Parameters for a separate message (see Section
9.19).” No length precedes it, so an empty FILL_PARAMETERS is the single
byte 0x00.
§The Type Delta chain restarts here
Section 9.19.15: “The value of FILL_PARAMETERS is a separate parameter
scope. Parameters inside it are not considered to appear in the enclosing
message for the purposes of Section 9.19, so a Parameter Type MAY appear
both in the message and inside FILL_PARAMETERS.” Section 9.19 defines Type Delta against “the previous Parameter Type in the message”, and a
separate scope is not the message — so the inner chain starts from 0, and
the outer parameter after FILL_PARAMETERS deltas from 0x23 rather than
from the last inner type. The draft states neither half; both are
decided here and in the codec’s decoder, together.
Fields§
§inner: Vec<KeyValuePair>Implementations§
Source§impl FillParameters
impl FillParameters
Sourcepub fn inherited() -> Self
pub fn inherited() -> Self
A fill with every setting inherited from the subscription.
The common case, and the one whose encoding is worth knowing: one byte,
0x00, under a Length of 1.
Sourcepub fn with(self, parameter: KeyValuePair) -> Result<Self, FillError>
pub fn with(self, parameter: KeyValuePair) -> Result<Self, FillError>
Add a nested parameter. Types must be added in ascending order.
§Errors
FillError::NotAFillParameter for a type outside Table 7, and
FillError::RepeatedFillParameter for a second instance of a type
whose own definition does not allow repeats. Ordering is not checked
here — FillParameters::parameter sorts before encoding, because
Section 9.19 requires ascending order on the wire and a caller should
not have to know Table 7’s numbering to satisfy it.
Sourcepub fn with_range(self, filter: &LocationFilter) -> Result<Self, FillError>
pub fn with_range(self, filter: &LocationFilter) -> Result<Self, FillError>
Add the LOCATION_FILTER that selects the fill range.
Shorthand for with(filter.parameter()?), and the parameter most fills
carry: the fill range is what a fill is for.
Sourcepub fn with_group_order(self, order: GroupOrder) -> Result<Self, FillError>
pub fn with_group_order(self, order: GroupOrder) -> Result<Self, FillError>
Add the GROUP_ORDER (0x22) that the fill fetch stream’s Groups arrive
in.
Section 9.19.8: “When it appears inside FILL_PARAMETERS, it governs the fill fetch stream and its ordering relative to subscription-delivered Objects”. It is the one nested parameter a reader cannot ignore: Section 11.4.1.1 makes a Group ID Delta count upward under Ascending and downward under Descending, nothing on the data stream says which, and a reader started in the wrong order decodes every Object after the first into a Group that walks the wrong way — without failing to parse.
A shorthand rather than a raw KeyValuePair because the value is a
uint8 on the wire while the crate’s KvpValue has no uint8 arm: it
travels as a Varint whose value must fit one byte, and
encode_nested_value writes the byte. Getting that pair wrong is a
MalformedValue at best and a desynchronised block at worst.
§Errors
As FillParameters::with: FillError::RepeatedFillParameter for a
second GROUP_ORDER, which Section 9.19 does not allow.
Sourcepub fn inner(&self) -> &[KeyValuePair]
pub fn inner(&self) -> &[KeyValuePair]
The nested parameters, in the order they were added.
Sourcepub fn parameter(&self) -> Result<KeyValuePair, FillError>
pub fn parameter(&self) -> Result<KeyValuePair, FillError>
This block as the Message Parameter that carries it.
The value is the count, then the parameters in ascending type order with their types delta-encoded from 0, each value in the shape its own type names. It is decoded back through the codec before it is returned.
§Errors
FillError::MalformedValue for a value whose shape does not match its
type, and FillError::NotRoundTrippable if the codec’s
decode_fill_parameters refuses what this built or reads it back
differently.