Enum Message

pub enum Message<'a> {
    Alive {
        options: MessageOptions<'a>,
    },
    ControllerAction {
        controller_id: ID,
        action_id: ActionID,
        timestamp: DateTime<FixedOffset>,
        options: MessageOptions<'a>,
    },
    RequestControllersList {
        controller_id: Option<ID>,
        options: MessageOptions<'a>,
    },
    ControllersList {
        data: IndexMap<ID, Controller<'a>>,
        options: MessageOptions<'a>,
    },
    ControllerStatus {

        controller_id: ID,
        display_name: Option<Box<TextName<'a>>>,
        is_disconnected: Option<bool>,
        op_mode: Option<OpMode>,
        job_mode: Option<JobMode>,
        alarm: Option<Box<KeyValuePair<TextID<'a>, bool>>>,
        audit: Option<Box<KeyValuePair<TextID<'a>, R32>>>,
        variable: Option<Box<KeyValuePair<TextID<'a>, R32>>>,
        operator_id: Option<Option<ID>>,
        operator_name: Option<Option<Box<TextName<'a>>>>,
        job_card_id: Option<Option<Box<TextName<'a>>>>,
        mold_id: Option<Option<Box<TextName<'a>>>>,
        state: StateValues<'a>,
        controller: Option<Box<Controller<'a>>>,
        options: MessageOptions<'a>,
    
},
    CycleData {
        controller_id: ID,
        data: IndexMap<TextID<'a>, R32>,
        timestamp: DateTime<FixedOffset>,
        state: StateValues<'a>,
        options: MessageOptions<'a>,
    },
    RequestJobCardsList {
        controller_id: ID,
        options: MessageOptions<'a>,
    },
    JobCardsList {
        controller_id: ID,
        data: IndexMap<TextName<'a>, JobCard<'a>>,
        options: MessageOptions<'a>,
    },
    Join {
        org_id: Option<TextID<'a>>,
        version: TextID<'a>,
        password: &'a str,
        language: Language,
        filter: Filters,
        options: MessageOptions<'a>,
    },
    JoinResponse {
        result: u32,
        level: Option<u32>,
        message: Option<Box<Cow<'a, str>>>,
        options: MessageOptions<'a>,
    },
    RequestMoldData {
        controller_id: ID,
        options: MessageOptions<'a>,
    },
    MoldData {
        controller_id: ID,
        data: IndexMap<TextID<'a>, R32>,
        timestamp: DateTime<FixedOffset>,
        state: StateValues<'a>,
        options: MessageOptions<'a>,
    },
    ReadMoldData {
        controller_id: ID,
        field: Option<TextID<'a>>,
        options: MessageOptions<'a>,
    },
    MoldDataValue {
        controller_id: ID,
        field: TextID<'a>,
        value: R32,
        options: MessageOptions<'a>,
    },
    LoginOperator {
        controller_id: ID,
        password: &'a str,
        options: MessageOptions<'a>,
    },
    OperatorInfo {
        controller_id: ID,
        operator_id: Option<ID>,
        name: TextName<'a>,
        password: TextName<'a>,
        level: u8,
        options: MessageOptions<'a>,
    },
}

All Open Protocol message types.

See this document for details.

Variants

Alive

The ALIVE message, sent periodically as the keep-alive mechanism.

Fields

options: MessageOptions<'a>

Message configuration options.

ControllerAction

The CNTRLER_ACTION message, sent by the server whenever the current action of a controller changes.

Fields

controller_id: ID

Unique ID of the controller.

action_id: ActionID

Unique action code.

See this document for details.

timestamp: DateTime<FixedOffset>

Time-stamp of the event.

options: MessageOptions<'a>

Message configuration options.

RequestControllersList

The REQ_CNTRLER_LIST message, sent to the server to request a list of controllers (i.e. machines) within the user’s organization.

Response

The Server should reply with a ControllersList message.

Fields

controller_id: Option<ID>

Unique ID of the controller to request.

