cobia/
cape_smart_pointer.rs

1use crate::*;
2use crate::C::*;
3
4/// COBIA Smart Pointer
5/// 
6/// External objects implement interfaces that all derive
7/// from ICapeInterface.
8///
9/// Objects that provide wrappers for such interfaces also
10/// typically maintain the reference count for the underlying
11/// object.
12///
13/// An object can implement multiple interfaces, and one
14/// interface wrapper can be converted to that for another
15/// wrapper provided that the object implements the 
16/// corresponding interface
17
18pub trait CapeSmartPointer {
19	type Interface;
20	/// Get the interface pointer
21	///
22	/// This function provides the interface wrapped by the object.
23	fn as_interface_pointer(&self) -> *mut Self::Interface;
24	/// Get the ICapeInterface
25	///
26	/// All CAPE-OPEN interfaces are laid out such that the 
27	/// first fields correspond to the field of ICapeInterface
28	/// and therefore all interfaces can safely be cast to 
29	/// ICapeInterface.
30	///
31	/// This function provides the ICapeInterface representation
32	/// of the interface wrapped by the object.
33	fn as_cape_interface_pointer(&self) -> *mut C::ICapeInterface;
34	/// Get the interface ID
35	///
36	/// All interfaces are identified by a unique ID, which is 
37	/// passed to the queryInterface member function of 
38	/// ICapeInterface to obtain a pointer to that interface.
39	///
40	/// This function exposes the interface ID for the interface
41	/// that is wrapped.
42	fn get_interface_id() -> &'static CapeUUID;
43	/// Get an interface wrapper instance from another object
44	///
45	/// This function provides an interface wrapper from any 
46	/// object that implements ICapeInterface, provided that the 
47	/// underlying object implements the interface.
48	///
49	/// This function performs a queryInterface on the 
50	/// object that is passed as argument, with the interface
51	/// ID returned by as_cape_interface_pointer()
52	fn from_object<T:CapeSmartPointer>(smart_pointer : &T) -> Result<Self,COBIAError>  where Self: Sized;
53	/// Get an interface wrapper instance from an interface pointer of the wrapped type
54	///
55	/// This function provides an interface wrapper directly from 
56	/// the interface pointer. 
57	/// 
58	/// #Safety
59	///
60	/// The interface pointer must be valid and must point to an object
61	/// that implements the interface.
62	///
63	/// #Panics
64	///
65	/// Panics if the interface pointer is null.
66	fn from_interface_pointer(interface : *mut Self::Interface) -> Self;
67	/// Get an interface wrapper instance from an interface pointer of the wrapped type, without adding a reference
68	///
69	/// This function provides an interface wrapper directly from 
70	/// the interface pointer. Typical use it to attach a return 
71	/// value from an external function, which must be released by the 
72	/// receiver, to the smart pointer.
73	/// 
74	/// #Safety
75	///
76	/// The interface pointer must be valid and must point to an object
77	/// that implements the interface.
78	///
79	/// #Panics
80	///
81	/// Panics if the interface pointer is null.
82	fn attach(interface : *mut Self::Interface) -> Self;
83	/// Return an interface pointer and release ownership, without decreasing a reference
84	///
85	/// This function releases ownership of the object by returning
86	/// the contained pointer. The caller is responsible for releasing the
87	/// object. Typical use is to return the pointer from a function that 
88	/// is exposed externally.
89	fn detach(self) -> *mut Self::Interface;
90	/// Get an interface wrapper instance from any interface pointer
91	///
92	/// This function provides an interface wrapper directly from 
93	/// any CAPE-OPEN interface pointer by performing a queryInterface.
94	///
95	/// If the object does not implement the interface, the function
96	/// returns an error. If the interface pointer is null, the function
97	/// returns an error.
98	///
99	/// Any CAPE-OPEN interface can be cast to ICapeInterface. This is a
100	/// reinterpret-cast and therefore an unsafe operation.
101	/// 
102	/// #Safety
103	///
104	/// If non-null, the interface pointer must be valid and must point 
105	/// to an object that implements the interface.
106	///
107	fn from_cape_interface_pointer(interface : *mut C::ICapeInterface) -> Result<Self,COBIAError>  where Self: Sized;
108	/// Get the last error
109	///
110	/// The last error is available after a function call that
111	/// returns a COBIAERR_CAPEOPENERROR. This function calls
112	/// getLastError on ICapeInterface to obtain the last error.
113	fn last_error(&self) -> Option<CapeError>;
114}
cobia/cape_smart_pointer.rs

cobia/
cape_smart_pointer.rs
