core_foundation/
lib.rs

1// Copyright 2013 The Servo Project Developers. See the COPYRIGHT
2// file at the top-level directory of this distribution.
3//
4// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
5// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
7// option. This file may not be copied, modified, or distributed
8// except according to those terms.
9
10#![allow(non_snake_case)]
11
12//! This crate provides wrappers around the underlying CoreFoundation
13//! types and functions that are available on Apple's operating systems.
14//!
15//! It also provides a framework for other crates to use when wrapping
16//! other frameworks that use the CoreFoundation framework.
17
18use crate::base::TCFType;
19
20pub unsafe trait ConcreteCFType: TCFType {}
21
22/// Declare a Rust type that wraps an underlying CoreFoundation type.
23///
24/// This will provide an implementation of `Drop` using [`CFRelease`].
25/// The type must have an implementation of the [`TCFType`] trait, usually
26/// provided using the [`impl_TCFType`] macro.
27///
28/// ```
29/// use core_foundation::{declare_TCFType, impl_TCFType};
30/// // Make sure that the `TCFType` trait is in scope.
31/// use core_foundation::base::{CFTypeID, TCFType};
32///
33/// extern "C" {
34///     // We need a function that returns the `CFTypeID`.
35///     pub fn ShrubberyGetTypeID() -> CFTypeID;
36/// }
37///
38/// pub struct __Shrubbery {}
39/// // The ref type must be a pointer to the underlying struct.
40/// pub type ShrubberyRef = *const __Shrubbery;
41///
42/// declare_TCFType!(Shrubbery, ShrubberyRef);
43/// impl_TCFType!(Shrubbery, ShrubberyRef, ShrubberyGetTypeID);
44/// # fn main() {}
45/// ```
46///
47/// [`CFRelease`]: https://developer.apple.com/documentation/corefoundation/1521153-cfrelease
48/// [`TCFType`]: base/trait.TCFType.html
49/// [`impl_TCFType`]: macro.impl_TCFType.html
50#[macro_export]
51macro_rules! declare_TCFType {
52    (
53        $(#[$doc:meta])*
54        $ty:ident, $raw:ident
55    ) => {
56        declare_TCFType!($(#[$doc])* $ty<>, $raw);
57    };
58
59    (
60        $(#[$doc:meta])*
61        $ty:ident<$($p:ident $(: $bound:path)*),*>, $raw:ident
62    ) => {
63        $(#[$doc])*
64        pub struct $ty<$($p $(: $bound)*),*>($raw, $(::std::marker::PhantomData<$p>),*);
65
66        #[allow(unused_imports)]
67        impl<$($p $(: $bound)*),*> Drop for $ty<$($p),*> {
68            fn drop(&mut self) {
69                use $crate::base::TCFType;
70                unsafe { $crate::base::CFRelease(self.as_CFTypeRef()) }
71            }
72        }
73    };
74}
75
76/// Provide an implementation of the [`TCFType`] trait for the Rust
77/// wrapper type around an underlying CoreFoundation type.
78///
79/// See [`declare_TCFType`] for details.
80///
81/// [`declare_TCFType`]: macro.declare_TCFType.html
82/// [`TCFType`]: base/trait.TCFType.html
83#[macro_export]
84macro_rules! impl_TCFType {
85    ($ty:ident, $ty_ref:ident, $ty_id:ident) => {
86        impl_TCFType!($ty<>, $ty_ref, $ty_id);
87        unsafe impl $crate::ConcreteCFType for $ty { }
88    };
89
90    ($ty:ident<$($p:ident $(: $bound:path)*),*>, $ty_ref:ident, $ty_id:ident) => {
91        impl<$($p $(: $bound)*),*> $crate::base::TCFType for $ty<$($p),*> {
92            type Ref = $ty_ref;
93
94            #[allow(non_snake_case)]
95            #[inline]
96            fn as_concrete_TypeRef(&self) -> $ty_ref {
97                self.0
98            }
99
100            #[inline]
101            unsafe fn wrap_under_get_rule(reference: $ty_ref) -> Self {
102                assert!(!reference.is_null(), "Attempted to create a NULL object.");
103                let reference = $crate::base::CFRetain(reference as *const ::core::ffi::c_void) as $ty_ref;
104                $crate::base::TCFType::wrap_under_create_rule(reference)
105            }
106
107            #[allow(non_snake_case)]
108            #[inline]
109            fn as_CFTypeRef(&self) -> $crate::base::CFTypeRef {
110                self.as_concrete_TypeRef() as $crate::base::CFTypeRef
111            }
112
113            #[inline]
114            unsafe fn wrap_under_create_rule(reference: $ty_ref) -> Self {
115                assert!(!reference.is_null(), "Attempted to create a NULL object.");
116                // we need one PhantomData for each type parameter so call ourselves
117                // again with @Phantom $p to produce that
118                $ty(reference $(, impl_TCFType!(@Phantom $p))*)
119            }
120
121            #[inline]
122            fn type_id() -> $crate::base::CFTypeID {
123                unsafe {
124                    $ty_id()
125                }
126            }
127        }
128
129        #[allow(unused_imports)]
130        impl<$($p $(: $bound)*),*> Clone for $ty<$($p),*> {
131            #[inline]
132            fn clone(&self) -> Self {
133                use $crate::base::TCFType;
134                unsafe {
135                    $ty::wrap_under_get_rule(self.0)
136                }
137            }
138        }
139
140        #[allow(unused_imports)]
141        impl<$($p $(: $bound)*),*> PartialEq for $ty<$($p),*> {
142            #[inline]
143            fn eq(&self, other: &Self) -> bool {
144                use $crate::base::TCFType;
145                self.as_CFType().eq(&other.as_CFType())
146            }
147        }
148
149        impl<$($p $(: $bound)*),*> Eq for $ty<$($p),*> { }
150
151        #[allow(unused_imports)]
152        unsafe impl<'a, $($p $(: $bound)*),*> $crate::base::ToVoid<$ty<$($p),*>> for &'a $ty<$($p),*> {
153            fn to_void(&self) -> *const ::core::ffi::c_void {
154                use $crate::base::{TCFType, TCFTypeRef};
155                self.as_concrete_TypeRef().as_void_ptr()
156            }
157        }
158
159        #[allow(unused_imports)]
160        unsafe impl<$($p $(: $bound)*),*> $crate::base::ToVoid<$ty<$($p),*>> for $ty<$($p),*> {
161            fn to_void(&self) -> *const ::core::ffi::c_void {
162                use $crate::base::{TCFType, TCFTypeRef};
163                self.as_concrete_TypeRef().as_void_ptr()
164            }
165        }
166
167        #[allow(unused_imports)]
168        unsafe impl<$($p $(: $bound)*),*> $crate::base::ToVoid<$ty<$($p),*>> for $ty_ref {
169            fn to_void(&self) -> *const ::core::ffi::c_void {
170                use $crate::base::TCFTypeRef;
171                self.as_void_ptr()
172            }
173        }
174
175    };
176
177    (@Phantom $x:ident) => { ::std::marker::PhantomData };
178}
179
180/// Implement `std::fmt::Debug` for the given type.
181///
182/// This will invoke the implementation of `Debug` for [`CFType`]
183/// which invokes [`CFCopyDescription`].
184///
185/// The type must have an implementation of the [`TCFType`] trait, usually
186/// provided using the [`impl_TCFType`] macro.
187///
188/// [`CFType`]: base/struct.CFType.html#impl-Debug
189/// [`CFCopyDescription`]: https://developer.apple.com/documentation/corefoundation/1521252-cfcopydescription?language=objc
190/// [`TCFType`]: base/trait.TCFType.html
191/// [`impl_TCFType`]: macro.impl_TCFType.html
192#[macro_export]
193macro_rules! impl_CFTypeDescription {
194    ($ty:ident) => {
195        // it's fine to use an empty <> list
196        impl_CFTypeDescription!($ty<>);
197    };
198    ($ty:ident<$($p:ident $(: $bound:path)*),*>) => {
199        #[allow(unused_imports)]
200        impl<$($p $(: $bound)*),*> ::std::fmt::Debug for $ty<$($p),*> {
201            fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
202                use $crate::base::TCFType;
203                self.as_CFType().fmt(f)
204            }
205        }
206    }
207}
208
209#[macro_export]
210macro_rules! impl_CFComparison {
211    ($ty:ident, $compare:ident) => {
212        impl_CFComparison!($ty<>, $compare);
213    };
214    ($ty:ident<$($p:ident $(: $bound:path)*),*>, $compare:ident) => {
215        impl<$($p $(: $bound)*),*> PartialOrd for $ty<$($p),*> {
216            #[inline]
217            fn partial_cmp(&self, other: &$ty<$($p),*>) -> Option<::std::cmp::Ordering> {
218                unsafe {
219                    Some(
220                        $compare(
221                            self.as_concrete_TypeRef(),
222                            other.as_concrete_TypeRef(),
223                            ::std::ptr::null_mut(),
224                        )
225                        .into(),
226                    )
227                }
228            }
229        }
230
231        impl<$($p $(: $bound)*),*> Ord for $ty<$($p),*> {
232            #[inline]
233            fn cmp(&self, other: &$ty<$($p),*>) -> ::std::cmp::Ordering {
234                self.partial_cmp(other).unwrap()
235            }
236        }
237    };
238}
239
240pub mod array;
241pub mod attributed_string;
242pub mod base;
243pub mod boolean;
244pub mod bundle;
245pub mod characterset;
246pub mod data;
247pub mod date;
248pub mod dictionary;
249pub mod error;
250pub mod filedescriptor;
251pub mod mach_port;
252pub mod number;
253pub mod propertylist;
254pub mod runloop;
255pub mod set;
256pub mod string;
257pub mod timezone;
258pub mod url;
259pub mod uuid;
core_foundation/lib.rs

core_foundation/
lib.rs