If omitted, all controllers of the user’s organization will be returned.

options: MessageOptions<'a>

Message configuration options.

ControllersList

The RESP_CNTRLER_LIST message, sent by the server in response to a RequestControllersList message.

Fields

data: IndexMap<ID, Controller<'a>>

List of controllers requested by a previous RequestControllersList message.

Each controller data structure contains the last-known values of the controller’s state.

options: MessageOptions<'a>

Message configuration options.

ControllerStatus

The UPD_CNTRLER message, sent by the server whenever the status of a connected controller changes.

Only the changed fields will be set, with other fields/properties being set to None as they are not relevant.

Fields

controller_id: ID

Unique ID of the controller.

display_name: Option<Box<TextName<'a>>>

Human-friendly name for display (or None if not relevant).

is_disconnected: Option<bool>

If true, the controller has disconnected from the iChen® Server.

op_mode: Option<OpMode>

Current operation mode of the controller (or None if not relevant).

job_mode: Option<JobMode>

Current job mode of the controller (or None if not relevant).

alarm: Option<Box<KeyValuePair<TextID<'a>, bool>>>

State of an alarm (if any) on the controller (or None if not relevant).

See this document for valid alarm codes.

audit: Option<Box<KeyValuePair<TextID<'a>, R32>>>

Change of a setting (if any) on the controller for audit trail purpose (or None if not relevant).

variable: Option<Box<KeyValuePair<TextID<'a>, R32>>>

Change of a variable (if any) on the controller (or None if not relevant).

operator_id: Option<Option<ID>>

Unique ID of the current logged-on user, Some(None) if a user has logged out (or None if not relevant).

operator_name: Option<Option<Box<TextName<'a>>>>

Name of the current logged-on user, Some(None) if the current user has no name (or None if not relevant).

job_card_id: Option<Option<Box<TextName<'a>>>>

Unique ID of the current job card loaded, Some(None) if no job card is currently loaded (or None if not relevant).

mold_id: Option<Option<Box<TextName<'a>>>>

Unique ID of the current mold data set loaded, Some(None) if no mold data set is currently loaded (or None if not relevant).

state: StateValues<'a>

Snapshot of the current known states of the controller.

controller: Option<Box<Controller<'a>>>

A Controller data structure containing the last-known state of the controller.

This field is only sent once by the server as soon as a new controller has connected to the network. All subsequent messages have this field set to None.

If this field is not None, then all other info fields should be None or have values equal to the matching fields in controller.

options: MessageOptions<'a>

Message configuration options.

CycleData

The CYCLE_DATA message, sent by the server at the end of each machine cycle.

Fields

controller_id: ID

Unique ID of the controller.

data: IndexMap<TextID<'a>, R32>

A data dictionary containing a set of cycle data.

See this document for examples.

timestamp: DateTime<FixedOffset>

Time-stamp of the event.

state: StateValues<'a>

Snapshot of the current known states of the controller.

options: MessageOptions<'a>

Message configuration options.

RequestJobCardsList

The REQ_JOBCARDS_LIST message, sent by the server when a connected controller requests a list of job cards.

Action Required

The user should send a JobCardsList message to the Server as a reply.

Fields

controller_id: ID

Unique ID of the controller.

options: MessageOptions<'a>

Message configuration options.

JobCardsList

The RESP_JOBSLIST message, sent to the server in response to a RequestJobCardsList message.

Fields

controller_id: ID

Unique ID of the controller.

data: IndexMap<TextName<'a>, JobCard<'a>>

A data dictionary containing a set of JobCard data structures.

options: MessageOptions<'a>

Message configuration options.

Join

The JOIN message, sent to log onto the server.

Response

The Server should reply with a JoinResponse message.

Fields

org_id: Option<TextID<'a>>

Organization ID (if any).

version: TextID<'a>

The maximum protocol version supported, in the format x.x.x.x.

The current protocol version implemented is in the constant PROTOCOL_VERSION.

password: &'a str

Password to log onto the server.

