Struct Message

pub struct Message { /* private fields */ }

A rustean representation of a BMessage

The Message class is identified by a u32 what value, that can be set during the creation of a message, and by using the set_what() method. In C++, this value is usually generated by using a 4 character literal. In Rust there is the haiku_constant! macro that simulates the behaviour.

The message can be further enriched by adding data. To add data, use the add_data() method. All data is identified by a label. Every type that implements the Flattenable trait may be added. It is possible to add more than one object to each label, creating an array-like construction. You may only add multiple values of the same type. Adding differing types will fail.

In order to read the data, you may use the find_data() method

Further manipulation of the data can be done with the remove_data() and remove_field() methods.

Implementations

impl Message

pub fn new(what: u32) -> Self

Create a new message with the signature what

pub fn what(&self) -> u32

Get the current identifier of the message

pub fn set_what(&mut self, what: u32)

Set a new identifier for the message

pub fn add_data<T: Flattenable<T>>( &mut self, name: &str, data: &T, ) -> Result<()>

Add data to the message.

Every type that implements the Flattenable trait may be added. The name parameter identifies the name with which the data will be associated. You may repeatedly reuse this method, to add more values to the name, as long as all the data is of the same type.

This method will return an error of ErrorKind::InvalidInput when you are trying to add data to an existing identifier, with a different type.

pub fn find_data<T: Flattenable<T>>( &self, name: &str, index: usize, ) -> Result<T>

Retrieve an object that is stored in the message

You may retrieve any object that implements the Flattenable interface. There may be more than one value stored, so you can use the index parameter to iterate through the object. The first value is at index 0.

This method will return ErrorKind::NotFound when the name is not in this message, or it is of a different type. Additionally, if the index is out of range, it will return ErrorKind::InvalidInput.

pub fn replace_data<T: Flattenable<T>>( &mut self, name: &str, index: usize, data: &T, ) -> Result<()>

Replace existing data in the message with a new value.

The requirement is that the data of the type exists under the name, at the index.

It returns ErrorKind::NotFound if the name does not exist, or it has a different type. ErrorKind::InvalidInput if the index is out of range, and otherwise any error that the Flattenable trait implementation returns.

pub fn remove_data(&mut self, name: &str, index: usize) -> Result<()>

Remove data for name at index

In case you are removing the only element at name, the whole field will be removed, effectively doing the same as remove_field().

This will return ErrorKind::NotFound when the identifier does not exist, and ErrorKind::InvalidInput when the index is out of range.

pub fn remove_field(&mut self, name: &str) -> Result<()>

Remove all data for a field

This removes all data stored at the identfier name. It will return ErrorKind::NotFound if there is no data stored at name.

pub fn get_info(&self, name: &str) -> Option<(u32, usize, bool)>

Retrieve the type, the number of items and whether or not it is fixed data

This method returns a tuple consisting of the type_code, the number of items and whether or not the data size is fixed, or None if there is no data.

pub fn is_empty(&self) -> bool

Check if the message has data associated with it

pub fn is_system(&self) -> bool

Check if the message is a system message

System messages have a what code that is built up from the ‘_’ (underscore) character, and three capital letters. Example: _BED Because of this fact it is advised not to give your message codes this structure.

pub fn is_reply(&self) -> bool

Check if the message is a reply message

pub fn was_delivered(&self) -> bool

Check if this message was delivered through a messenger

pub fn is_source_waiting(&self) -> bool

Check if the source is waiting for a reply

pub fn is_source_remote(&self) -> bool

Check if the source is another application than the current

pub fn get_return_address(&self) -> Option<Messenger>

Get a Messenger to the sender of this message

Trait Implementations

impl Debug for Message

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Flattenable<Message> for Message

fn type_code() -> u32

The type code is a unique identifier that identifies the flattened data

fn flattened_size(&self) -> usize

Return the size of the flattened type

fn is_fixed_size() -> bool

Check if flattened objects of this type are always a fixed size

fn flatten(&self) -> Vec<u8>

Return a flattened version of this object

fn unflatten(buffer: &[u8]) -> Result<Message>

Unflatten an object from a stream