1use crate::imp::Box;
2use crate::{IUnknown, IUnknownImpl, Interface, InterfaceRef};
3use core::any::Any;
4use core::borrow::Borrow;
5use core::ops::Deref;
6use core::ptr::NonNull;
7
8/// Identifies types that can be placed in [`ComObject`].
9///
10/// This trait links types that can be placed in `ComObject` with the types generated by the
11/// `#[implement]` macro. The `#[implement]` macro generates implementations of this trait.
12/// The generated types contain the vtable layouts and refcount-related fields for the COM
13/// object implementation.
14///
15/// This trait is an implementation detail of the Windows crates.
16/// User code should not deal directly with this trait.
17///
18/// This trait is sort of the reverse of [`IUnknownImpl`]. This trait allows user code to use
19/// [`ComObject<T>`] instead of `ComObject<T_Impl>`.
20pub trait ComObjectInner: Sized {
21 /// The generated `<foo>_Impl` type (aka the "boxed" type or "outer" type).
22 type Outer: IUnknownImpl<Impl = Self>;
23
24 /// Moves an instance of this type into a new ComObject box and returns it.
25 ///
26 /// # Safety
27 ///
28 /// It is important that safe Rust code never be able to acquire an owned instance of a
29 /// generated "outer" COM object type, e.g. `<foo>_Impl`. This would be unsafe because the
30 /// `<foo>_Impl` object contains a reference count field and provides methods that adjust
31 /// the reference count, and destroy the object when the reference count reaches zero.
32 ///
33 /// Safe Rust code must only be able to interact with these values by accessing them via a
34 /// `ComObject` reference. `ComObject` handles adjusting reference counts and associates the
35 /// lifetime of a `&<foo>_Impl` with the lifetime of the related `ComObject`.
36 ///
37 /// The `#[implement]` macro generates the implementation of this `into_object` method.
38 /// The generated `into_object` method encapsulates the construction of the `<foo>_Impl`
39 /// object and immediately places it into the heap and returns a `ComObject` reference to it.
40 /// This ensures that our requirement -- that safe Rust code never own a `<foo>_Impl` value
41 /// directly -- is met.
42 fn into_object(self) -> ComObject<Self>;
43}
44
45/// Describes the COM interfaces implemented by a specific COM object.
46///
47/// The `#[implement]` macro generates implementations of this trait. Implementations are attached
48/// to the "outer" types generated by `#[implement]`, e.g. the `MyApp_Impl` type. Each
49/// implementation knows how to locate the interface-specific field within `MyApp_Impl`.
50///
51/// This trait is an implementation detail of the Windows crates.
52/// User code should not deal directly with this trait.
53pub trait ComObjectInterface<I: Interface> {
54 /// Gets a borrowed interface that is implemented by `T`.
55 fn as_interface_ref(&self) -> InterfaceRef<'_, I>;
56}
57
58/// A counted pointer to a type that implements COM interfaces, where the object has been
59/// placed in the heap (boxed).
60///
61/// This type exists so that you can place an object into the heap and query for COM interfaces,
62/// without losing the safe reference to the implementation object.
63///
64/// Because the pointer inside this type is known to be non-null, `Option<ComObject<T>>` should
65/// always have the same size as a single pointer.
66///
67/// # Safety
68///
69/// The contained `ptr` field is an owned, reference-counted pointer to a _pinned_ `Pin<Box<T::Outer>>`.
70/// Although this code does not currently use `Pin<T>`, it takes care not to expose any unsafe semantics
71/// to safe code. However, code that calls unsafe functions on [`ComObject`] must, like all unsafe code,
72/// understand and preserve invariants.
73#[repr(transparent)]
74pub struct ComObject<T: ComObjectInner> {
75 ptr: NonNull<T::Outer>,
76}
77
78impl<T: ComObjectInner> ComObject<T> {
79 /// Allocates a heap cell (box) and moves `value` into it. Returns a counted pointer to `value`.
80 pub fn new(value: T) -> Self {
81 T::into_object(value)
82 }
83
84 /// Creates a new `ComObject` that points to an existing boxed instance.
85 ///
86 /// # Safety
87 ///
88 /// The caller must ensure that `ptr` points to a valid, heap-allocated instance of `T::Outer`.
89 /// Normally, this pointer comes from using `Box::into_raw(Box::new(...))`.
90 ///
91 /// The pointed-to box must have a reference count that is greater than zero.
92 ///
93 /// This function takes ownership of the existing pointer; it does not call `AddRef`.
94 /// The reference count must accurately reflect all outstanding references to the box,
95 /// including `ptr` in the count.
96 pub unsafe fn from_raw(ptr: NonNull<T::Outer>) -> Self {
97 Self { ptr }
98 }
99
100 /// Gets a reference to the shared object stored in the box.
101 ///
102 /// [`ComObject`] also implements [`Deref`], so you can often deref directly into the object.
103 /// For those situations where using the [`Deref`] impl is inconvenient, you can use
104 /// this method to explicitly get a reference to the contents.
105 #[inline(always)]
106 pub fn get(&self) -> &T {
107 self.get_box().get_impl()
108 }
109
110 /// Gets a reference to the shared object's heap box.
111 #[inline(always)]
112 fn get_box(&self) -> &T::Outer {
113 unsafe { self.ptr.as_ref() }
114 }
115
116 // Note that we _do not_ provide a way to get a mutable reference to the outer box.
117 // It's ok to return `&mut T`, but not `&mut T::Outer`. That would allow someone to replace the
118 // contents of the entire object (box and reference count), which could lead to UB.
119 // This could maybe be solved by returning `Pin<&mut T::Outer>`, but that requires some
120 // additional thinking.
121
122 /// Gets a mutable reference to the object stored in the box, if the reference count
123 /// is exactly 1. If there are multiple references to this object then this returns `None`.
124 #[inline(always)]
125 pub fn get_mut(&mut self) -> Option<&mut T> {
126 if self.is_reference_count_one() {
127 // SAFETY: We must only return &mut T, *NOT* &mut T::Outer.
128 // Returning T::Outer would allow swapping the contents of the object, which would
129 // allow (incorrectly) modifying the reference count.
130 unsafe { Some(self.ptr.as_mut().get_impl_mut()) }
131 } else {
132 None
133 }
134 }
135
136 /// If this object has only a single object reference (i.e. this [`ComObject`] is the only
137 /// reference to the heap allocation), then this method will extract the inner `T`
138 /// (and return it in an `Ok`) and then free the heap allocation.
139 ///
140 /// If there is more than one reference to this object, then this returns `Err(self)`.
141 #[inline(always)]
142 pub fn take(self) -> Result<T, Self> {
143 if self.is_reference_count_one() {
144 let outer_box: Box<T::Outer> = unsafe { core::mem::transmute(self) };
145 Ok(outer_box.into_inner())
146 } else {
147 Err(self)
148 }
149 }
150
151 /// Casts to a given interface type.
152 ///
153 /// This always performs a `QueryInterface`, even if `T` is known to implement `I`.
154 /// If you know that `T` implements `I`, then use [`Self::as_interface`] or [`Self::to_interface`] because
155 /// those functions do not require a dynamic `QueryInterface` call.
156 #[inline(always)]
157 pub fn cast<I: Interface>(&self) -> windows_core::Result<I>
158 where
159 T::Outer: ComObjectInterface<IUnknown>,
160 {
161 let unknown = self.as_interface::<IUnknown>();
162 unknown.cast()
163 }
164
165 /// Gets a borrowed reference to an interface that is implemented by `T`.
166 ///
167 /// The returned reference does not have an additional reference count.
168 /// You can AddRef it by calling [`InterfaceRef::to_owned`].
169 #[inline(always)]
170 pub fn as_interface<I: Interface>(&self) -> InterfaceRef<'_, I>
171 where
172 T::Outer: ComObjectInterface<I>,
173 {
174 self.get_box().as_interface_ref()
175 }
176
177 /// Gets an owned (counted) reference to an interface that is implemented by this [`ComObject`].
178 #[inline(always)]
179 pub fn to_interface<I: Interface>(&self) -> I
180 where
181 T::Outer: ComObjectInterface<I>,
182 {
183 self.as_interface::<I>().to_owned()
184 }
185
186 /// Converts `self` into an interface that it implements.
187 ///
188 /// This does not need to adjust reference counts because `self` is consumed.
189 #[inline(always)]
190 pub fn into_interface<I: Interface>(self) -> I
191 where
192 T::Outer: ComObjectInterface<I>,
193 {
194 unsafe {
195 let raw = self.get_box().as_interface_ref().as_raw();
196 core::mem::forget(self);
197 I::from_raw(raw)
198 }
199 }
200
201 /// This casts the given COM interface to [`&dyn Any`]. It returns a reference to the "outer"
202 /// object, e.g. `MyApp_Impl`, not the inner `MyApp` object.
203 ///
204 /// `T` must be a type that has been annotated with `#[implement]`; this is checked at
205 /// compile-time by the generic constraints of this method. However, note that the
206 /// returned `&dyn Any` refers to the _outer_ implementation object that was generated by
207 /// `#[implement]`, i.e. the `MyApp_Impl` type, not the inner `MyApp` type.
208 ///
209 /// If the given object is not a Rust object, or is a Rust object but not `T`, or is a Rust
210 /// object that contains non-static lifetimes, then this function will return `Err(E_NOINTERFACE)`.
211 ///
212 /// The returned value is an owned (counted) reference; this function calls `AddRef` on the
213 /// underlying COM object. If you do not need an owned reference, then you can use the
214 /// [`Interface::cast_object_ref`] method instead, and avoid the cost of `AddRef` / `Release`.
215 pub fn cast_from<I>(interface: &I) -> crate::Result<Self>
216 where
217 I: Interface,
218 T::Outer: Any + 'static + IUnknownImpl<Impl = T>,
219 {
220 interface.cast_object()
221 }
222}
223
224impl<T: ComObjectInner + Default> Default for ComObject<T> {
225 fn default() -> Self {
226 Self::new(T::default())
227 }
228}
229
230impl<T: ComObjectInner> Drop for ComObject<T> {
231 fn drop(&mut self) {
232 unsafe {
233 T::Outer::Release(self.ptr.as_ptr());
234 }
235 }
236}
237
238impl<T: ComObjectInner> Clone for ComObject<T> {
239 #[inline(always)]
240 fn clone(&self) -> Self {
241 unsafe {
242 self.ptr.as_ref().AddRef();
243 Self { ptr: self.ptr }
244 }
245 }
246}
247
248impl<T: ComObjectInner> AsRef<T> for ComObject<T> {
249 #[inline(always)]
250 fn as_ref(&self) -> &T {
251 self.get()
252 }
253}
254
255impl<T: ComObjectInner> Deref for ComObject<T> {
256 type Target = T::Outer;
257
258 #[inline(always)]
259 fn deref(&self) -> &Self::Target {
260 self.get_box()
261 }
262}
263
264// There is no DerefMut implementation because we cannot statically guarantee
265// that the reference count is 1, which is a requirement for getting exclusive
266// access to the contents of the object. Use get_mut() for dynamically-checked
267// exclusive access.
268
269impl<T: ComObjectInner> From<T> for ComObject<T> {
270 fn from(value: T) -> ComObject<T> {
271 ComObject::new(value)
272 }
273}
274
275// Delegate hashing, if implemented.
276impl<T: ComObjectInner + core::hash::Hash> core::hash::Hash for ComObject<T> {
277 fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
278 self.get().hash(state);
279 }
280}
281
282// If T is Send (or Sync) then the ComObject<T> is also Send (or Sync).
283// Since the actual object storage is in the heap, the object is never moved.
284unsafe impl<T: ComObjectInner + Send> Send for ComObject<T> {}
285unsafe impl<T: ComObjectInner + Sync> Sync for ComObject<T> {}
286
287impl<T: ComObjectInner + PartialEq> PartialEq for ComObject<T> {
288 fn eq(&self, other: &ComObject<T>) -> bool {
289 let inner_self: &T = self.get();
290 let other_self: &T = other.get();
291 inner_self == other_self
292 }
293}
294
295impl<T: ComObjectInner + Eq> Eq for ComObject<T> {}
296
297impl<T: ComObjectInner + PartialOrd> PartialOrd for ComObject<T> {
298 fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
299 let inner_self: &T = self.get();
300 let other_self: &T = other.get();
301 <T as PartialOrd>::partial_cmp(inner_self, other_self)
302 }
303}
304
305impl<T: ComObjectInner + Ord> Ord for ComObject<T> {
306 fn cmp(&self, other: &Self) -> core::cmp::Ordering {
307 let inner_self: &T = self.get();
308 let other_self: &T = other.get();
309 <T as Ord>::cmp(inner_self, other_self)
310 }
311}
312
313impl<T: ComObjectInner + core::fmt::Debug> core::fmt::Debug for ComObject<T> {
314 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
315 <T as core::fmt::Debug>::fmt(self.get(), f)
316 }
317}
318
319impl<T: ComObjectInner + core::fmt::Display> core::fmt::Display for ComObject<T> {
320 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
321 <T as core::fmt::Display>::fmt(self.get(), f)
322 }
323}
324
325impl<T: ComObjectInner> Borrow<T> for ComObject<T> {
326 fn borrow(&self) -> &T {
327 self.get()
328 }
329}
330
331/// Enables applications to define COM objects using static storage. This is useful for factory
332/// objects, stateless objects, or objects which use need to contain or use mutable global state.
333///
334/// COM objects that are defined using `StaticComObject` have their storage placed directly in
335/// static storage; they are not stored in the heap.
336///
337/// COM objects defined using `StaticComObject` do have a reference count and this reference
338/// count is adjusted when owned COM interface references (e.g. `IFoo` and `IUnknown`) are created
339/// for the object. The reference count is initialized to 1.
340///
341/// # Example
342///
343/// ```rust,ignore
344/// #[implement(IFoo)]
345/// struct MyApp {
346/// // ...
347/// }
348///
349/// static MY_STATIC_APP: StaticComObject<MyApp> = MyApp { ... }.into_static();
350///
351/// fn get_my_static_ifoo() -> IFoo {
352/// MY_STATIC_APP.to_interface()
353/// }
354/// ```
355pub struct StaticComObject<T>
356where
357 T: ComObjectInner,
358{
359 outer: T::Outer,
360}
361
362// IMPORTANT: Do not expose any methods that return mutable access to the contents of StaticComObject.
363// Doing so would violate our safety invariants. For example, we provide a Deref impl but it would
364// be unsound to provide a DerefMut impl.
365impl<T> StaticComObject<T>
366where
367 T: ComObjectInner,
368{
369 /// Wraps `outer` in a `StaticComObject`.
370 pub const fn from_outer(outer: T::Outer) -> Self {
371 Self { outer }
372 }
373}
374
375impl<T> StaticComObject<T>
376where
377 T: ComObjectInner,
378{
379 /// Gets access to the contained value.
380 pub const fn get(&'static self) -> &'static T::Outer {
381 &self.outer
382 }
383}
384
385impl<T> core::ops::Deref for StaticComObject<T>
386where
387 T: ComObjectInner,
388{
389 type Target = T::Outer;
390
391 fn deref(&self) -> &Self::Target {
392 &self.outer
393 }
394}
395