pdfium_render/error.rs
1//! Defines the [PdfiumError] enum, used to wrap Pdfium errors as `Err` values.
2
3use crate::bindgen::{
4 FPDF_ERR_FILE, FPDF_ERR_FORMAT, FPDF_ERR_PAGE, FPDF_ERR_PASSWORD, FPDF_ERR_SECURITY, FPDF_ERR_UNKNOWN,
5};
6use std::error::Error;
7use std::ffi::IntoStringError;
8use std::fmt::{Display, Formatter, Result};
9use std::num::ParseIntError;
10
11#[cfg(target_arch = "wasm32")]
12use wasm_bindgen::JsValue;
13
14#[cfg(doc)]
15use crate::pdfium::Pdfium;
16
17/// A wrapped internal library error from Pdfium's `FPDF_ERR_*` constant values.
18///
19/// Pdfium only provides detailed internal error information for document loading functions.
20/// All other functions in the Pdfium API return a value indicating success or failure,
21/// but otherwise detailed error information for failed API calls is not available. In these
22/// cases, an error value of [PdfiumInternalError::Unknown] will be returned.
23#[derive(Debug)]
24pub enum PdfiumInternalError {
25 /// The document could not be loaded due to a file system error.
26 FileError = FPDF_ERR_FILE as isize,
27
28 /// The document could not be loaded due to a format parsing error.
29 FormatError = FPDF_ERR_FORMAT as isize,
30
31 /// The document could not be loaded because the wrong password was supplied.
32 PasswordError = FPDF_ERR_PASSWORD as isize,
33
34 /// The document could not be loaded because of the document's security settings.
35 SecurityError = FPDF_ERR_SECURITY as isize,
36
37 /// The page could not be loaded due to an internal error.
38 PageError = FPDF_ERR_PAGE as isize,
39
40 /// A generic error value returned in all other unhandled situations.
41 Unknown = FPDF_ERR_UNKNOWN as isize,
42}
43
44/// A wrapper enum for handling Pdfium errors as standard Rust `Err` values.
45#[derive(Debug)]
46pub enum PdfiumError {
47 /// The Pdfium WASM module has not been initialized.
48 ///
49 /// It is essential that the exported `initialize_pdfium_render()` function be called
50 /// from Javascript _before_ calling any `pdfium-render` function from within your Rust code.
51 /// See: <https://github.com/ajrcarey/pdfium-render/blob/master/examples/index.html>
52 #[cfg(target_arch = "wasm32")]
53 PdfiumWasmModuleNotInitialized,
54
55 /// An error occurred during dynamic binding to an external Pdfium library.
56 #[cfg(not(target_arch = "wasm32"))]
57 LoadLibraryError(libloading::Error),
58
59 /// An error occurred during dynamic binding while converting an FPDF_* function name
60 /// to a C string. The wrapped string value contains more information.
61 #[cfg(not(target_arch = "wasm32"))]
62 LoadLibraryFunctionNameError(String),
63
64 /// The global library bindings have already been initialized based on the
65 /// first call to [Pdfium::new]. Bindings initialization can only occur once
66 /// during the lifetime of the program.
67 PdfiumLibraryBindingsAlreadyInitialized,
68
69 UnrecognizedPath,
70 PdfClipPathSegmentIndexOutOfBounds,
71 PageIndexOutOfBounds,
72 LinkIndexOutOfBounds,
73 UnknownBitmapFormat,
74 UnknownBitmapRotation,
75 UnknownFormType,
76 UnknownFormFieldType,
77 UnknownActionType,
78 UnknownAppearanceMode,
79 UnknownPageAnnotationVariableTextJustificationType,
80 PageObjectIndexOutOfBounds,
81 PageAnnotationIndexOutOfBounds,
82 OwnershipNotAttachedToDocument,
83 OwnershipNotAttachedToPage,
84 OwnershipAlreadyAttachedToDifferentPage,
85 OwnershipNotAttachedToAnnotation,
86 FormFieldOptionIndexOutOfBounds,
87 FormFieldAppearanceStreamUndefined,
88 PageFlattenFailure,
89 PageMissingEmbeddedThumbnail,
90 UnknownPdfPageObjectType,
91 UnknownPdfPageTextRenderMode,
92 UnknownPdfPagePathFillMode,
93 UnknownPdfAnnotationType,
94 UnknownPdfDestinationViewType,
95 UnknownPdfSecurityHandlerRevision,
96 UnsupportedPdfPageObjectType,
97 TextSegmentIndexOutOfBounds,
98 TextSearchTargetIsEmpty,
99 CharIndexOutOfBounds,
100 NoCharsInPageObject,
101 NoCharsInAnnotation,
102 NoCharsInRect,
103 ImageObjectFilterIndexOutOfBounds,
104 ImageObjectFilterIndexInBoundsButFilterUndefined,
105 UnknownPdfColorSpace,
106 InvalidTransformationMatrix,
107 FontGlyphIndexOutOfBounds,
108 UnknownPathSegmentType,
109 NoPagesInDocument,
110 NoPageObjectsInCollection,
111 NoPageLinksInCollection,
112 NoAnnotationsInCollection,
113 PageObjectNotCopyable,
114 ImageObjectFiltersNotCopyable,
115 PathObjectBezierControlPointsNotCopyable,
116 PathObjectUnknownSegmentTypeNotCopyable,
117 GroupContainsNonCopyablePageObjects,
118 SourcePageIndexNotInCache,
119 NoUriForAction,
120 DestinationPageIndexNotAvailable,
121 DestinationPageLocationNotAvailable,
122 PageAnnotationAttachmentPointIndexOutOfBounds,
123 NoAttachmentPointsInPageAnnotation,
124 CoordinateConversionFunctionIndicatedError,
125
126 /// Pdfium does not safely support moving page object ownership from one document to another.
127 CannotMoveObjectAcrossDocuments,
128
129 /// Pdfium does not support adding or removing page objects from the page objects
130 /// collection inside a PdfPageXObjectFormObject object.
131 PageObjectsCollectionIsImmutable,
132
133 /// A call to `FPDFDest_GetView()` returned a valid `FPDFDEST_VIEW_*` value, but the number
134 /// of view parameters returned does not match the PDF specification.
135 PdfDestinationViewInvalidParameters,
136
137 /// A [ParseIntError] occurred while attempting to parse a `PdfColor` from a hexadecimal string
138 /// in `PdfColor::from_hex()`.
139 ParseHexadecimalColorError(ParseIntError),
140
141 /// The hexadecimal string given to `PdfColor::from_hex()` was not either exactly 7 or 9
142 /// characters long.
143 ParseHexadecimalColorUnexpectedLength,
144
145 /// The leading `#` character was not found while attempting to parse a `PdfColor` from
146 /// a hexadecimal string in `PdfColor::from_hex()`.
147 ParseHexadecimalColorMissingLeadingHash,
148
149 /// An error occurred converting a byte stream into a `CString`.
150 CStringConversionError(IntoStringError),
151
152 /// Two data buffers are expected to have the same size, but they do not.
153 DataBufferLengthMismatch,
154
155 /// The setting cannot be returned because this `PdfPageGroupObject` is empty.
156 EmptyPageObjectGroup,
157
158 /// A call to a internal Pdfium `FPDF_*` function returned a value indicating failure.
159 ///
160 /// For Pdfium functions that return enumerations, this means the function returned
161 /// a value of -1 rather than a valid enumeration constant.
162 ///
163 /// For Pdfium functions that return C-style boolean integers, this means that the function
164 /// returned a value other than `PdfiumLibraryBindings::TRUE`.
165 PdfiumFunctionReturnValueIndicatedFailure,
166
167 /// A call to a Pdfium function that returns a standard 8-bit color component value
168 /// (for example, `FPDFPageObj_GetStrokeColor()` and `FPDFPageObj_GetStrokeColor()`)
169 /// successfully returned a value, but the value could not be converted from a c_int
170 /// to a standard Rust u8.
171 UnableToConvertPdfiumColorValueToRustu8(std::num::TryFromIntError),
172
173 /// The browser's built-in `Window` object could not be retrieved.
174 WebSysWindowObjectNotAvailable,
175
176 #[cfg(target_arch = "wasm32")]
177 /// A JsValue returned from a function call was set to JsValue::UNDEFINED instead of
178 /// a valid value of the expected type.
179 JsValueUndefined,
180
181 #[cfg(target_arch = "wasm32")]
182 /// An error was returned when attempting to use the browser's built-in `fetch()` API.
183 WebSysFetchError(JsValue),
184
185 #[cfg(target_arch = "wasm32")]
186 /// An invalid Response object was returned when attempting to use the browser's built-in `fetch()` API.
187 WebSysInvalidResponseError,
188
189 #[cfg(target_arch = "wasm32")]
190 /// An error was returned when attempting to construct a `Blob` object from a byte buffer.
191 JsSysErrorConstructingBlobFromBytes,
192
193 #[cfg(target_arch = "wasm32")]
194 /// An error occurred when attempting to retrieve the function table for the compiled
195 /// Pdfium WASM module.
196 JsSysErrorRetrievingFunctionTable(JsValue),
197
198 #[cfg(target_arch = "wasm32")]
199 /// An error occurred when attempting to retrieve an exported function from
200 /// `pdfium-render`'s WASM module.
201 JsSysErrorRetrievingFunction(JsValue),
202
203 #[cfg(target_arch = "wasm32")]
204 /// An error occurred when attempting to update an entry in Pdfium's WASM function table.
205 JsSysErrorPatchingFunctionTable(JsValue),
206
207 #[cfg(target_arch = "wasm32")]
208 /// No previously cached function was available for a WASM function table restore operation.
209 ///
210 /// This error should never occur; if it does, it indicates a programming error in pdfium-render.
211 /// Please file an issue: https://github.com/ajrcarey/pdfium-render/issues
212 NoPreviouslyCachedFunctionSet,
213
214 /// An error occurred during an image processing operation.
215 ImageError,
216
217 /// Dimensions of `Image::Image` are specified in `u32`, but bitmaps in Pdfium are sized in
218 /// `c_int` (`i32`), meaning that an `Image::Image` can have dimensions that overflow
219 /// the maximum size of a Pdfium bitmap. As a compromise, Image dimensions in `pdfium-render`
220 /// are limited to `u16`.
221 ///
222 /// This error indicates that an `Image::Image` had a width or height larger than the maximum
223 /// `u16` size allowed by `pdfium-render`.
224 ImageSizeOutOfBounds,
225
226 /// An I/O error occurred during a Pdfium file operation.
227 IoError(std::io::Error),
228
229 /// A wrapped internal library error from Pdfium's `FPDF_ERR_*` constant values.
230 PdfiumLibraryInternalError(PdfiumInternalError),
231}
232
233impl Display for PdfiumError {
234 fn fmt(&self, f: &mut Formatter<'_>) -> Result {
235 write!(f, "{self:#?}")
236 }
237}
238
239impl Error for PdfiumError {}