fidl/
handle.rs

1// Copyright 2019 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! A portable representation of handle-like objects for fidl.
6
7#[cfg(target_os = "fuchsia")]
8pub use fuchsia_handles::*;
9
10#[cfg(not(target_os = "fuchsia"))]
11pub use non_fuchsia_handles::*;
12
13pub use fuchsia_async::{Channel as AsyncChannel, OnSignalsRef, Socket as AsyncSocket};
14
15/// Fuchsia implementation of handles just aliases the zircon library
16#[cfg(target_os = "fuchsia")]
17pub mod fuchsia_handles {
18
19    pub use zx::{
20        AsHandleRef, Handle, HandleBased, HandleDisposition, HandleInfo, HandleOp, HandleRef,
21        MessageBufEtc, ObjectType, Peered, Rights, Signals, Status,
22    };
23
24    pub use fuchsia_async::invoke_for_handle_types;
25
26    macro_rules! fuchsia_handle {
27        ($x:tt, $docname:expr, $name:ident, $zx_name:ident, Stub) => {
28            /// Stub implementation of Zircon handle type $x.
29            #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
30            #[repr(transparent)]
31            pub struct $x(zx::Handle);
32
33            impl zx::AsHandleRef for $x {
34                fn as_handle_ref(&self) -> HandleRef<'_> {
35                    self.0.as_handle_ref()
36                }
37            }
38            impl From<Handle> for $x {
39                fn from(handle: Handle) -> Self {
40                    $x(handle)
41                }
42            }
43            impl From<$x> for Handle {
44                fn from(x: $x) -> Handle {
45                    x.0
46                }
47            }
48            impl zx::HandleBased for $x {}
49        };
50        ($x:tt, $docname:expr, $name:ident, $value:expr, $availability:tt) => {
51            pub use zx::$x;
52        };
53    }
54
55    invoke_for_handle_types!(fuchsia_handle);
56
57    pub use zx::SocketOpts;
58}
59
60/// Non-Fuchsia implementation of handles
61#[cfg(not(target_os = "fuchsia"))]
62pub mod non_fuchsia_handles {
63    pub use fuchsia_async::emulated_handle::{
64        AsHandleRef, EmulatedHandleRef, Handle, HandleBased, HandleDisposition, HandleInfo,
65        HandleOp, HandleRef, MessageBufEtc, ObjectType, Peered, Rights, Signals, SocketOpts,
66    };
67    pub use zx_status::Status;
68
69    pub use fuchsia_async::invoke_for_handle_types;
70
71    macro_rules! declare_unsupported_fidl_handle {
72        ($name:ident) => {
73            /// An unimplemented Zircon-like $name
74            #[derive(PartialEq, Eq, Debug, PartialOrd, Ord, Hash)]
75            pub struct $name;
76
77            impl From<$crate::handle::Handle> for $name {
78                fn from(_: $crate::handle::Handle) -> $name {
79                    $name
80                }
81            }
82            impl From<$name> for Handle {
83                fn from(_: $name) -> $crate::handle::Handle {
84                    $crate::handle::Handle::invalid()
85                }
86            }
87            impl HandleBased for $name {}
88            impl AsHandleRef for $name {
89                fn as_handle_ref(&self) -> HandleRef<'_> {
90                    HandleRef::invalid()
91                }
92            }
93        };
94    }
95
96    macro_rules! declare_fidl_handle {
97        ($name:ident) => {
98            pub use fuchsia_async::emulated_handle::$name;
99        };
100    }
101
102    macro_rules! host_handle {
103        ($x:tt, $docname:expr, $name:ident, $zx_name:ident, Everywhere) => {
104            declare_fidl_handle! {$x}
105        };
106        ($x:tt, $docname:expr, $name:ident, $zx_name:ident, $availability:ident) => {
107            declare_unsupported_fidl_handle! {$x}
108        };
109    }
110
111    invoke_for_handle_types!(host_handle);
112}
113
114#[allow(clippy::too_long_first_doc_paragraph)]
115/// Converts a vector of `HandleDisposition` (handles bundled with their
116/// intended object type and rights) to a vector of `HandleInfo` (handles
117/// bundled with their actual type and rights, guaranteed by the kernel).
118///
119/// This makes a `zx_handle_replace` syscall for each handle unless the rights
120/// are `Rights::SAME_RIGHTS`.
121///
122/// # Panics
123///
124/// Panics if any of the handle dispositions uses `HandleOp::Duplicate`. This is
125/// never the case for handle dispositions return by `standalone_encode`.
126pub fn convert_handle_dispositions_to_infos(
127    handle_dispositions: Vec<HandleDisposition<'_>>,
128) -> crate::Result<Vec<HandleInfo>> {
129    handle_dispositions
130        .into_iter()
131        .map(|mut hd| {
132            Ok(HandleInfo::new(
133                match hd.take_op() {
134                    HandleOp::Move(h) if hd.rights == Rights::SAME_RIGHTS => h,
135                    HandleOp::Move(h) => {
136                        h.replace(hd.rights).map_err(crate::Error::HandleReplace)?
137                    }
138                    HandleOp::Duplicate(_) => panic!("unexpected HandleOp::Duplicate"),
139                },
140                hd.object_type,
141                hd.rights,
142            ))
143        })
144        .collect()
145}
fidl/handle.rs

fidl/
handle.rs