language: Language

Language encoding.

filter: Filters

A collection of Filter values containing what type(s) of messages to receive.

options: MessageOptions<'a>

Message configuration options.

JoinResponse

The RESP_JOIN message, sent by the Server in response to a Join message.

Fields

result: u32

Result code, >= 100 indicates success.

level: Option<u32>

The allowed access level for this client.

message: Option<Box<Cow<'a, str>>>

A message (mostly likely an error message in case of failure), if any.

options: MessageOptions<'a>

Message configuration options.

RequestMoldData

The REQ_MOLD message, sent to the server to request the set of mold settings data of a controller.

Response

The Server should reply with a MoldData message.

Fields

controller_id: ID

Unique ID of the controller.

options: MessageOptions<'a>

Message configuration options.

MoldData

The RESP_MOLD message, sent by the server in response to a RequestMoldData message or a ReadMoldData message with field set to None (meaning read all).

Fields

controller_id: ID

Unique ID of the controller.

data: IndexMap<TextID<'a>, R32>

A data dictionary containing a set of mold settings.

timestamp: DateTime<FixedOffset>

Time-stamp of the event.

state: StateValues<'a>

Snapshot of the current known states of the controller.

options: MessageOptions<'a>

Message configuration options.

ReadMoldData

The READ_MOLD_DATA message, sent to the server to read the current value of a particular mold setting.

The server keeps a cache of the states of all mold settings for each controller. The value returned is based on the server cache. No command is sent to controller to poll the latest value.

Response

The Server should reply with a MoldData message if field is None, or a MoldDataValue message.

Fields

controller_id: ID

Unique ID of the controller.

field: Option<TextID<'a>>

Name of the mold setting to read, None for all.

options: MessageOptions<'a>

Message configuration options.

MoldDataValue

The RESP_MOLD_DATA_VALUE message, sent by the server in response to a ReadMoldData message.

Fields

controller_id: ID

Unique ID of the controller.

field: TextID<'a>

Name of the mold setting to read.

value: R32

Current cached value of the mold setting.

options: MessageOptions<'a>

Message configuration options.

LoginOperator

The REQ_PWD_LEVEL message, sent by server when a connected controller attempts to authenticate and authorize a user password.

Action Required

The user should send an OperatorInfo message to the Server as a reply.

Fields

controller_id: ID

Unique ID of the controller.

password: &'a str

User password.

options: MessageOptions<'a>

Message configuration options.

OperatorInfo

The RESP_PWD_LEVEL message, sent to the server in response to a LoginOperator message.

Fields

controller_id: ID

Unique ID of the controller.

operator_id: Option<ID>

Unique ID of the authenticated user.

name: TextName<'a>

Name of the user.

password: TextName<'a>

User password.

level: u8

Allowed access level for the user.

Valid values are from 0 to MAX_OPERATOR_LEVEL (usually 10).

options: MessageOptions<'a>

Message configuration options.

Implementations

impl<'a> Message<'a>

pub const PROTOCOL_VERSION: &'static str = "4.0"

Current protocol version: 4.0.

pub const DEFAULT_LANGUAGE: Language = Language::EN

Default language to use: EN (English).

pub const MAX_OPERATOR_LEVEL: u8 = 10u8

Maximum operator level: 10.

