realsense_rust/kind/
exception.rs

1//! Possible exception / error types that librealsense2 can produce
2
3use num_derive::{FromPrimitive, ToPrimitive};
4use realsense_sys as sys;
5use std::fmt::{Display, Formatter, Result};
6
7/// Enumeration of possible exception types that can be returned via `rs2_error`
8///
9/// `Rs2Exception` is an enumeration where each variant describes the class of error returned by an
10/// [`rs2_error`](realsense_sys::rs2_error) pointer.
11#[repr(i32)]
12#[derive(FromPrimitive, ToPrimitive, Debug, Clone, Copy, PartialEq, Eq, Hash)]
13pub enum Rs2Exception {
14    /// Unknown error classification.
15    ///
16    /// This is context-dependent. Usually this means that the error isn't a specific class of
17    /// librealsense2 errors (could just be `std::runtime_error` under the hood). You'll need to
18    /// know what API was called at a low-level to be able to trace what this error actually means.
19    Unknown = sys::rs2_exception_type_RS2_EXCEPTION_TYPE_UNKNOWN as i32,
20    /// Error resulted because the device was disconnected.
21    ///
22    /// This can be caused by outside intervention (pulling the plug), by an internal firmware
23    /// error or due to insufficient power to the camera / device.
24    CameraDisconnected = sys::rs2_exception_type_RS2_EXCEPTION_TYPE_CAMERA_DISCONNECTED as i32,
25    /// Error occurred from the underlying OS-specific layer.
26    Backend = sys::rs2_exception_type_RS2_EXCEPTION_TYPE_BACKEND as i32,
27    /// An invalid value was passed to the API.
28    InvalidValue = sys::rs2_exception_type_RS2_EXCEPTION_TYPE_INVALID_VALUE as i32,
29    /// Error resulted because a function precondition was violated.
30    ///
31    /// Usually this means that you tried to call a method before a class was properly initialized
32    /// or configured. E.g. this type of error can occur if you try to wait for frames on a
33    /// pipeline before it is started. We attempt to reduce the number of opportunities where this
34    /// can happen by structuring the types around these constraints at a higher level.
35    WrongApiCallSequence =
36        sys::rs2_exception_type_RS2_EXCEPTION_TYPE_WRONG_API_CALL_SEQUENCE as i32,
37    /// The method you tried to call is not implemented.
38    NotImplemented = sys::rs2_exception_type_RS2_EXCEPTION_TYPE_NOT_IMPLEMENTED as i32,
39    /// Error resulted because the device is in recovery mode
40    ///
41    /// The device might require a firmware update.
42    DeviceInRecoveryMode =
43        sys::rs2_exception_type_RS2_EXCEPTION_TYPE_DEVICE_IN_RECOVERY_MODE as i32,
44    /// Error resulted because of an IO device failure.
45    IoDeviceFailure = sys::rs2_exception_type_RS2_EXCEPTION_TYPE_IO as i32,
46    /// Normally, this exception would not be included, since this just tells us the total number of
47    /// exceptions. HOWEVER, there is a section of the SDK that does return this, which the
48    /// maintainers use when, quote, "If you want to avoid any errors being reported because an
49    /// exception an expected API behavior". We do not know what this means, or why it exists, but
50    /// we include it for completeness.
51    ///
52    /// Reference:
53    /// <https://github.com/IntelRealSense/librealsense/blob/cacc8e701a963a44b49fe51911443797e8b3a517/src/api.h#L438>
54    ///
55    Count = sys::rs2_exception_type_RS2_EXCEPTION_TYPE_COUNT as i32,
56}
57
58impl Display for Rs2Exception {
59    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
60        let s = match self {
61            Rs2Exception::Unknown => "Unknown",
62            Rs2Exception::CameraDisconnected => "CameraDisconnected",
63            Rs2Exception::Backend => "Backend",
64            Rs2Exception::InvalidValue => "InvalidValue",
65            Rs2Exception::WrongApiCallSequence => "WrongAPICallSequence",
66            Rs2Exception::NotImplemented => "NotImplemented",
67            Rs2Exception::DeviceInRecoveryMode => "DeviceInRecoveryMode",
68            Rs2Exception::IoDeviceFailure => "IODeviceFailure",
69            Rs2Exception::Count => "Count (not a real error)",
70        };
71
72        write!(f, "{}", s)
73    }
74}
75
76#[cfg(test)]
77mod tests {
78    use super::*;
79    use num_traits::FromPrimitive;
80
81    #[test]
82    fn all_variants_exist() {
83        for i in 0..sys::rs2_exception_type_RS2_EXCEPTION_TYPE_COUNT as i32 {
84            assert!(
85                Rs2Exception::from_i32(i).is_some(),
86                "Rs2Exception variant for ordinal {} does not exist.",
87                i,
88            );
89        }
90    }
91}
realsense_rust/kind/exception.rs

realsense_rust/kind/
exception.rs
