image4 0.8.2

A no_std-friendly library for parsing and generation of Image4 images written in pure Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

use super::ImageRef;
use crate::{Manifest, Payload, RestoreInfo, Tag};
use alloc::{boxed::Box, vec::Vec};
use der::{
    referenced::{OwnedToRef, RefToOwned},
    Decode, DecodeValue, EncodeValue, FixedTag, Header, Length, Reader, Writer,
};

/// An Image4 image that owns its data.
#[derive(Clone, Debug)]
pub struct Image {
    pub(super) payload: Payload,
    pub(super) manifest: Option<Box<Manifest>>,
    pub(super) restore_info: Option<RestoreInfo>,
}

impl Image {
    /// Creates a new [`Image`] which only contains a payload.
    pub fn new(tag: Tag, builder_string: &str, data: Vec<u8>) -> der::Result<Self> {
        Ok(Self {
            payload: Payload::new(tag, builder_string, data)?,
            manifest: None,
            restore_info: None,
        })
    }

    /// Creates a new image from a payload.
    pub fn from_payload(payload: Payload) -> Self {
        Self {
            payload,
            manifest: None,
            restore_info: None,
        }
    }

    /// Parses a DER encoded payload and creates an [`Image`] that contains it.
    pub fn from_payload_bytes(bytes: &[u8]) -> der::Result<Self> {
        Ok(Self {
            payload: Payload::from_der(bytes)?,
            manifest: None,
            restore_info: None,
        })
    }

    /// Parses a DER encoded Image4 manifest and stores the parsed [`Manifest`] in the image.
    pub fn parse_manifest(&mut self, bytes: &[u8]) -> der::Result<()> {
        self.manifest = Some(Box::new(Manifest::from_der(bytes)?));

        Ok(())
    }

    /// Returns an immutable reference to the payload of the image.
    pub fn payload(&self) -> &Payload {
        &self.payload
    }

    /// Returns a mutable reference to the payload of the image.
    pub fn payload_mut(&mut self) -> &mut Payload {
        &mut self.payload
    }

    /// Returns an immutable reference to the manifest of the image if any.
    pub fn manifest(&self) -> Option<&Manifest> {
        self.manifest.as_deref()
    }

    /// Returns a mutable reference to the manifest of the image if any.
    pub fn manifest_mut(&mut self) -> Option<&mut Manifest> {
        self.manifest.as_deref_mut()
    }

    /// Sets a new manifest for the image and returns the old one if any.
    pub fn set_manifest(&mut self, manifest: Option<Box<Manifest>>) -> Option<Box<Manifest>> {
        core::mem::replace(&mut self.manifest, manifest)
    }

    /// Returns an immutable reference to the restore info of the image if any.
    pub fn restore_info(&self) -> Option<&RestoreInfo> {
        self.restore_info.as_ref()
    }

    /// Returns a mutable reference to the restore info of the image if any.
    pub fn restore_info_mut(&mut self) -> Option<&mut RestoreInfo> {
        self.restore_info.as_mut()
    }

    /// Sets restore info of the image.
    pub fn set_restore_info(&mut self, restore_info: Option<RestoreInfo>) {
        self.restore_info = restore_info;
    }

    /// Decodes the part of an image after the magic string.
    ///
    /// May be used when it is required to first identify what kind of buffer you're looking at by
    /// checking the magic string.
    pub fn decode_after_magic<'a, R: Reader<'a>>(decoder: &mut R) -> der::Result<Self> {
        ImageRef::decode_after_magic(decoder).map(Into::into)
    }
}

impl FixedTag for Image {
    const TAG: der::Tag = der::Tag::Sequence;
}

impl<'a> DecodeValue<'a> for Image {
    fn decode_value<R: Reader<'a>>(reader: &mut R, header: Header) -> der::Result<Self> {
        ImageRef::decode_value(reader, header).map(Into::into)
    }
}

impl EncodeValue for Image {
    fn value_len(&self) -> der::Result<Length> {
        ImageRef::from(self).value_len()
    }

    fn encode_value(&self, encoder: &mut impl Writer) -> der::Result<()> {
        ImageRef::from(self).encode_value(encoder)
    }
}

impl From<&'_ ImageRef<'_>> for Image {
    fn from(value: &'_ ImageRef<'_>) -> Self {
        Self {
            payload: value.payload.ref_to_owned(),
            manifest: value.manifest.as_ref().map(|m| Box::new(m.ref_to_owned())),
            restore_info: value.restore_info.as_ref().map(RefToOwned::ref_to_owned),
        }
    }
}

impl From<ImageRef<'_>> for Image {
    fn from(value: ImageRef<'_>) -> Self {
        (&value).into()
    }
}

impl OwnedToRef for Image {
    type Borrowed<'a> = ImageRef<'a>;

    fn owned_to_ref(&self) -> Self::Borrowed<'_> {
        self.into()
    }
}