pub fn parse_from_json_str(json: &'a str) -> Result<'a, Self>

Parse a JSON string into a Message.

Errors

Return Err(OpenProtocolError) if there is an error during parsing.

pub fn to_json_str(&self) -> Result<'_, String>

Validate all the fields in the Message, then serialize it into a JSON string.

Errors

Return Err(OpenProtocolError) if there is an error.

Examples

let msg = Message::try_new_join_with_org("MyPassword", Filters::Status + Filters::Cycle, "MyCompany")?;
assert_eq!(
    r#"{"$type":"Join","orgId":"MyCompany","version":"4.0","password":"MyPassword","language":"EN","filter":"Status, Cycle","sequence":1}"#,
    msg.to_json_str()?
);

pub fn new_alive() -> Self

Create an ALIVE message.

Examples

let msg = Message::new_alive();
if let Message::Alive { options } = msg {
    assert_eq!(1, options.sequence());
    assert_eq!(0, options.priority());
    assert_eq!(None, options.id());
} else {
    panic!();
}

pub fn new_join(password: &'a str, filter: Filters) -> Self

Create a JOIN message with default language and protocol version.

The default language is DEFAULT_LANGUAGE (usually EN).

The default protocol version is given in PROTOCOL_VERSION.

Examples

let msg = Message::new_join("MyPassword", Filters::Status + Filters::Cycle);
if let Message::Join { org_id, version, password, language, filter, options } = msg {
    assert_eq!(None, org_id);
    assert_eq!(Message::PROTOCOL_VERSION, &version);
    assert_eq!("MyPassword", password);
    assert_eq!(Message::DEFAULT_LANGUAGE, language);
    assert_eq!(Filters::Status + Filters::Cycle, filter);
    assert_eq!(1, options.sequence());
    assert_eq!(0, options.priority());
    assert_eq!(None, options.id());
} else {
    panic!();
}

pub fn try_new_join_with_org( password: &'a str, filter: Filters, org: &'a str, ) -> Result<Self, String>

Create a JOIN message with non-default organization.

Errors

Returns Err(String) if the organization ID is empty or all-whitespace or contains any non-ASCII characters.

Error Examples

match Message::try_new_join_with_org("MyPassword", Filters::Status + Filters::Cycle, "") {
    Err(e) => assert_eq!("invalid value: a non-empty, non-whitespace, all-ASCII string required", e),
    _ => ()
}

Examples

let msg = Message::try_new_join_with_org("MyPassword", Filters::Status + Filters::Cycle, "MyCompany")?;

if let Message::Join { org_id, version, password, language, filter, options } = msg {
    assert_eq!(Some("MyCompany"), org_id.as_ref().map(|x| x.get()));
    assert_eq!(Message::PROTOCOL_VERSION, version.get());
    assert_eq!("MyPassword", password);
    assert_eq!(Message::DEFAULT_LANGUAGE, language);
    assert_eq!(Filters::Status + Filters::Cycle, filter);
    assert_eq!(1, options.sequence());
    assert_eq!(0, options.priority());
    assert_eq!(None, options.id());
} else {
    panic!();
}

pub fn id(&self) -> Option<&str>

Get the optional message ID from the options field.

pub fn sequence(&self) -> u64

Get the message sequence number from the options field.

pub fn priority(&self) -> i32

Get the message priority from the options field.

pub fn validate(&self) -> Result<'a, ()>

Validate the Message data structure.

Errors

Returns Err(OpenProtocolError) if some fields in the Message are not valid.

Examples

let msg = Message::ControllerStatus {
    controller_id: ID::from_u32(12345),
    display_name: None,
    is_disconnected: None,
    op_mode: None,
    job_mode: None,
    job_card_id: Some(None),
    mold_id: Some(Some(Box::new(TextName::new_from_str("Test-123").unwrap()))),     // Value is "Test-123"
    operator_id: None,
    operator_name: None,
    variable: None,
    audit: None,
    alarm: None,
    controller: None,
    state: StateValues::try_new_with_all(
        OpMode::Automatic,
        JobMode::ID02,
        None,
        None,
        Some("Test-FooBar"),    // Notice that this state value should be "Test-123"
    ).unwrap(),
    options: Default::default(),
};

// Validation should error because `state.mold_id` is not the same as the `mold_id` field.
assert_eq!(
    Err(Error::InconsistentState("mold_id")),
    msg.validate()
);

Trait Implementations

impl<'a> Clone for Message<'a>

fn clone(&self) -> Message<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Message<'a>

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

Formats the value using the given formatter.

impl<'de: 'a, 'a> Deserialize<'de> for Message<'a>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'a> Serialize for Message<'a>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.