Debian Codegraph @

.cargo/vendor/image/src/hooks.rs

raw
1 //! This module provides a way to register decoding hooks for image formats not directly supported
2 //! by this crate.
3
4 use std::{
5 collections::HashMap,
6 ffi::{OsStr, OsString},
7 io::{BufRead, BufReader, Read, Seek},
8 sync::RwLock,
9 };
10
11 use crate::{ImageDecoder, ImageResult};
12
13 pub(crate) trait ReadSeek: Read + Seek {}
14 impl<T: Read + Seek> ReadSeek for T {}
15
16 pub(crate) static DECODING_HOOKS: RwLock<Option<HashMap<OsString, DecodingHook>>> =
17 RwLock::new(None);
18
19 pub(crate) type DetectionHook = (&'static [u8], &'static [u8], OsString);
20 pub(crate) static GUESS_FORMAT_HOOKS: RwLock<Vec<DetectionHook>> = RwLock::new(Vec::new());
21
22 /// A wrapper around a type-erased trait object that implements `Read` and `Seek`.
23 pub struct GenericReader<'a>(pub(crate) BufReader<Box<dyn ReadSeek + 'a>>);
24 impl Read for GenericReader<'_> {
25 fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
26 self.0.read(buf)
27 }
28 fn read_vectored(&mut self, bufs: &mut [std::io::IoSliceMut<'_>]) -> std::io::Result<usize> {
29 self.0.read_vectored(bufs)
30 }
31 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> std::io::Result<usize> {
32 self.0.read_to_end(buf)
33 }
34 fn read_to_string(&mut self, buf: &mut String) -> std::io::Result<usize> {
35 self.0.read_to_string(buf)
36 }
37 fn read_exact(&mut self, buf: &mut [u8]) -> std::io::Result<()> {
38 self.0.read_exact(buf)
39 }
40 }
41 impl BufRead for GenericReader<'_> {
42 fn fill_buf(&mut self) -> std::io::Result<&[u8]> {
43 self.0.fill_buf()
44 }
45 fn consume(&mut self, amt: usize) {
46 self.0.consume(amt)
47 }
48 fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> std::io::Result<usize> {
49 self.0.read_until(byte, buf)
50 }
51 fn read_line(&mut self, buf: &mut String) -> std::io::Result<usize> {
52 self.0.read_line(buf)
53 }
54 }
55 impl Seek for GenericReader<'_> {
56 fn seek(&mut self, pos: std::io::SeekFrom) -> std::io::Result<u64> {
57 self.0.seek(pos)
58 }
59 fn rewind(&mut self) -> std::io::Result<()> {
60 self.0.rewind()
61 }
62 fn stream_position(&mut self) -> std::io::Result<u64> {
63 self.0.stream_position()
64 }
65
66 // TODO: Add `seek_relative` once MSRV is at least 1.80.0
67 }
68
69 /// A function to produce an `ImageDecoder` for a given image format.
70 pub type DecodingHook =
71 Box<dyn for<'a> Fn(GenericReader<'a>) -> ImageResult<Box<dyn ImageDecoder + 'a>> + Send + Sync>;
72
73 /// Register a new decoding hook or returns false if one already exists for the given format.
74 pub fn register_decoding_hook(extension: OsString, hook: DecodingHook) -> bool {
75 let mut hooks = DECODING_HOOKS.write().unwrap();
76 if hooks.is_none() {
77 *hooks = Some(HashMap::new());
78 }
79 match hooks.as_mut().unwrap().entry(extension) {
80 std::collections::hash_map::Entry::Vacant(entry) => {
81 entry.insert(hook);
82 true
83 }
84 std::collections::hash_map::Entry::Occupied(_) => false,
85 }
86 }
87
88 /// Returns whether a decoding hook has been registered for the given format.
89 pub fn decoding_hook_registered(extension: &OsStr) -> bool {
90 DECODING_HOOKS
91 .read()
92 .unwrap()
93 .as_ref()
94 .map(|hooks| hooks.contains_key(extension))
95 .unwrap_or(false)
96 }
97
98 /// Registers a format detection hook.
99 ///
100 /// The signature field holds the magic bytes from the start of the file that must be matched to
101 /// detect the format. The mask field is optional and can be used to specify which bytes in the
102 /// signature should be ignored during the detection.
103 ///
104 /// # Examples
105 ///
106 /// ## Using the mask to ignore some bytes
107 ///
108 /// ```
109 /// # use image::hooks::register_format_detection_hook;
110 /// // WebP signature is 'riff' followed by 4 bytes of length and then by 'webp'.
111 /// // This requires a mask to ignore the length.
112 /// register_format_detection_hook("webp".into(),
113 /// &[b'r', b'i', b'f', b'f', 0, 0, 0, 0, b'w', b'e', b'b', b'p'],
114 /// Some(&[0xff, 0xff, 0xff, 0xff, 0, 0, 0, 0, 0xff, 0xff, 0xff, 0xff]),
115 /// );
116 /// ```
117 ///
118 /// ## Multiple signatures
119 ///
120 /// ```
121 /// # use image::hooks::register_format_detection_hook;
122 /// // JPEG XL has two different signatures: https://en.wikipedia.org/wiki/JPEG_XL
123 /// // This function should be called twice to register them both.
124 /// register_format_detection_hook("jxl".into(), &[0xff, 0x0a], None);
125 /// register_format_detection_hook("jxl".into(),
126 /// &[0x00, 0x00, 0x00, 0x0c, 0x4a, 0x58, 0x4c, 0x20, 0x0d, 0x0a, 0x87, 0x0a], None,
127 /// );
128 /// ```
129 ///
130 pub fn register_format_detection_hook(
131 extension: OsString,
132 signature: &'static [u8],
133 mask: Option<&'static [u8]>,
134 ) {
135 GUESS_FORMAT_HOOKS
136 .write()
137 .unwrap()
138 .push((signature, mask.unwrap_or(&[]), extension));
139 }