ptr.h@ 4014

Last change on this file since 4014 was 3634, checked in by vboxsync, 17 years ago
VBox_hdr_h -> _VBox_hdr_h
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 12.4 KB

Line
1	/** @file
2	* MS COM / XPCOM Abstraction Layer:
3	* Smart COM pointer classes declaration
4	*/
5
6	/*
7	* Copyright (C) 2006-2007 innotek GmbH
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License as published by the Free Software Foundation,
13	* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
14	* distribution. VirtualBox OSE is distributed in the hope that it will
15	* be useful, but WITHOUT ANY WARRANTY of any kind.
16	*
17	* If you received this file as part of a commercial VirtualBox
18	* distribution, then only the terms of your commercial VirtualBox
19	* license agreement apply instead of the previous paragraph.
20	*/
21
22	#ifndef ___VBox_com_ptr_h
23	#define ___VBox_com_ptr_h
24
25	#if !defined (VBOX_WITH_XPCOM)
26
27	#include <atlbase.h>
28
29	#ifndef _ATL_IIDOF
30	# define _ATL_IIDOF(c) __uuidof(c)
31	#endif
32
33	#else /* !defined (VBOX_WITH_XPCOM) */
34
35	#include <nsXPCOM.h>
36	#include <nsIComponentManager.h>
37	#include <nsCOMPtr.h>
38	#include <ipcIService.h>
39	#include <nsIServiceManagerUtils.h>
40	#include <ipcCID.h>
41	#include <ipcIDConnectService.h>
42
43	// official XPCOM headers don't define it yet
44	#define IPC_DCONNECTSERVICE_CONTRACTID \
45	"@mozilla.org/ipc/dconnect-service;1"
46
47	#endif /* !defined (VBOX_WITH_XPCOM) */
48
49	#include <VBox/com/defs.h>
50	#include <VBox/com/assert.h>
51
52	/**
53	* Strong referencing operators. Used as a second argument to ComPtr<>/ComObjPtr<>.
54	*/
55	template <class C>
56	class ComStrongRef
57	{
58	protected:
59	static void addref (C *p) { p->AddRef(); }
60	static void release (C *p) { p->Release(); }
61	};
62
63	/**
64	* Weak referencing operators. Used as a second argument to ComPtr<>/ComObjPtr<>.
65	*/
66	template <class C>
67	class ComWeakRef
68	{
69	protected:
70	static void addref (C *p) {}
71	static void release (C *p) {}
72	};
73
74	/**
75	* Base template for smart COM pointers. Not intended to be used directly.
76	*/
77	template <class C, template <class> class RefOps = ComStrongRef>
78	class ComPtrBase : protected RefOps <C>
79	{
80	public:
81
82	// a special template to disable AddRef()/Release()
83	template <class I>
84	class NoAddRefRelease : public I {
85	private:
86	#if !defined (VBOX_WITH_XPCOM)
87	STDMETHOD_(ULONG, AddRef)() = 0;
88	STDMETHOD_(ULONG, Release)() = 0;
89	#else /* !defined (VBOX_WITH_XPCOM) */
90	NS_IMETHOD_(nsrefcnt) AddRef(void) = 0;
91	NS_IMETHOD_(nsrefcnt) Release(void) = 0;
92	#endif /* !defined (VBOX_WITH_XPCOM) */
93	};
94
95	protected:
96
97	ComPtrBase () : p (NULL) {}
98	ComPtrBase (const ComPtrBase &that) : p (that.p) { addref(); }
99	ComPtrBase (C *that_p) : p (that_p) { addref(); }
100
101	~ComPtrBase() { release(); }
102
103	ComPtrBase &operator= (const ComPtrBase &that) {
104	safe_assign (that.p);
105	return *this;
106	}
107	ComPtrBase &operator= (C *that_p) {
108	safe_assign (that_p);
109	return *this;
110	}
111
112	public:
113
114	void setNull() {
115	release();
116	p = NULL;
117	}
118
119	bool isNull() const {
120	return (p == NULL);
121	}
122	bool operator! () const { return isNull(); }
123
124	bool operator< (C* that_p) const { return p < that_p; }
125	bool operator== (C* that_p) const { return p == that_p; }
126
127	template <class I>
128	bool equalsTo (I *i) const {
129	IUnknown this_unk = NULL, that_unk = NULL;
130	if (i)
131	i->QueryInterface (COM_IIDOF (IUnknown), (void**) &that_unk);
132	if (p)
133	p->QueryInterface (COM_IIDOF (IUnknown), (void**) &this_unk);
134	bool equal = this_unk == that_unk;
135	if (that_unk)
136	that_unk->Release();
137	if (this_unk)
138	this_unk->Release();
139	return equal;
140	}
141
142	template <class OC>
143	bool equalsTo (const ComPtrBase <OC> &oc) const {
144	return equalsTo ((OC *) oc);
145	}
146
147	/** Intended to pass instances as in parameters to interface methods */
148	operator C* () const { return p; }
149
150	/**
151	* Derefereces the instance (redirects the -> operator to the managed
152	* pointer).
153	*/
154	NoAddRefRelease <C> *operator-> () const {
155	AssertMsg (p, ("Managed pointer must not be null\n"));
156	return (NoAddRefRelease <C> *) p;
157	}
158
159	template <class I>
160	HRESULT queryInterfaceTo (I **pp) const {
161	if (pp) {
162	if (p) {
163	return p->QueryInterface (COM_IIDOF (I), (void**) pp);
164	} else {
165	*pp = NULL;
166	return S_OK;
167	}
168	} else {
169	return E_INVALIDARG;
170	}
171	}
172
173	/** Intended to pass instances as out parameters to interface methods */
174	C **asOutParam() {
175	setNull();
176	return &p;
177	}
178
179	private:
180
181	void addref() {
182	if (p)
183	RefOps <C>::addref (p);
184	}
185	void release() {
186	if (p)
187	RefOps <C>::release (p);
188	}
189
190	void safe_assign (C *that_p) {
191	// be aware of self-assignment
192	if (that_p)
193	RefOps <C>::addref (that_p);
194	release();
195	p = that_p;
196	}
197
198	C *p;
199	};
200
201	/**
202	* Smart COM pointer wrapper that automatically manages refcounting of
203	* interface pointers.
204	*
205	* @param I COM interface class
206	*/
207	template <class I, template <class> class RefOps = ComStrongRef>
208	class ComPtr : public ComPtrBase <I, RefOps>
209	{
210	typedef ComPtrBase <I, RefOps> Base;
211
212	public:
213
214	ComPtr () : Base() {}
215	ComPtr (const ComPtr &that) : Base (that) {}
216	ComPtr &operator= (const ComPtr &that) {
217	Base::operator= (that);
218	return *this;
219	}
220
221	template <class OI>
222	ComPtr (OI *that_p) : Base () { operator= (that_p); }
223	// specialization for I
224	ComPtr (I *that_p) : Base (that_p) {}
225
226	template <class OC>
227	ComPtr (const ComPtr <OC, RefOps> &oc) : Base () { operator= ((OC *) oc); }
228
229	template <class OI>
230	ComPtr &operator= (OI *that_p) {
231	if (that_p)
232	that_p->QueryInterface (COM_IIDOF (I), (void **) Base::asOutParam());
233	else
234	Base::setNull();
235	return *this;
236	}
237	// specialization for I
238	ComPtr &operator= (I *that_p) {
239	Base::operator= (that_p);
240	return *this;
241	}
242
243	template <class OC>
244	ComPtr &operator= (const ComPtr <OC, RefOps> &oc) {
245	return operator= ((OC *) oc);
246	}
247
248	/**
249	* Createas an in-process object of the given class ID and starts to
250	* manage a reference to the created object in case of success.
251	*/
252	HRESULT createInprocObject (const CLSID &clsid)
253	{
254	HRESULT rc;
255	I *obj = NULL;
256	#if !defined (VBOX_WITH_XPCOM)
257	rc = CoCreateInstance (clsid, NULL, CLSCTX_INPROC_SERVER, _ATL_IIDOF (I),
258	(void **) &obj);
259	#else /* !defined (VBOX_WITH_XPCOM) */
260	nsCOMPtr <nsIComponentManager> manager;
261	rc = NS_GetComponentManager (getter_AddRefs (manager));
262	if (SUCCEEDED (rc))
263	rc = manager->CreateInstance (clsid, nsnull, NS_GET_IID (I),
264	(void **) &obj);
265	#endif /* !defined (VBOX_WITH_XPCOM) */
266	*this = obj;
267	if (SUCCEEDED (rc))
268	obj->Release();
269	return rc;
270	}
271
272	/**
273	* Createas a local (out-of-process) object of the given class ID and starts
274	* to manage a reference to the created object in case of success.
275	*
276	* Note: In XPCOM, the out-of-process functionality is currently emulated
277	* through in-process wrapper objects (that start a dedicated process and
278	* redirect all object requests to that process). For this reason, this
279	* method is fully equivalent to #createInprocObject() for now.
280	*/
281	HRESULT createLocalObject (const CLSID &clsid)
282	{
283	#if !defined (VBOX_WITH_XPCOM)
284	HRESULT rc;
285	I *obj = NULL;
286	rc = CoCreateInstance (clsid, NULL, CLSCTX_LOCAL_SERVER, _ATL_IIDOF (I),
287	(void **) &obj);
288	*this = obj;
289	if (SUCCEEDED (rc))
290	obj->Release();
291	return rc;
292	#else /* !defined (VBOX_WITH_XPCOM) */
293	return createInprocObject (clsid);
294	#endif /* !defined (VBOX_WITH_XPCOM) */
295	}
296
297	#ifdef VBOX_WITH_XPCOM
298	/**
299	* Createas an object of the given class ID on the specified server and
300	* starts to manage a reference to the created object in case of success.
301	*
302	* @param serverName Name of the server to create an object within.
303	*/
304	HRESULT createObjectOnServer (const CLSID &clsid, const char *serverName)
305	{
306	HRESULT rc;
307	I *obj = NULL;
308	nsCOMPtr <ipcIService> ipcServ = do_GetService (IPC_SERVICE_CONTRACTID, &rc);
309	if (SUCCEEDED (rc))
310	{
311	PRUint32 serverID = 0;
312	rc = ipcServ->ResolveClientName (serverName, &serverID);
313	if (SUCCEEDED (rc)) {
314	nsCOMPtr <ipcIDConnectService> dconServ =
315	do_GetService (IPC_DCONNECTSERVICE_CONTRACTID, &rc);
316	if (SUCCEEDED (rc))
317	rc = dconServ->CreateInstance (serverID, clsid, NS_GET_IID (I),
318	(void **) &obj);
319	}
320	}
321	*this = obj;
322	if (SUCCEEDED (rc))
323	obj->Release();
324	return rc;
325	}
326	#endif
327	};
328
329	/**
330	* Specialization of ComPtr<> for IUnknown to guarantee identity
331	* by always doing QueryInterface() when constructing or assigning from
332	* another interface pointer disregarding its type.
333	*/
334	template <template <class> class RefOps>
335	class ComPtr <IUnknown, RefOps> : public ComPtrBase <IUnknown, RefOps>
336	{
337	typedef ComPtrBase <IUnknown, RefOps> Base;
338
339	public:
340
341	ComPtr () : Base() {}
342	ComPtr (const ComPtr &that) : Base (that) {}
343	ComPtr &operator= (const ComPtr &that) {
344	Base::operator= (that);
345	return *this;
346	}
347
348	template <class OI>
349	ComPtr (OI *that_p) : Base () { operator= (that_p); }
350
351	template <class OC>
352	ComPtr (const ComPtr <OC, RefOps> &oc) : Base () { operator= ((OC *) oc); }
353
354	template <class OI>
355	ComPtr &operator= (OI *that_p) {
356	if (that_p)
357	that_p->QueryInterface (COM_IIDOF (IUnknown), (void **) Base::asOutParam());
358	else
359	Base::setNull();
360	return *this;
361	}
362
363	template <class OC>
364	ComPtr &operator= (const ComPtr <OC, RefOps> &oc) {
365	return operator= ((OC *) oc);
366	}
367	};
368
369	/**
370	* Smart COM pointer wrapper that automatically manages refcounting of
371	* pointers to interface implementation classes created on the component's
372	* (i.e. the server's) side. Differs from ComPtr by providing additional
373	* platform independent operations for creating new class instances.
374	*
375	* @param C class that implements some COM interface
376	*/
377	template <class C, template <class> class RefOps = ComStrongRef>
378	class ComObjPtr : public ComPtrBase <C, RefOps>
379	{
380	typedef ComPtrBase <C, RefOps> Base;
381
382	public:
383
384	ComObjPtr () : Base() {}
385	ComObjPtr (const ComObjPtr &that) : Base (that) {}
386	ComObjPtr (C *that_p) : Base (that_p) {}
387	ComObjPtr &operator= (const ComObjPtr &that) {
388	Base::operator= (that);
389	return *this;
390	}
391	ComObjPtr &operator= (C *that_p) {
392	Base::operator= (that_p);
393	return *this;
394	}
395
396	/**
397	* Creates a new server-side object of the given component class and
398	* immediately starts to manage a pointer to the created object (the
399	* previous pointer, if any, is of course released when appropriate).
400	*
401	* @note This method should be used with care on weakly referenced
402	* smart pointers because it leaves the newly created object completely
403	* unreferenced (i.e., with reference count equal to zero),
404	*
405	* @note Win32: when VBOX_COM_OUTOFPROC_MODULE is defined, the created
406	* object doesn't increase the lock count of the server module, as it
407	* does otherwise.
408	*/
409	HRESULT createObject() {
410	HRESULT rc;
411	#if !defined (VBOX_WITH_XPCOM)
412	# ifdef VBOX_COM_OUTOFPROC_MODULE
413	CComObjectNoLock <C> *obj = new CComObjectNoLock <C>();
414	if (obj) {
415	obj->InternalFinalConstructAddRef();
416	rc = obj->FinalConstruct();
417	obj->InternalFinalConstructRelease();
418	} else {
419	rc = E_OUTOFMEMORY;
420	}
421	# else
422	CComObject <C> *obj = NULL;
423	rc = CComObject <C>::CreateInstance (&obj);
424	# endif
425	#else /* !defined (VBOX_WITH_XPCOM) */
426	CComObject <C> *obj = new CComObject <C>();
427	if (obj) {
428	rc = obj->FinalConstruct();
429	} else {
430	rc = E_OUTOFMEMORY;
431	}
432	#endif /* !defined (VBOX_WITH_XPCOM) */
433	*this = obj;
434	return rc;
435	}
436	};
437
438	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/VBox/com/ptr.h@ 4014

Download in other formats: