Skip to main content

spodes_rs/service/
error.rs

1//! Error-reporting APDUs (IEC 62056-5-3): the EXCEPTION-RESPONSE used with LN
2//! referencing and the ConfirmedServiceError used with SN referencing.
3//!
4//! EXCEPTION-RESPONSE (`[216]`, tag 0xD8) is returned when a request cannot be
5//! served for a reason not tied to a specific object (association not
6//! established, PDU too long, deciphering error, …). ConfirmedServiceError
7//! (`[14]`, tag 0x0E) reports the same class of failure in the SN world and, most
8//! commonly, an InitiateRequest that the server cannot accept.
9
10use super::{tag, ServiceError};
11
12/// `state-error` values of an EXCEPTION-RESPONSE.
13pub mod state_error {
14    /// The service is not allowed in the current state.
15    pub const SERVICE_NOT_ALLOWED: u8 = 1;
16    /// The service is not known.
17    pub const SERVICE_UNKNOWN: u8 = 2;
18}
19
20/// `service-error` values of an EXCEPTION-RESPONSE.
21pub mod service_error {
22    /// The operation is not possible.
23    pub const OPERATION_NOT_POSSIBLE: u8 = 1;
24    /// The service is not supported.
25    pub const SERVICE_NOT_SUPPORTED: u8 = 2;
26    /// Other reason.
27    pub const OTHER_REASON: u8 = 3;
28    /// The request PDU is too long.
29    pub const PDU_TOO_LONG: u8 = 4;
30    /// A deciphering error occurred.
31    pub const DECIPHERING_ERROR: u8 = 5;
32    /// The invocation counter was invalid (replay protection).
33    pub const INVOCATION_COUNTER_ERROR: u8 = 6;
34}
35
36/// An EXCEPTION-RESPONSE APDU.
37///
38/// The optional `operation` field (present only with `invocation-counter-error`,
39/// carrying the lowest acceptable invocation counter) is not modelled.
40#[derive(Debug, Clone, PartialEq, Eq)]
41pub struct ExceptionResponse {
42    /// The state-error code (see [`state_error`]).
43    pub state_error: u8,
44    /// The service-error code (see [`service_error`]).
45    pub service_error: u8,
46}
47
48impl ExceptionResponse {
49    /// Encodes the APDU: `D8 <state-error> <service-error>`.
50    pub fn encode(&self) -> Vec<u8> {
51        vec![tag::EXCEPTION_RESPONSE, self.state_error, self.service_error]
52    }
53
54    /// Decodes the APDU.
55    pub fn decode(bytes: &[u8]) -> Result<ExceptionResponse, ServiceError> {
56        if bytes.first() != Some(&tag::EXCEPTION_RESPONSE) {
57            return Err(ServiceError::UnexpectedTag(*bytes.first().unwrap_or(&0)));
58        }
59        let state_error = *bytes.get(1).ok_or(ServiceError::Truncated)?;
60        let service_error = *bytes.get(2).ok_or(ServiceError::Truncated)?;
61        Ok(ExceptionResponse { state_error, service_error })
62    }
63}
64
65/// ConfirmedServiceError CHOICE selector (which service failed).
66pub mod service {
67    /// `initiateError` — the InitiateRequest failed.
68    pub const INITIATE_ERROR: u8 = 1;
69    /// `getStatus`.
70    pub const GET_STATUS: u8 = 2;
71    /// `read`.
72    pub const READ: u8 = 5;
73    /// `write`.
74    pub const WRITE: u8 = 6;
75}
76
77/// ServiceError CHOICE selector (the error category).
78pub mod category {
79    /// `application-reference`.
80    pub const APPLICATION_REFERENCE: u8 = 1;
81    /// `hardware-resource`.
82    pub const HARDWARE_RESOURCE: u8 = 2;
83    /// `initiate` — an InitiateRequest error.
84    pub const INITIATE: u8 = 6;
85    /// `access`.
86    pub const ACCESS: u8 = 9;
87}
88
89/// A ConfirmedServiceError APDU: a nested CHOICE of `service`, error `category`
90/// and the final enumerated `value`.
91#[derive(Debug, Clone, PartialEq, Eq)]
92pub struct ConfirmedServiceError {
93    /// Which service failed (see [`service`]).
94    pub service: u8,
95    /// The error category (see [`category`]).
96    pub category: u8,
97    /// The enumerated error value within the category.
98    pub value: u8,
99}
100
101impl ConfirmedServiceError {
102    /// Encodes the APDU: `0E <service> <category> <value>`.
103    pub fn encode(&self) -> Vec<u8> {
104        vec![tag::CONFIRMED_SERVICE_ERROR, self.service, self.category, self.value]
105    }
106
107    /// Decodes the APDU.
108    pub fn decode(bytes: &[u8]) -> Result<ConfirmedServiceError, ServiceError> {
109        if bytes.first() != Some(&tag::CONFIRMED_SERVICE_ERROR) {
110            return Err(ServiceError::UnexpectedTag(*bytes.first().unwrap_or(&0)));
111        }
112        Ok(ConfirmedServiceError {
113            service: *bytes.get(1).ok_or(ServiceError::Truncated)?,
114            category: *bytes.get(2).ok_or(ServiceError::Truncated)?,
115            value: *bytes.get(3).ok_or(ServiceError::Truncated)?,
116        })
117    }
118}
119
120#[cfg(test)]
121mod tests {
122    use super::*;
123
124    #[test]
125    fn exception_response_round_trips() {
126        // Association not established: service-not-allowed / operation-not-possible.
127        let ex = ExceptionResponse {
128            state_error: state_error::SERVICE_NOT_ALLOWED,
129            service_error: service_error::OPERATION_NOT_POSSIBLE,
130        };
131        assert_eq!(ex.encode(), vec![0xD8, 0x01, 0x01]);
132        assert_eq!(ExceptionResponse::decode(&ex.encode()).unwrap(), ex);
133    }
134
135    #[test]
136    fn confirmed_service_error_matches_reference_bytes() {
137        // IEC 61334-6 Example 3: 0E 01 06 02 — initiateError / initiate /
138        // incompatible-conformance.
139        let e = ConfirmedServiceError { service: service::INITIATE_ERROR, category: category::INITIATE, value: 2 };
140        assert_eq!(e.encode(), vec![0x0E, 0x01, 0x06, 0x02]);
141        assert_eq!(ConfirmedServiceError::decode(&e.encode()).unwrap(), e);
142    }
143}