Enum IgtlError 

pub enum IgtlError {
    InvalidHeader(String),
    CrcMismatch {
        expected: u64,
        actual: u64,
    },
    UnknownMessageType(String),
    InvalidSize {
        expected: usize,
        actual: usize,
    },
    Io(Error),
    Utf8(FromUtf8Error),
    InvalidTimestamp(String),
    BodyTooLarge {
        size: usize,
        max: usize,
    },
}

OpenIGTLink protocol error types

All operations in this library return Result<T, IgtlError> to provide explicit error handling.

Variants

InvalidHeader(String)

Invalid header format or content

This error occurs when:

• Header version field is not 1, 2, or 3
• Message type contains invalid characters (non-ASCII or control characters)
• Device name contains invalid characters
• Header size doesn’t match expected 58 bytes

Example

let err = IgtlError::InvalidHeader("Version must be 1, 2, or 3".to_string());

CrcMismatch

CRC checksum mismatch

This error occurs when:

• Network transmission corrupted the message data
• Message was tampered with during transmission
• Sender and receiver use incompatible CRC implementations
• Hardware-level data corruption (rare)

When this error occurs, the message should be discarded and the sender should retransmit.

Example

let err = IgtlError::CrcMismatch {
    expected: 0x1234567890abcdef,
    actual: 0x1234567890abcdee,
};

Fields

expected: u64

Expected CRC value calculated from message body

actual: u64

Actual CRC value received in message header

UnknownMessageType(String)

Unknown or unsupported message type

This error occurs when:

• Receiving a message type not implemented in this library
• Message type field contains invalid characters
• Sender uses a custom/proprietary message type
• Protocol version mismatch (e.g., OpenIGTLink v4 message on v3 receiver)

The 21 standard message types are supported. Custom message types will trigger this error unless explicitly added.

Example

let err = IgtlError::UnknownMessageType("CUSTOM_MSG".to_string());

InvalidSize

Invalid message size

This error occurs when:

• Message body size doesn’t match the size declared in header
• Required fields are missing in message body
• Array sizes in message don’t match declared counts
• Message is truncated during transmission

Example

let err = IgtlError::InvalidSize {
    expected: 100,
    actual: 95,
};

Fields

expected: usize

Expected size in bytes based on message format

actual: usize

Actual size in bytes received or parsed

Io(Error)

I/O error occurred during network communication

This error wraps standard library I/O errors and occurs when:

• TCP connection failed or was refused
• Connection lost during transmission (broken pipe)
• Network timeout occurred
• Socket was closed by peer
• Insufficient permissions to bind to port

Common scenarios:

• Server not running at specified address
• Firewall blocking the connection
• Network cable unplugged during operation
• Server crashed during communication

Example

let io_err = io::Error::new(io::ErrorKind::ConnectionRefused, "Connection refused");
let err = IgtlError::Io(io_err);

Utf8(FromUtf8Error)

UTF-8 conversion error

This error occurs when:

• Device name or string message contains invalid UTF-8 sequences
• Message was created by non-UTF-8 compliant sender
• Data corruption in text fields

OpenIGTLink string fields should be UTF-8 encoded. This error indicates the sender is not following the specification.

Example

let invalid_bytes = vec![0xFF, 0xFE, 0xFD];
match String::from_utf8(invalid_bytes) {
    Err(e) => {
        let err = IgtlError::Utf8(e);
    }
    _ => {}
}

InvalidTimestamp(String)

Invalid timestamp value

This error occurs when:

• Timestamp nanoseconds field exceeds 10^9 (invalid)
• Timestamp seconds field is negative (if checked)
• Timestamp represents a date far in the future (system time issue)

Example

let err = IgtlError::InvalidTimestamp("Nanoseconds must be < 1000000000".to_string());

BodyTooLarge

Message body size exceeds maximum allowed

This error occurs when:

• Attempting to send a message larger than protocol limit (typically 4GB)
• Image data exceeds reasonable memory limits
• Malformed message header declares impossibly large body size

This protects against memory exhaustion attacks and implementation bugs.

Example

let err = IgtlError::BodyTooLarge {
    size: 5_000_000_000,
    max: 4_294_967_295,
};

Fields

size: usize

Actual body size in bytes

max: usize

Maximum allowed size in bytes

Trait Implementations

impl Debug for IgtlError

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

Formats the value using the given formatter.

impl Display for IgtlError

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

Formats the value using the given formatter.

impl Error for IgtlError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for IgtlError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<FromUtf8Error> for IgtlError

fn from(source: FromUtf8Error) -> Self

Converts to this type from the input type.