Struct IgtlMessage

Source

pub struct IgtlMessage<T: Message> {
    pub header: Header,
    pub extended_header: Option<ExtendedHeader>,
    pub content: T,
    pub metadata: Option<HashMap<String, String>>,
}

Expand description

Complete OpenIGTLink message structure

Wraps a specific message type with header, optional extended header, and optional metadata.

§Type Parameters

T - Message type that implements the Message trait

Fields§

§header: Header

Message header (58 bytes)

§extended_header: Option<ExtendedHeader>

Extended header (Version 3 feature, optional) Contains metadata information and message ID when present

§content: T

Message content

§metadata: Option<HashMap<String, String>>

Metadata as key-value pairs (Version 3 feature, optional)

Implementations§

Source §

impl<T: Message> IgtlMessage<T>

Source

pub fn new(content: T, device_name: &str) -> Result<Self>

Create a new message with the given content and device name

§Arguments

content - Message content
device_name - Device name (max 20 characters)

§Returns

New message with generated header

Source

pub fn set_extended_header(&mut self, data: Vec<u8>)

Set extended header data (Version 3 feature)

When extended header is set, the message version is automatically upgraded to 3.

§Arguments

data - Extended header data as byte vector

§Examples

let transform = TransformMessage::identity();
let mut msg = IgtlMessage::new(transform, "Device").unwrap();
msg.set_extended_header(vec![0x01, 0x02, 0x03, 0x04]);

Source

pub fn set_extended_header_struct(&mut self, ext_header: ExtendedHeader)

Set structured Extended Header (Version 3 feature)

§Arguments

ext_header - Structured Extended Header

Source

pub fn get_extended_header(&self) -> Option<Vec<u8>>

Get extended header data reference (Version 3 feature)

§Returns

Optional reference to extended header bytes (additional_fields only, not the full structure)

Source

pub fn get_extended_header_struct(&self) -> Option<&ExtendedHeader>

Get structured Extended Header reference (Version 3 feature)

§Returns

Optional reference to structured Extended Header

Source

pub fn get_message_id(&self) -> Option<u32>

Get message ID from Extended Header

§Returns

Message ID if Extended Header exists, None otherwise

Source

pub fn set_message_id(&mut self, message_id: u32)

Set message ID in Extended Header

Creates Extended Header if it doesn’t exist.

§Arguments

message_id - Unique message identifier

Source

pub fn clear_extended_header(&mut self)

Remove extended header and optionally downgrade to Version 2

Source

pub fn set_metadata(&mut self, metadata: HashMap<String, String>)

Set metadata key-value pairs (Version 3 feature)

When metadata is set, the message version is automatically upgraded to 3.

§Arguments

metadata - HashMap of key-value pairs

§Examples

let transform = TransformMessage::identity();
let mut msg = IgtlMessage::new(transform, "Device").unwrap();
let mut metadata = HashMap::new();
metadata.insert("priority".to_string(), "high".to_string());
msg.set_metadata(metadata);

Source

pub fn add_metadata(&mut self, key: String, value: String)

Add a single metadata key-value pair (Version 3 feature)

§Arguments

key - Metadata key
value - Metadata value

Source

pub fn get_metadata(&self) -> Option<&HashMap<String, String>>

Get metadata reference (Version 3 feature)

§Returns

Optional reference to metadata HashMap

Source

pub fn clear_metadata(&mut self)

Remove metadata and optionally downgrade to Version 2

Source

pub fn encode(&self) -> Result<Vec<u8>>

Encode the complete message to bytes

Message format is determined by the presence of extended_header and metadata fields, NOT by the version field, as version information may be unreliable.

Format without Extended Header: Header (58) + Content Format with Extended Header: Header (58) + ExtHdrSize (2) + ExtHdr (var) + Content + Metadata (var)

Extended Header Size field:

0: No extended header present, content follows immediately after the size field
0: Extended header present, value indicates the size (including this field)

Metadata format (when present):

MetadataSize (2 bytes, big-endian)
For each pair:
- KeySize (2 bytes)
- Key (KeySize bytes, UTF-8)
- ValueSize (2 bytes)
- Value (ValueSize bytes, UTF-8)

§Returns

Complete message as byte vector

Source

pub fn decode(data: &[u8]) -> Result<Self>

Decode a complete message from bytes with CRC verification

Automatically detects Extended Header presence based on the extended_header_size field, NOT the version field, as version information may be unreliable.

§Arguments

data - Byte slice containing the complete message

§Returns

Decoded message or error

Source

pub fn decode_with_options(data: &[u8], verify_crc: bool) -> Result<Self>

Decode a complete message from bytes with optional CRC verification

Allows skipping CRC verification for performance in trusted environments.

§Arguments

data - Byte slice containing the complete message
verify_crc - Whether to verify CRC (true = verify, false = skip)

§Returns

Decoded message or error

§Safety

Disabling CRC verification (verify_crc = false) should only be done in trusted environments where data corruption is unlikely (e.g., loopback, local network). Using this in production over unreliable networks may lead to silent data corruption.

§Examples

// Decode with CRC verification (recommended)
let msg = IgtlMessage::<TransformMessage>::decode_with_options(&data, true)?;

// Decode without CRC verification (use with caution)
let msg_fast = IgtlMessage::<TransformMessage>::decode_with_options(&data, false)?;