pub struct Message { /* private fields */ }Expand description
A message on its way to the server’s Metadata Adapter.
There are two shapes, and the difference is not cosmetic:
Message::new— numbered, so the server can deduplicate it and so its outcome can be reported back to you.Message::fire_and_forget— unnumbered and unreported. The server cannot tell a resend from a new message and you will never learn whether it worked.
§The number is yours to choose
The progressive starts at 1 and orders the messages of a sequence. This crate deliberately does not allocate it: the server tracks the numbering per session, so a counter kept here would silently restart the moment a session was replaced — exactly when a caller most needs to know what happened to a message. You own the numbering, and this crate never rewrites it.
§Examples
use std::num::NonZeroU32;
use lightstreamer_rs::{Message, SequenceName as Sequence};
let message = Message::new("BUY 100", NonZeroU32::MIN)
.in_sequence(Sequence::try_new("ORDERS")?);Implementations§
Source§impl Message
impl Message
Sourcepub fn new(text: impl Into<String>, progressive: NonZeroU32) -> Self
pub fn new(text: impl Into<String>, progressive: NonZeroU32) -> Self
A numbered message whose outcome will be reported.
The outcome arrives on the session event stream as
SessionEvent::Message.
Sourcepub fn fire_and_forget(text: impl Into<String>) -> Self
pub fn fire_and_forget(text: impl Into<String>) -> Self
A message with no number and no outcome report.
The protocol makes these two properties inseparable: a message may omit
its progressive only if it also declines the outcome notification
[docs/spec/03-requests.md §12.1]. So this is genuinely
fire-and-forget — no ordering, no deduplication, no confirmation, and
no error if the Metadata Adapter rejects it.
Sourcepub fn in_sequence(self, sequence: SequenceName) -> Self
pub fn in_sequence(self, sequence: SequenceName) -> Self
Places the message in an ordered sequence.
Messages of one sequence are processed in progressive order; messages of different sequences do not constrain each other.
Sourcepub fn with_max_wait(self, wait: Duration) -> Result<Self, ConfigError>
pub fn with_max_wait(self, wait: Duration) -> Result<Self, ConfigError>
How long the server may wait for earlier messages of the same sequence
before giving up on them and processing this one
[docs/spec/03-requests.md §12.1].
Only meaningful alongside Message::in_sequence. When the wait
expires the skipped progressives are reported as failures with
Appendix B codes 38 and 39 [docs/spec/05-error-codes.md §2].
§Errors
ConfigError::DurationTooLarge if the duration does not fit a whole
number of milliseconds.
Sourcepub fn validate(&self) -> Result<(), ConfigError>
pub fn validate(&self) -> Result<(), ConfigError>
Checks that the parts of this message can be sent together.
Client::send_message calls this first,
so a caller never has to; it is public for the same reason
Subscription::validate is.
§Errors
ConfigError::SequencedMessageNeedsAProgressiveif aMessage::fire_and_forgetmessage was placed in a sequence. A sequence orders messages by their progressive, and a fire-and-forget message has none:LS_msg_progis “mandatory wheneverLS_sequenceis specified” [docs/spec/03-requests.md§12.1]. The two are not a combination the protocol leaves open.ConfigError::MaxWaitNeedsASequenceifMessage::with_max_waitwas used on a message in no sequence, where it names how long to wait for messages that do not exist. The server ignores it there [docs/spec/03-requests.md§12.1]; this crate refuses it, so that a caller who set a bound is never silently running without one.
§Examples
use lightstreamer_rs::{ConfigError, Message, SequenceName};
let impossible = Message::fire_and_forget("BUY 100")
.in_sequence(SequenceName::try_new("ORDERS")?);
assert!(matches!(
impossible.validate(),
Err(ConfigError::SequencedMessageNeedsAProgressive)
));