nulib.system.com.objbase source code

1 /**
2     COM Object Base Functions
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.objbase;
12 import nulib.system.com.uuid;
13 import nulib.system.com.hresult;
14 import nulib.system.com.unk;
15 
16 extern(Windows) @nogc nothrow:
17 
18 enum CLSCTX : uint {
19     CLSCTX_INPROC_SERVER    = 0x1,
20     CLSCTX_INPROC_HANDLER   = 0x2,
21     CLSCTX_LOCAL_SERVER     = 0x4,
22     CLSCTX_INPROC_SERVER16  = 0x8,
23     CLSCTX_REMOTE_SERVER    = 0x10,
24     CLSCTX_INPROC_HANDLER16 = 0x20,
25     CLSCTX_INPROC_SERVERX86 = 0x40,
26     CLSCTX_INPROC_HANDLERX86 = 0x80,
27 }
28 
29 /**
30     Determines the concurrency model used for incoming calls to objects created by this thread.
31     This concurrency model can be either apartment-threaded or multithreaded.
32 
33     Remarks:
34         $(P 
35             When a thread is initialized through a call to CoInitializeEx, 
36             you choose whether to initialize it as apartment-threaded or multithreaded by 
37             designating one of the members of COINIT as its second parameter.
38 
39             This designates how incoming calls to any object created by that thread are handled, 
40             that is, the object's concurrency.
41         )
42         $(P 
43             Apartment-threading, while allowing for multiple threads of execution, 
44             serializes all incoming calls by requiring that calls to methods of objects created by 
45             this thread always run on the same thread, i.e. the apartment/thread that created them.
46 
47             In addition, calls can arrive only at message-queue boundaries.
48 
49             Because of this serialization, it is not typically necessary to write concurrency 
50             control into the code for the object, other than to avoid calls to PeekMessage and 
51             SendMessage during processing that must not be interrupted by other method invocations 
52             or calls to other objects in the same apartment/thread.
53         )
54         $(P
55             Multi-threading (also called free-threading) allows calls to methods of objects 
56             created by this thread to be run on any thread.
57             There is no serialization of calls, i.e. many calls may occur to the same method 
58             or to the same object or simultaneously.
59 
60             Multi-threaded object concurrency offers the highest performance and takes the best 
61             advantage of multiprocessor hardware for cross-thread, cross-process, and cross-machine 
62             calling, since calls to objects are not serialized in any way.
63             This means, however, that the code for objects must enforce its own concurrency model, 
64             typically through the use of synchronization primitives, such as critical sections, 
65             semaphores, or mutexes.
66 
67             In addition, because the object doesn't control the lifetime of the threads 
68             that are accessing it, no thread-specific state may be stored in the object 
69             (in Thread Local Storage).
70         )
71 
72     Notes:
73         $(P
74             The multi-threaded apartment is intended for use by non-GUI threads.
75             Threads in multi-threaded apartments should not perform UI actions.
76             This is because UI threads require a message pump, and COM does not pump messages for 
77             threads in a multi-threaded apartment.
78         )
79 */
80 enum COINIT : uint {
81     
82     /**
83         Initializes the thread for apartment-threaded object concurrency (see Remarks).
84     */
85     APARTMENTTHREADED = 0x2,
86     
87     /**
88         Initializes the thread for multithreaded object concurrency (see Remarks).
89     */
90     MULTITHREADED = 0x0,
91     
92     /**
93         Disables DDE for OLE1 support.
94     */
95     DISABLE_OLE1DDE = 0x4,
96     
97     /**
98         Increase memory usage in an attempt to increase performance.
99     */
100     SPEED_OVER_MEMORY = 0x8
101 }
102 
103 
104 /**
105     Initializes the COM library on the current thread and 
106     identifies the concurrency model as single-thread apartment (STA).
107 
108     Params:
109         pvReserved = Reserved, must be $(D null).
110     
111     Returns:
112         An HRESULT indicating the error code.
113 */
114 extern HRESULT CoInitialize(void* pvReserved = null);
115 extern HRESULT CoInitializeEx(uint, void*);
116 extern void CoUninitialize();
117 extern uint CoGetCurrentProcess();
118 extern HRESULT CoCreateInstance(const(IID)*, IUnknown, CLSCTX, const(CLSID)*, void**);
119 extern void CoFreeLibrary(void*);
120 extern void CoFreeAllLibraries();
121 extern void CoFreeUnusedLibraries();
122 extern void* MIDL_user_allocate(size_t);
123 extern void MIDL_user_free(void*);
124 
125 debug {
126     extern uint DebugCoGetRpcFault();
127     extern void DebugCoSetRpcFault(uint);
128 }