nulib.system.com.unk source code

1 /**
2     COM Base Interfaces
3 
4     Copyright:
5         Copyright © 2023-2025, Kitsunebi Games
6         Copyright © 2023-2025, Inochi2D Project
7     
8     License:   $(LINK2 http://www.boost.org/LICENSE_1_0.txt, Boost License 1.0)
9     Authors:   Luna Nielsen
10 */
11 module nulib.system.com.unk;
12 import nulib.system.com.hresult;
13 import nulib.system.com.objbase;
14 import nulib.system.com.uuid;
15 
16 /**
17     Fundamental interface within the COM Programming Model.
18 
19     All COM classes must derive from this interface.
20 */
21 @Guid!("00000000-0000-0000-C000-000000000046")
22 interface IUnknown {
23 extern(Windows) @nogc:
24 public:
25     /**
26         Helper type for getting the GUID of IUnknown.
27     */
28     extern(D) __gshared const IID iid = __uuidof!IUnknown;
29 
30     /**
31         Queries a COM object for a pointer to one of its interface.
32 
33         Note:
34             Because you pass the address of an interface pointer, 
35             the method can overwrite that address with the pointer to the interface being queried for.
36             Upon successful return, $(D *ppvObject) (the dereferenced address) contains a pointer to 
37             the requested interface.
38             If the object doesn't support the interface, the method sets $(D *ppvObject) 
39             (the dereferenced address) to $(D null).
40 
41         Params:
42             riid = Reference to the Guid of the interface being queried for.
43             ppvObject = Reference to a pointer to store result of operation in.
44 
45         Returns:
46             $(D S_OK) if supported, $(D E_NOINTERFACE) otherwise.
47             If ppvObject is $(D null), returns $(D E_POINTER). 
48     */
49     HRESULT QueryInterface(const(IID)* riid, out void* ppvObject);
50     
51     /**
52         A helper function that infers an interface identifier.
53     */
54     extern(D)
55     HRESULT QueryInterface(T)(T** pvObject) if(is(__uuidof!T)) {
56         return QueryInterface(__uuidof!T, pvObject);
57     }
58 
59     /**
60         Increments the reference count for an interface pointer to a COM object.
61 
62         You should call this method whenever you make a copy of an interface pointer.
63 
64         Returns:
65             The new reference count, should only be used for debugging.
66     */
67     uint AddRef();
68     
69     /**
70         Decrements the reference count for an interface on a COM object.
71 
72         Returns:
73             The new reference count, should only be used for debugging.
74     */
75     uint Release();
76 }
77 
78 alias LPUNKNOWN = IUnknown; /// Convenience alias.
79 
80 
81 /**
82     Asynchronous version of IUnknown.
83 
84     Note:
85         This interface is poorly documented by Microsoft, but you generally
86         want a $(D ICallFactory) to actually do these calls.
87     
88     See_Also:
89         $(LINK https://devblogs.microsoft.com/oldnewthing/20220214-44/?p=106251)
90 */
91 @Guid!("000e0000-0000-0000-C000-000000000046")
92 interface AsyncIUnknown : IUnknown {
93     
94     /**
95         Begins to query a COM object for a pointer to one of its interface.
96 
97         Params:
98             riid = Reference to the Guid of the interface being queried for.
99 
100         Returns:
101             An $(D HRESULT) status code.
102     */
103     HRESULT Begin_QueryInterface(ref IID riid);
104     
105     /**
106         Finishes querying a COM object for a pointer to one of its interface.
107 
108         Note:
109             Because you pass the address of an interface pointer, 
110             the method can overwrite that address with the pointer to the interface being queried for.
111             Upon successful return, $(D *ppvObject) (the dereferenced address) contains a pointer to 
112             the requested interface.
113             If the object doesn't support the interface, the method sets $(D *ppvObject) 
114             (the dereferenced address) to $(D null).
115 
116         Params:
117             ppvObject = Reference to a pointer to store result of operation in.
118 
119         Returns:
120             An $(D HRESULT) status code.
121     */
122     HRESULT Finish_QueryInterface(out void* ppvObject);
123     
124     /**
125         Begins incrementing the reference count for an interface pointer to a COM object.
126 
127         You should call this method whenever you make a copy of an interface pointer.
128 
129         Returns:
130             An $(D HRESULT) status code.
131     */
132     HRESULT Begin_AddRef();
133     
134     /**
135         Finishes incrementing the reference count for an interface pointer to a COM object.
136 
137         You should call this method whenever you make a copy of an interface pointer.
138 
139         Returns:
140             The new reference count, should only be used for debugging.
141     */
142     uint Finish_AddRef();
143     
144     /**
145         Begins decrementing the reference count for an interface on a COM object.
146 
147         Returns:
148             An $(D HRESULT) status code.
149     */
150     HRESULT Begin_Release();
151     
152     /**
153         Finishes decrementing the reference count for an interface on a COM object.
154 
155         Returns:
156             The new reference count, should only be used for debugging.
157     */
158     uint Finish_Release();
159 }
160 
161 alias LPASYNCUNKNOWN = AsyncIUnknown; /// Convenience alias.
162 
163 /**
164     A class factory.
165 
166     Class factories allows classes to be instantiated in an uninitialized state.
167 */
168 interface IClassFactory : IUnknown {
169 extern(Windows) @nogc:
170     
171     /**
172         Creates an uninitialized object.
173 
174         Params:
175             outer =     If the object is an aggregate, specify controlling $(D IUnknown) 
176                         interface, otherwise set this to $(D null)
177             riid =      The identifier of the interface to be used to communicate with
178                         the newly created object. If $(D outer) is $(D null), this must
179                         be set to $(D IUnknown.IID).
180             ppvObject = The address of pointer variable that receives the interface 
181                         pointer requested in $(D riid).
182 
183         Returns:
184             $(D S_OK) if creation succeeded, 
185             $(D CLASS_E_NOAGGREGATION) if object doesn't support aggregation, 
186             $(D E_NOINTERFACE) if the $(D riid) interface isn't supported,
187             or either of $(D E_INVALIDARG), $(D E_OUTOFMEMORY) and $(D E_UNEXPECTED).
188     */
189     HRESULT CreateInstance(IUnknown outer, const(IID)* riid, out void* ppvObject);
190     alias RemoteCreateInstance = CreateInstance;
191 
192     /**
193         Locks an object application open in memory. 
194         This enables instances to be created more quickly.
195     
196         Params:
197             fLock = If $(D true) increments lock count, otherwise the lock count
198                     is decremented.
199         
200         Returns:
201             Either of $(D S_OK), $(D E_FAIL), $(D E_UNEXPECTED) or $(D E_OUTOFMEMORY)
202     */
203     HRESULT LockServer(bool fLock);
204     alias RemoteLockServer = LockServer;
205 }
206 
207 alias LPCLASSFACTORY = IClassFactory; /// Convenience alias.