Make raw_*_handle return a result

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+* **Breaking:** `HasRaw(Display/Window)Handle::raw_(display/window)_handle` returns a result indicating if fetching the window handle failed (#122).
 * Remove Android-specific platform differences (#118).
 
 ## 0.5.2 (2023-03-31)

src/borrowed.rs

@@ -7,7 +7,9 @@ use core::fmt;
 use core::hash::{Hash, Hasher};
 use core::marker::PhantomData;
 
-use crate::{HasRawDisplayHandle, HasRawWindowHandle, RawDisplayHandle, RawWindowHandle};
+use crate::{
+    HandleError, HasRawDisplayHandle, HasRawWindowHandle, RawDisplayHandle, RawWindowHandle,
+};
 
 /// Keeps track of whether the application is currently active.
 ///
@@ -268,8 +270,8 @@ impl<'a> DisplayHandle<'a> {
 }
 
 unsafe impl HasRawDisplayHandle for DisplayHandle<'_> {
-    fn raw_display_handle(&self) -> RawDisplayHandle {
-        self.raw
+    fn raw_display_handle(&self) -> Result<RawDisplayHandle, HandleError> {
+        Ok(self.raw)
     }
 }
 
@@ -411,8 +413,8 @@ impl<'a> WindowHandle<'a> {
 }
 
 unsafe impl HasRawWindowHandle for WindowHandle<'_> {
-    fn raw_window_handle(&self) -> RawWindowHandle {
-        self.raw
+    fn raw_window_handle(&self) -> Result<RawWindowHandle, HandleError> {
+        Ok(self.raw)
     }
 }
 
@@ -422,27 +424,6 @@ impl HasWindowHandle for WindowHandle<'_> {
     }
 }
 
-/// The error type returned when a handle cannot be obtained.
-#[derive(Debug)]
-#[non_exhaustive]
-pub enum HandleError {
-    /// The handle is not currently active.
-    ///
-    /// See documentation on [`Active`] for more information.
-    Inactive,
-}
-
-impl fmt::Display for HandleError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        match self {
-            Self::Inactive => write!(f, "the handle is not currently active"),
-        }
-    }
-}
-
-#[cfg(feature = "std")]
-impl std::error::Error for HandleError {}
-
 /// ```compile_fail
 /// use raw_window_handle::{Active, DisplayHandle, WindowHandle};
 /// fn _assert<T: Send + Sync>() {}

src/lib.rs

@@ -48,8 +48,7 @@ pub use appkit::{AppKitDisplayHandle, AppKitWindowHandle};
 #[cfg(any(feature = "std", not(target_os = "android")))]
 #[allow(deprecated)]
 pub use borrowed::{
-    Active, ActiveHandle, DisplayHandle, HandleError, HasDisplayHandle, HasWindowHandle,
-    WindowHandle,
+    Active, ActiveHandle, DisplayHandle, HasDisplayHandle, HasWindowHandle, WindowHandle,
 };
 pub use haiku::{HaikuDisplayHandle, HaikuWindowHandle};
 pub use redox::{OrbitalDisplayHandle, OrbitalWindowHandle};
@@ -61,6 +60,8 @@ pub use unix::{
 pub use web::{WebDisplayHandle, WebWindowHandle};
 pub use windows::{Win32WindowHandle, WinRtWindowHandle, WindowsDisplayHandle};
 
+use core::fmt;
+
 /// Window that wraps around a raw window handle.
 ///
 /// # Safety
@@ -76,25 +77,25 @@ pub use windows::{Win32WindowHandle, WinRtWindowHandle, WindowsDisplayHandle};
 /// The exact handles returned by `raw_window_handle` must remain consistent between multiple calls
 /// to `raw_window_handle` as long as not indicated otherwise by platform specific events.
 pub unsafe trait HasRawWindowHandle {
-    fn raw_window_handle(&self) -> RawWindowHandle;
+    fn raw_window_handle(&self) -> Result<RawWindowHandle, HandleError>;
 }
 
 unsafe impl<'a, T: HasRawWindowHandle + ?Sized> HasRawWindowHandle for &'a T {
-    fn raw_window_handle(&self) -> RawWindowHandle {
+    fn raw_window_handle(&self) -> Result<RawWindowHandle, HandleError> {
         (*self).raw_window_handle()
     }
 }
 #[cfg(feature = "alloc")]
 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 unsafe impl<T: HasRawWindowHandle + ?Sized> HasRawWindowHandle for alloc::rc::Rc<T> {
-    fn raw_window_handle(&self) -> RawWindowHandle {
+    fn raw_window_handle(&self) -> Result<RawWindowHandle, HandleError> {
         (**self).raw_window_handle()
     }
 }
 #[cfg(feature = "alloc")]
 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 unsafe impl<T: HasRawWindowHandle + ?Sized> HasRawWindowHandle for alloc::sync::Arc<T> {
-    fn raw_window_handle(&self) -> RawWindowHandle {
+    fn raw_window_handle(&self) -> Result<RawWindowHandle, HandleError> {
         (**self).raw_window_handle()
     }
 }
@@ -216,27 +217,27 @@ pub enum RawWindowHandle {
 /// The exact handles returned by `raw_display_handle` must remain consistent between multiple calls
 /// to `raw_display_handle` as long as not indicated otherwise by platform specific events.
 pub unsafe trait HasRawDisplayHandle {
-    fn raw_display_handle(&self) -> RawDisplayHandle;
+    fn raw_display_handle(&self) -> Result<RawDisplayHandle, HandleError>;
 }
 
 unsafe impl<'a, T: HasRawDisplayHandle + ?Sized> HasRawDisplayHandle for &'a T {
-    fn raw_display_handle(&self) -> RawDisplayHandle {
+    fn raw_display_handle(&self) -> Result<RawDisplayHandle, HandleError> {
         (*self).raw_display_handle()
     }
 }
 
 #[cfg(feature = "alloc")]
 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 unsafe impl<T: HasRawDisplayHandle + ?Sized> HasRawDisplayHandle for alloc::rc::Rc<T> {
-    fn raw_display_handle(&self) -> RawDisplayHandle {
+    fn raw_display_handle(&self) -> Result<RawDisplayHandle, HandleError> {
         (**self).raw_display_handle()
     }
 }
 
 #[cfg(feature = "alloc")]
 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 unsafe impl<T: HasRawDisplayHandle + ?Sized> HasRawDisplayHandle for alloc::sync::Arc<T> {
-    fn raw_display_handle(&self) -> RawDisplayHandle {
+    fn raw_display_handle(&self) -> Result<RawDisplayHandle, HandleError> {
         (**self).raw_display_handle()
     }
 }
@@ -344,6 +345,32 @@ pub enum RawDisplayHandle {
     Haiku(HaikuDisplayHandle),
 }
 
+/// An error that can occur while fetching a display or window handle.
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub enum HandleError {
+    /// The underlying handle cannot be represented using the types in this crate.
+    NotSupported,
+
+    /// The underlying handle is not available.
+    Unavailable,
+}
+
+impl fmt::Display for HandleError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::NotSupported => write!(
+                f,
+                "The underlying handle cannot be represented using the types in this crate"
+            ),
+            Self::Unavailable => write!(f, "The underlying handle is not available"),
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for HandleError {}
+
 macro_rules! from_impl {
     ($($to:ident, $enum:ident, $from:ty)*) => ($(
         impl From<$from> for $to {