VirtualBox

source: vbox/trunk/include/VBox/com/array.h@ 25930

Last change on this file since 25930 was 25346, checked in by vboxsync, 15 years ago

iprt/cpputils.h -> iprt/cpp/utils.h

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Revision Author Id
File size: 48.4 KB
Line 
1/** @file
2 * MS COM / XPCOM Abstraction Layer:
3 * Safe array helper class declaration
4 */
5
6/*
7 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 *
26 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
27 * Clara, CA 95054 USA or visit http://www.sun.com if you need
28 * additional information or have any questions.
29 */
30
31#ifndef ___VBox_com_array_h
32#define ___VBox_com_array_h
33
34/** @defgroup grp_COM_arrays COM/XPCOM Arrays
35 * @{
36 *
37 * The COM/XPCOM array support layer provides a cross-platform way to pass
38 * arrays to and from COM interface methods and consists of the com::SafeArray
39 * template and a set of ComSafeArray* macros part of which is defined in
40 * VBox/com/defs.h.
41 *
42 * This layer works with interface attributes and method parameters that have
43 * the 'safearray="yes"' attribute in the XIDL definition:
44 * @code
45
46 <interface name="ISomething" ...>
47
48 <method name="testArrays">
49 <param name="inArr" type="long" dir="in" safearray="yes"/>
50 <param name="outArr" type="long" dir="out" safearray="yes"/>
51 <param name="retArr" type="long" dir="return" safearray="yes"/>
52 </method>
53
54 </interface>
55
56 * @endcode
57 *
58 * Methods generated from this and similar definitions are implemented in
59 * component classes using the following declarations:
60 * @code
61
62 STDMETHOD(TestArrays) (ComSafeArrayIn (LONG, aIn),
63 ComSafeArrayOut (LONG, aOut),
64 ComSafeArrayOut (LONG, aRet));
65
66 * @endcode
67 *
68 * And the following function bodies:
69 * @code
70
71 STDMETHODIMP Component::TestArrays (ComSafeArrayIn (LONG, aIn),
72 ComSafeArrayOut (LONG, aOut),
73 ComSafeArrayOut (LONG, aRet))
74 {
75 if (ComSafeArrayInIsNull (aIn))
76 return E_INVALIDARG;
77 if (ComSafeArrayOutIsNull (aOut))
78 return E_POINTER;
79 if (ComSafeArrayOutIsNull (aRet))
80 return E_POINTER;
81
82 // Use SafeArray to access the input array parameter
83
84 com::SafeArray <LONG> in (ComSafeArrayInArg (aIn));
85
86 for (size_t i = 0; i < in.size(); ++ i)
87 LogFlow (("*** in[%u]=%d\n", i, in [i]));
88
89 // Use SafeArray to create the return array (the same technique is used
90 // for output array paramters)
91
92 SafeArray <LONG> ret (in.size() * 2);
93 for (size_t i = 0; i < in.size(); ++ i)
94 {
95 ret [i] = in [i];
96 ret [i + in.size()] = in [i] * 10;
97 }
98
99 ret.detachTo (ComSafeArrayOutArg (aRet));
100
101 return S_OK;
102 }
103
104 * @endcode
105 *
106 * Such methods can be called from the client code using the following pattern:
107 * @code
108
109 ComPtr <ISomething> component;
110
111 // ...
112
113 com::SafeArray <LONG> in (3);
114 in [0] = -1;
115 in [1] = -2;
116 in [2] = -3;
117
118 com::SafeArray <LONG> out;
119 com::SafeArray <LONG> ret;
120
121 HRESULT rc = component->TestArrays (ComSafeArrayAsInParam (in),
122 ComSafeArrayAsOutParam (out),
123 ComSafeArrayAsOutParam (ret));
124
125 if (SUCCEEDED (rc))
126 for (size_t i = 0; i < ret.size(); ++ i)
127 printf ("*** ret[%u]=%d\n", i, ret [i]);
128
129 * @endcode
130 *
131 * For interoperability with standard C++ containers, there is a template
132 * constructor that takes such a container as argument and performs a deep copy
133 * of its contents. This can be used in method implementations like this:
134 * @code
135
136 STDMETHODIMP Component::COMGETTER(Values) (ComSafeArrayOut (int, aValues))
137 {
138 // ... assume there is a |std::list <int> mValues| data member
139
140 com::SafeArray <int> values (mValues);
141 values.detachTo (ComSafeArrayOutArg (aValues));
142
143 return S_OK;
144 }
145
146 * @endcode
147 *
148 * The current implementation of the SafeArray layer supports all types normally
149 * allowed in XIDL as array element types (including 'wstring' and 'uuid').
150 * However, 'pointer-to-...' types (e.g. 'long *', 'wstring *') are not
151 * supported and therefore cannot be used as element types.
152 *
153 * Note that for GUID arrays you should use SafeGUIDArray and
154 * SafeConstGUIDArray, customized SafeArray<> specializations.
155 *
156 * Also note that in order to pass input BSTR array parameters declared
157 * using the ComSafeArrayIn (IN_BSTR, aParam) macro to the SafeArray<>
158 * constructor using the ComSafeArrayInArg() macro, you should use IN_BSTR
159 * as the SafeArray<> template argument, not just BSTR.
160 *
161 * Arrays of interface pointers are also supported but they require to use a
162 * special SafeArray implementation, com::SafeIfacePointer, which takes the
163 * interface class name as a template argument (e.g. com::SafeIfacePointer
164 * <IUnknown>). This implementation functions identically to com::SafeArray.
165 */
166
167#if defined (VBOX_WITH_XPCOM)
168# include <nsMemory.h>
169#endif
170
171#include "VBox/com/defs.h"
172#include "VBox/com/ptr.h"
173#include "VBox/com/assert.h"
174
175#include "iprt/cpp/utils.h"
176
177#if defined (VBOX_WITH_XPCOM)
178
179/**
180 * Wraps the given com::SafeArray instance to generate an expression that is
181 * suitable for passing it to functions that take input safearray parameters
182 * declared using the ComSafeArrayIn macro.
183 *
184 * @param aArray com::SafeArray instance to pass as an input parameter.
185 */
186#define ComSafeArrayAsInParam(aArray) \
187 (aArray).size(), (aArray).__asInParam_Arr ((aArray).raw())
188
189/**
190 * Wraps the given com::SafeArray instance to generate an expression that is
191 * suitable for passing it to functions that take output safearray parameters
192 * declared using the ComSafeArrayOut macro.
193 *
194 * @param aArray com::SafeArray instance to pass as an output parameter.
195 */
196#define ComSafeArrayAsOutParam(aArray) \
197 (aArray).__asOutParam_Size(), (aArray).__asOutParam_Arr()
198
199#else /* defined (VBOX_WITH_XPCOM) */
200
201#define ComSafeArrayAsInParam(aArray) (aArray).__asInParam()
202
203#define ComSafeArrayAsOutParam(aArray) (aArray).__asOutParam()
204
205#endif /* defined (VBOX_WITH_XPCOM) */
206
207/**
208 *
209 */
210namespace com
211{
212
213#if defined (VBOX_WITH_XPCOM)
214
215////////////////////////////////////////////////////////////////////////////////
216
217/**
218 * Provides various helpers for SafeArray.
219 *
220 * @param T Type of array elements.
221 */
222template <typename T>
223struct SafeArrayTraits
224{
225protected:
226
227 /** Initializes memory for aElem. */
228 static void Init (T &aElem) { aElem = 0; }
229
230 /** Initializes memory occupied by aElem. */
231 static void Uninit (T &aElem) { aElem = 0; }
232
233 /** Creates a deep copy of aFrom and stores it in aTo. */
234 static void Copy (const T &aFrom, T &aTo) { aTo = aFrom; }
235
236public:
237
238 /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard (that
239 * in particular forbid casts of 'char **' to 'const char **'). Then initial
240 * reason for this magic is that XPIDL declares input strings
241 * (char/PRUnichar pointers) as const but doesn't do so for pointers to
242 * arrays. */
243 static T *__asInParam_Arr (T *aArr) { return aArr; }
244 static T *__asInParam_Arr (const T *aArr) { return const_cast <T *> (aArr); }
245};
246
247template <typename T>
248struct SafeArrayTraits <T *>
249{
250 // Arbitrary pointers are not supported
251};
252
253template<>
254struct SafeArrayTraits <PRUnichar *>
255{
256protected:
257
258 static void Init (PRUnichar * &aElem) { aElem = NULL; }
259
260 static void Uninit (PRUnichar * &aElem)
261 {
262 if (aElem)
263 {
264 ::SysFreeString (aElem);
265 aElem = NULL;
266 }
267 }
268
269 static void Copy (const PRUnichar * aFrom, PRUnichar * &aTo)
270 {
271 AssertCompile (sizeof (PRUnichar) == sizeof (OLECHAR));
272 aTo = aFrom ? ::SysAllocString ((const OLECHAR *) aFrom) : NULL;
273 }
274
275public:
276
277 /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard */
278 static const PRUnichar **__asInParam_Arr (PRUnichar **aArr)
279 {
280 return const_cast <const PRUnichar **> (aArr);
281 }
282 static const PRUnichar **__asInParam_Arr (const PRUnichar **aArr) { return aArr; }
283};
284
285template<>
286struct SafeArrayTraits <const PRUnichar *>
287{
288protected:
289
290 static void Init (const PRUnichar * &aElem) { aElem = NULL; }
291 static void Uninit (const PRUnichar * &aElem)
292 {
293 if (aElem)
294 {
295 ::SysFreeString (const_cast <PRUnichar *> (aElem));
296 aElem = NULL;
297 }
298 }
299
300 static void Copy (const PRUnichar * aFrom, const PRUnichar * &aTo)
301 {
302 AssertCompile (sizeof (PRUnichar) == sizeof (OLECHAR));
303 aTo = aFrom ? ::SysAllocString ((const OLECHAR *) aFrom) : NULL;
304 }
305
306public:
307
308 /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard */
309 static const PRUnichar **__asInParam_Arr (const PRUnichar **aArr) { return aArr; }
310};
311
312template<>
313struct SafeArrayTraits <nsID *>
314{
315protected:
316
317 static void Init (nsID * &aElem) { aElem = NULL; }
318
319 static void Uninit (nsID * &aElem)
320 {
321 if (aElem)
322 {
323 ::nsMemory::Free (aElem);
324 aElem = NULL;
325 }
326 }
327
328 static void Copy (const nsID * aFrom, nsID * &aTo)
329 {
330 if (aFrom)
331 {
332 aTo = (nsID *) ::nsMemory::Alloc (sizeof (nsID));
333 if (aTo)
334 *aTo = *aFrom;
335 }
336 else
337 aTo = NULL;
338 }
339
340 /* This specification is also reused for SafeConstGUIDArray, so provide a
341 * no-op Init() and Uninit() which are necessary for SafeArray<> but should
342 * be never called in context of SafeConstGUIDArray. */
343
344 static void Init (const nsID * &aElem) { NOREF (aElem); AssertFailed(); }
345 static void Uninit (const nsID * &aElem) { NOREF (aElem); AssertFailed(); }
346
347public:
348
349 /** Magic to workaround strict rules of par. 4.4.4 of the C++ standard. */
350 static const nsID **__asInParam_Arr (nsID **aArr)
351 {
352 return const_cast <const nsID **> (aArr);
353 }
354 static const nsID **__asInParam_Arr (const nsID **aArr) { return aArr; }
355};
356
357#else /* defined (VBOX_WITH_XPCOM) */
358
359////////////////////////////////////////////////////////////////////////////////
360
361struct SafeArrayTraitsBase
362{
363protected:
364
365 static SAFEARRAY *CreateSafeArray (VARTYPE aVarType, SAFEARRAYBOUND *aBound)
366 { return SafeArrayCreate (aVarType, 1, aBound); }
367};
368
369/**
370 * Provides various helpers for SafeArray.
371 *
372 * @param T Type of array elements.
373 *
374 * Specializations of this template must provide the following methods:
375 *
376 // Returns the VARTYPE of COM SafeArray elements to be used for T
377 static VARTYPE VarType();
378
379 // Returns the number of VarType() elements necessary for aSize
380 // elements of T
381 static ULONG VarCount (size_t aSize);
382
383 // Returns the number of elements of T that fit into the given number of
384 // VarType() elements (opposite to VarCount (size_t aSize)).
385 static size_t Size (ULONG aVarCount);
386
387 // Creates a deep copy of aFrom and stores it in aTo
388 static void Copy (ULONG aFrom, ULONG &aTo);
389 */
390template <typename T>
391struct SafeArrayTraits : public SafeArrayTraitsBase
392{
393protected:
394
395 // Arbitrary types are treated as passed by value and each value is
396 // represented by a number of VT_Ix type elements where VT_Ix has the
397 // biggest possible bitness necessary to represent T w/o a gap. COM enums
398 // fall into this category.
399
400 static VARTYPE VarType()
401 {
402 if (sizeof (T) % 8 == 0) return VT_I8;
403 if (sizeof (T) % 4 == 0) return VT_I4;
404 if (sizeof (T) % 2 == 0) return VT_I2;
405 return VT_I1;
406 }
407
408 static ULONG VarCount (size_t aSize)
409 {
410 if (sizeof (T) % 8 == 0) return (ULONG) ((sizeof (T) / 8) * aSize);
411 if (sizeof (T) % 4 == 0) return (ULONG) ((sizeof (T) / 4) * aSize);
412 if (sizeof (T) % 2 == 0) return (ULONG) ((sizeof (T) / 2) * aSize);
413 return (ULONG) (sizeof (T) * aSize);
414 }
415
416 static size_t Size (ULONG aVarCount)
417 {
418 if (sizeof (T) % 8 == 0) return (size_t) (aVarCount * 8) / sizeof (T);
419 if (sizeof (T) % 4 == 0) return (size_t) (aVarCount * 4) / sizeof (T);
420 if (sizeof (T) % 2 == 0) return (size_t) (aVarCount * 2) / sizeof (T);
421 return (size_t) aVarCount / sizeof (T);
422 }
423
424 static void Copy (T aFrom, T &aTo) { aTo = aFrom; }
425};
426
427template <typename T>
428struct SafeArrayTraits <T *>
429{
430 // Arbitrary pointer types are not supported
431};
432
433/* Although the generic SafeArrayTraits template would work for all integers,
434 * we specialize it for some of them in order to use the correct VT_ type */
435
436template<>
437struct SafeArrayTraits <LONG> : public SafeArrayTraitsBase
438{
439protected:
440
441 static VARTYPE VarType() { return VT_I4; }
442 static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
443 static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
444
445 static void Copy (LONG aFrom, LONG &aTo) { aTo = aFrom; }
446};
447
448template<>
449struct SafeArrayTraits <ULONG> : public SafeArrayTraitsBase
450{
451protected:
452
453 static VARTYPE VarType() { return VT_UI4; }
454 static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
455 static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
456
457 static void Copy (ULONG aFrom, ULONG &aTo) { aTo = aFrom; }
458};
459
460template<>
461struct SafeArrayTraits <LONG64> : public SafeArrayTraitsBase
462{
463protected:
464
465 static VARTYPE VarType() { return VT_I8; }
466 static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
467 static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
468
469 static void Copy (LONG64 aFrom, LONG64 &aTo) { aTo = aFrom; }
470};
471
472template<>
473struct SafeArrayTraits <ULONG64> : public SafeArrayTraitsBase
474{
475protected:
476
477 static VARTYPE VarType() { return VT_UI8; }
478 static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
479 static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
480
481 static void Copy (ULONG64 aFrom, ULONG64 &aTo) { aTo = aFrom; }
482};
483
484template<>
485struct SafeArrayTraits <BSTR> : public SafeArrayTraitsBase
486{
487protected:
488
489 static VARTYPE VarType() { return VT_BSTR; }
490 static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
491 static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
492
493 static void Copy (BSTR aFrom, BSTR &aTo)
494 {
495 aTo = aFrom ? ::SysAllocString ((const OLECHAR *) aFrom) : NULL;
496 }
497};
498
499template<>
500struct SafeArrayTraits <GUID> : public SafeArrayTraitsBase
501{
502protected:
503
504 /* Use the 64-bit unsigned integer type for GUID */
505 static VARTYPE VarType() { return VT_UI8; }
506
507 /* GUID is 128 bit, so we need two VT_UI8 */
508 static ULONG VarCount (size_t aSize)
509 {
510 AssertCompileSize (GUID, 16);
511 return (ULONG) (aSize * 2);
512 }
513
514 static size_t Size (ULONG aVarCount) { return (size_t) aVarCount / 2; }
515
516 static void Copy (GUID aFrom, GUID &aTo) { aTo = aFrom; }
517};
518
519/**
520 * Helper for SafeArray::__asOutParam() that automatically updates m.raw after a
521 * non-NULL m.arr assignment.
522 */
523class OutSafeArrayDipper
524{
525 OutSafeArrayDipper (SAFEARRAY **aArr, void **aRaw)
526 : arr (aArr), raw (aRaw) { Assert (*aArr == NULL && *aRaw == NULL); }
527
528 SAFEARRAY **arr;
529 void **raw;
530
531 template <class, class> friend class SafeArray;
532
533public:
534
535 ~OutSafeArrayDipper()
536 {
537 if (*arr != NULL)
538 {
539 HRESULT rc = SafeArrayAccessData (*arr, raw);
540 AssertComRC (rc);
541 }
542 }
543
544 operator SAFEARRAY **() { return arr; }
545};
546
547#endif /* defined (VBOX_WITH_XPCOM) */
548
549////////////////////////////////////////////////////////////////////////////////
550
551/**
552 * The SafeArray class represents the safe array type used in COM to pass arrays
553 * to/from interface methods.
554 *
555 * This helper class hides all MSCOM/XPCOM specific implementation details and,
556 * together with ComSafeArrayIn, ComSafeArrayOut and ComSafeArrayRet macros,
557 * provides a platform-neutral way to handle safe arrays in the method
558 * implementation.
559 *
560 * When an instance of this class is destroyed, it automatically frees all
561 * resources occupied by individual elements of the array as well as by the
562 * array itself. However, when the value of an element is manually changed
563 * using #operator[] or by accessing array data through the #raw() pointer, it is
564 * the caller's responsibility to free resources occupied by the previous
565 * element's value.
566 *
567 * Also, objects of this class do not support copy and assignment operations and
568 * therefore cannot be returned from functions by value. In other words, this
569 * class is just a temporary storage for handling interface method calls and not
570 * intended to be used to store arrays as data members and such -- you should
571 * use normal list/vector classes for that.
572 *
573 * @note The current implementation supports only one-dimensional arrays.
574 *
575 * @note This class is not thread-safe.
576 */
577template <typename T, class Traits = SafeArrayTraits <T> >
578class SafeArray : public Traits
579{
580public:
581
582 /**
583 * Creates a null array.
584 */
585 SafeArray() {}
586
587 /**
588 * Creates a new array of the given size. All elements of the newly created
589 * array initialized with null values.
590 *
591 * @param aSize Initial number of elements in the array.
592 *
593 * @note If this object remains null after construction it means that there
594 * was not enough memory for creating an array of the requested size.
595 * The constructor will also assert in this case.
596 */
597 SafeArray (size_t aSize) { resize (aSize); }
598
599 /**
600 * Weakly attaches this instance to the existing array passed in a method
601 * parameter declared using the ComSafeArrayIn macro. When using this call,
602 * always wrap the parameter name in the ComSafeArrayInArg macro call like
603 * this:
604 * <pre>
605 * SafeArray safeArray (ComSafeArrayInArg (aArg));
606 * </pre>
607 *
608 * Note that this constructor doesn't take the ownership of the array. In
609 * particular, it means that operations that operate on the ownership (e.g.
610 * #detachTo()) are forbidden and will assert.
611 *
612 * @param aArg Input method parameter to attach to.
613 */
614 SafeArray (ComSafeArrayIn (T, aArg))
615 {
616#if defined (VBOX_WITH_XPCOM)
617
618 AssertReturnVoid (aArg != NULL);
619
620 m.size = aArgSize;
621 m.arr = aArg;
622 m.isWeak = true;
623
624#else /* defined (VBOX_WITH_XPCOM) */
625
626 AssertReturnVoid (aArg != NULL);
627 SAFEARRAY *arg = *aArg;
628
629 if (arg)
630 {
631 AssertReturnVoid (arg->cDims == 1);
632
633 VARTYPE vt;
634 HRESULT rc = SafeArrayGetVartype (arg, &vt);
635 AssertComRCReturnVoid (rc);
636 AssertMsgReturnVoid (vt == VarType(),
637 ("Expected vartype %d, got %d.\n",
638 VarType(), vt));
639
640 rc = SafeArrayAccessData (arg, (void HUGEP **) &m.raw);
641 AssertComRCReturnVoid (rc);
642 }
643
644 m.arr = arg;
645 m.isWeak = true;
646
647#endif /* defined (VBOX_WITH_XPCOM) */
648 }
649
650 /**
651 * Creates a deep copy of the given standard C++ container that stores
652 * T objects.
653 *
654 * @param aCntr Container object to copy.
655 *
656 * @param C Standard C++ container template class (normally deduced from
657 * @c aCntr).
658 */
659 template <template <typename, typename> class C, class A>
660 SafeArray (const C <T, A> & aCntr)
661 {
662 resize (aCntr.size());
663 AssertReturnVoid (!isNull());
664
665 size_t i = 0;
666 for (typename C <T, A>::const_iterator it = aCntr.begin();
667 it != aCntr.end(); ++ it, ++ i)
668#if defined (VBOX_WITH_XPCOM)
669 Copy (*it, m.arr [i]);
670#else
671 Copy (*it, m.raw [i]);
672#endif
673 }
674
675 /**
676 * Creates a deep copy of the given standard C++ map that stores T objects
677 * as values.
678 *
679 * @param aMap Map object to copy.
680 *
681 * @param C Standard C++ map template class (normally deduced from
682 * @c aCntr).
683 * @param L Standard C++ compare class (deduced from @c aCntr).
684 * @param A Standard C++ allocator class (deduced from @c aCntr).
685 * @param K Map key class (deduced from @c aCntr).
686 */
687 template <template <typename, typename, typename, typename>
688 class C, class L, class A, class K>
689 SafeArray (const C <K, T, L, A> & aMap)
690 {
691 typedef C <K, T, L, A> Map;
692
693 resize (aMap.size());
694 AssertReturnVoid (!isNull());
695
696 int i = 0;
697 for (typename Map::const_iterator it = aMap.begin();
698 it != aMap.end(); ++ it, ++ i)
699#if defined (VBOX_WITH_XPCOM)
700 Copy (it->second, m.arr [i]);
701#else
702 Copy (it->second, m.raw [i]);
703#endif
704 }
705
706 /**
707 * Destroys this instance after calling #setNull() to release allocated
708 * resources. See #setNull() for more details.
709 */
710 virtual ~SafeArray() { setNull(); }
711
712 /**
713 * Returns @c true if this instance represents a null array.
714 */
715 bool isNull() const { return m.arr == NULL; }
716
717 /**
718 * Resets this instance to null and, if this instance is not a weak one,
719 * releases any resources occupied by the array data.
720 *
721 * @note This method destroys (cleans up) all elements of the array using
722 * the corresponding cleanup routine for the element type before the
723 * array itself is destroyed.
724 */
725 virtual void setNull() { m.uninit(); }
726
727 /**
728 * Returns @c true if this instance is weak. A weak instance doesn't own the
729 * array data and therefore operations manipulating the ownership (e.g.
730 * #detachTo()) are forbidden and will assert.
731 */
732 bool isWeak() const { return m.isWeak; }
733
734 /** Number of elements in the array. */
735 size_t size() const
736 {
737#if defined (VBOX_WITH_XPCOM)
738 if (m.arr)
739 return m.size;
740 return 0;
741#else
742 if (m.arr)
743 return Size (m.arr->rgsabound [0].cElements);
744 return 0;
745#endif
746 }
747
748 /**
749 * Appends a copy of the given element at the end of the array.
750 *
751 * The array size is increased by one by this method and the additional
752 * space is allocated as needed.
753 *
754 * This method is handy in cases where you want to assign a copy of the
755 * existing value to the array element, for example:
756 * <tt>Bstr string; array.push_back (string);</tt>. If you create a string
757 * just to put it in the array, you may find #appendedRaw() more useful.
758 *
759 * @param aElement Element to append.
760 *
761 * @return @c true on success and @c false if there is not enough
762 * memory for resizing.
763 */
764 bool push_back (const T &aElement)
765 {
766 if (!ensureCapacity (size() + 1))
767 return false;
768
769#if defined (VBOX_WITH_XPCOM)
770 Copy (aElement, m.arr [m.size]);
771 ++ m.size;
772#else
773 Copy (aElement, m.raw [size() - 1]);
774#endif
775 return true;
776 }
777
778 /**
779 * Appends an empty element at the end of the array and returns a raw
780 * pointer to it suitable for assigning a raw value (w/o constructing a
781 * copy).
782 *
783 * The array size is increased by one by this method and the additional
784 * space is allocated as needed.
785 *
786 * Note that in case of raw assignment, value ownership (for types with
787 * dynamically allocated data and for interface pointers) is transferred to
788 * the safe array object.
789 *
790 * This method is handy for operations like
791 * <tt>Bstr ("foo").detachTo (array.appendedRaw());</tt>. Don't use it as
792 * an l-value (<tt>array.appendedRaw() = SysAllocString (L"tralala");</tt>)
793 * since this doesn't check for a NULL condition; use #resize() and
794 * #setRawAt() instead. If you need to assign a copy of the existing value
795 * instead of transferring the ownership, look at #push_back().
796 *
797 * @return Raw pointer to the added element or NULL if no memory.
798 */
799 T *appendedRaw()
800 {
801 if (!ensureCapacity (size() + 1))
802 return NULL;
803
804#if defined (VBOX_WITH_XPCOM)
805 Init (m.arr [m.size]);
806 ++ m.size;
807 return &m.arr [m.size - 1];
808#else
809 /* nothing to do here, SafeArrayCreate() has performed element
810 * initialization */
811 return &m.raw [size() - 1];
812#endif
813 }
814
815 /**
816 * Resizes the array preserving its contents when possible. If the new size
817 * is larger than the old size, new elements are initialized with null
818 * values. If the new size is less than the old size, the contents of the
819 * array beyond the new size is lost.
820 *
821 * @param aNewSize New number of elements in the array.
822 * @return @c true on success and @c false if there is not enough
823 * memory for resizing.
824 */
825 bool resize (size_t aNewSize)
826 {
827 if (!ensureCapacity (aNewSize))
828 return false;
829
830#if defined (VBOX_WITH_XPCOM)
831
832 if (m.size < aNewSize)
833 {
834 /* initialize the new elements */
835 for (size_t i = m.size; i < aNewSize; ++ i)
836 Init (m.arr [i]);
837 }
838
839 m.size = aNewSize;
840#else
841 /* nothing to do here, SafeArrayCreate() has performed element
842 * initialization */
843#endif
844 return true;
845 }
846
847 /**
848 * Reinitializes this instance by preallocating space for the given number
849 * of elements. The previous array contents is lost.
850 *
851 * @param aNewSize New number of elements in the array.
852 * @return @c true on success and @c false if there is not enough
853 * memory for resizing.
854 */
855 bool reset (size_t aNewSize)
856 {
857 m.uninit();
858 return resize (aNewSize);
859 }
860
861 /**
862 * Returns a pointer to the raw array data. Use this raw pointer with care
863 * as no type or bound checking is done for you in this case.
864 *
865 * @note This method returns @c NULL when this instance is null.
866 * @see #operator[]
867 */
868 T *raw()
869 {
870#if defined (VBOX_WITH_XPCOM)
871 return m.arr;
872#else
873 return m.raw;
874#endif
875 }
876
877 /**
878 * Const version of #raw().
879 */
880 const T *raw() const
881 {
882#if defined (VBOX_WITH_XPCOM)
883 return m.arr;
884#else
885 return m.raw;
886#endif
887 }
888
889 /**
890 * Array access operator that returns an array element by reference. A bit
891 * safer than #raw(): asserts and returns an invalid reference if this
892 * instance is null or if the index is out of bounds.
893 *
894 * @note For weak instances, this call will succeed but the behavior of
895 * changing the contents of an element of the weak array instance is
896 * undefined and may lead to a program crash on some platforms.
897 */
898 T &operator[] (size_t aIdx)
899 {
900 AssertReturn (m.arr != NULL, *((T *) NULL));
901 AssertReturn (aIdx < size(), *((T *) NULL));
902#if defined (VBOX_WITH_XPCOM)
903 return m.arr [aIdx];
904#else
905 AssertReturn (m.raw != NULL, *((T *) NULL));
906 return m.raw [aIdx];
907#endif
908 }
909
910 /**
911 * Const version of #operator[] that returns an array element by value.
912 */
913 const T operator[] (size_t aIdx) const
914 {
915 AssertReturn (m.arr != NULL, *((T *) NULL));
916 AssertReturn (aIdx < size(), *((T *) NULL));
917#if defined (VBOX_WITH_XPCOM)
918 return m.arr [aIdx];
919#else
920 AssertReturn (m.raw != NULL, *((T *) NULL));
921 return m.raw [aIdx];
922#endif
923 }
924
925 /**
926 * Creates a copy of this array and stores it in a method parameter declared
927 * using the ComSafeArrayOut macro. When using this call, always wrap the
928 * parameter name in the ComSafeArrayOutArg macro call like this:
929 * <pre>
930 * safeArray.cloneTo (ComSafeArrayOutArg (aArg));
931 * </pre>
932 *
933 * @note It is assumed that the ownership of the returned copy is
934 * transferred to the caller of the method and he is responsible to free the
935 * array data when it is no longer needed.
936 *
937 * @param aArg Output method parameter to clone to.
938 */
939 virtual const SafeArray &cloneTo (ComSafeArrayOut (T, aArg)) const
940 {
941 /// @todo Implement me!
942#if defined (VBOX_WITH_XPCOM)
943 NOREF (aArgSize);
944 NOREF (aArg);
945#else
946 NOREF (aArg);
947#endif
948 AssertFailedReturn (*this);
949 }
950
951 /**
952 * Transfers the ownership of this array's data to the specified location
953 * declared using the ComSafeArrayOut macro and makes this array a null
954 * array. When using this call, always wrap the parameter name in the
955 * ComSafeArrayOutArg macro call like this:
956 * <pre>
957 * safeArray.detachTo (ComSafeArrayOutArg (aArg));
958 * </pre>
959 *
960 * Detaching the null array is also possible in which case the location will
961 * receive NULL.
962 *
963 * @note Since the ownership of the array data is transferred to the
964 * caller of the method, he is responsible to free the array data when it is
965 * no longer needed.
966 *
967 * @param aArg Location to detach to.
968 */
969 virtual SafeArray &detachTo (ComSafeArrayOut (T, aArg))
970 {
971 AssertReturn (m.isWeak == false, *this);
972
973#if defined (VBOX_WITH_XPCOM)
974
975 AssertReturn (aArgSize != NULL, *this);
976 AssertReturn (aArg != NULL, *this);
977
978 *aArgSize = m.size;
979 *aArg = m.arr;
980
981 m.isWeak = false;
982 m.size = 0;
983 m.arr = NULL;
984
985#else /* defined (VBOX_WITH_XPCOM) */
986
987 AssertReturn (aArg != NULL, *this);
988 *aArg = m.arr;
989
990 if (m.raw)
991 {
992 HRESULT rc = SafeArrayUnaccessData (m.arr);
993 AssertComRCReturn (rc, *this);
994 m.raw = NULL;
995 }
996
997 m.isWeak = false;
998 m.arr = NULL;
999
1000#endif /* defined (VBOX_WITH_XPCOM) */
1001
1002 return *this;
1003 }
1004
1005 // Public methods for internal purposes only.
1006
1007#if defined (VBOX_WITH_XPCOM)
1008
1009 /** Internal function. Never call it directly. */
1010 PRUint32 *__asOutParam_Size() { setNull(); return &m.size; }
1011
1012 /** Internal function Never call it directly. */
1013 T **__asOutParam_Arr() { Assert (isNull()); return &m.arr; }
1014
1015#else /* defined (VBOX_WITH_XPCOM) */
1016
1017 /** Internal function Never call it directly. */
1018 SAFEARRAY ** __asInParam() { return &m.arr; }
1019
1020 /** Internal function Never call it directly. */
1021 OutSafeArrayDipper __asOutParam()
1022 { setNull(); return OutSafeArrayDipper (&m.arr, (void **) &m.raw); }
1023
1024#endif /* defined (VBOX_WITH_XPCOM) */
1025
1026 static const SafeArray Null;
1027
1028protected:
1029
1030 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(SafeArray)
1031
1032 /**
1033 * Ensures that the array is big enough to contain aNewSize elements.
1034 *
1035 * If the new size is greater than the current capacity, a new array is
1036 * allocated and elements from the old array are copied over. The size of
1037 * the array doesn't change, only the capacity increases (which is always
1038 * greater than the size). Note that the additionally allocated elements are
1039 * left uninitialized by this method.
1040 *
1041 * If the new size is less than the current size, the existing array is
1042 * truncated to the specified size and the elements outside the new array
1043 * boundary are freed.
1044 *
1045 * If the new size is the same as the current size, nothing happens.
1046 *
1047 * @param aNewSize New size of the array.
1048 *
1049 * @return @c true on success and @c false if not enough memory.
1050 */
1051 bool ensureCapacity (size_t aNewSize)
1052 {
1053 AssertReturn (!m.isWeak, false);
1054
1055#if defined (VBOX_WITH_XPCOM)
1056
1057 /* Note: we distinguish between a null array and an empty (zero
1058 * elements) array. Therefore we never use zero in malloc (even if
1059 * aNewSize is zero) to make sure we get a non-null pointer. */
1060
1061 if (m.size == aNewSize && m.arr != NULL)
1062 return true;
1063
1064 /* Allocate in 16-byte pieces. */
1065 size_t newCapacity = RT_MAX ((aNewSize + 15) / 16 * 16, 16);
1066
1067 if (m.capacity != newCapacity)
1068 {
1069 T *newArr = (T *) nsMemory::Alloc (RT_MAX (newCapacity, 1) * sizeof (T));
1070 AssertReturn (newArr != NULL, false);
1071
1072 if (m.arr != NULL)
1073 {
1074 if (m.size > aNewSize)
1075 {
1076 /* Truncation takes place, uninit exceeding elements and
1077 * shrink the size. */
1078 for (size_t i = aNewSize; i < m.size; ++ i)
1079 Uninit (m.arr [i]);
1080
1081 m.size = aNewSize;
1082 }
1083
1084 /* Copy the old contents. */
1085 memcpy (newArr, m.arr, m.size * sizeof (T));
1086 nsMemory::Free ((void *) m.arr);
1087 }
1088
1089 m.arr = newArr;
1090 }
1091 else
1092 {
1093 if (m.size > aNewSize)
1094 {
1095 /* Truncation takes place, uninit exceeding elements and
1096 * shrink the size. */
1097 for (size_t i = aNewSize; i < m.size; ++ i)
1098 Uninit (m.arr [i]);
1099
1100 m.size = aNewSize;
1101 }
1102 }
1103
1104 m.capacity = newCapacity;
1105
1106#else
1107
1108 SAFEARRAYBOUND bound = { VarCount (aNewSize), 0 };
1109 HRESULT rc;
1110
1111 if (m.arr == NULL)
1112 {
1113 m.arr = CreateSafeArray (VarType(), &bound);
1114 AssertReturn (m.arr != NULL, false);
1115 }
1116 else
1117 {
1118 SafeArrayUnaccessData (m.arr);
1119
1120 rc = SafeArrayRedim (m.arr, &bound);
1121 AssertComRCReturn (rc == S_OK, false);
1122 }
1123
1124 rc = SafeArrayAccessData (m.arr, (void HUGEP **) &m.raw);
1125 AssertComRCReturn (rc, false);
1126
1127#endif
1128 return true;
1129 }
1130
1131 struct Data
1132 {
1133 Data()
1134 : isWeak (false)
1135#if defined (VBOX_WITH_XPCOM)
1136 , capacity (0), size (0), arr (NULL)
1137#else
1138 , arr (NULL), raw (NULL)
1139#endif
1140 {}
1141
1142 ~Data() { uninit(); }
1143
1144 void uninit()
1145 {
1146#if defined (VBOX_WITH_XPCOM)
1147
1148 if (arr)
1149 {
1150 if (!isWeak)
1151 {
1152 for (size_t i = 0; i < size; ++ i)
1153 Uninit (arr [i]);
1154
1155 nsMemory::Free ((void *) arr);
1156 }
1157 else
1158 isWeak = false;
1159
1160 arr = NULL;
1161 }
1162
1163 size = capacity = 0;
1164
1165#else /* defined (VBOX_WITH_XPCOM) */
1166
1167 if (arr)
1168 {
1169 if (raw)
1170 {
1171 SafeArrayUnaccessData (arr);
1172 raw = NULL;
1173 }
1174
1175 if (!isWeak)
1176 {
1177 HRESULT rc = SafeArrayDestroy (arr);
1178 AssertComRCReturnVoid (rc);
1179 }
1180 else
1181 isWeak = false;
1182
1183 arr = NULL;
1184 }
1185
1186#endif /* defined (VBOX_WITH_XPCOM) */
1187 }
1188
1189 bool isWeak : 1;
1190
1191#if defined (VBOX_WITH_XPCOM)
1192 PRUint32 capacity;
1193 PRUint32 size;
1194 T *arr;
1195#else
1196 SAFEARRAY *arr;
1197 T *raw;
1198#endif
1199 };
1200
1201 Data m;
1202};
1203
1204////////////////////////////////////////////////////////////////////////////////
1205
1206#if defined (VBOX_WITH_XPCOM)
1207
1208/**
1209 * Version of com::SafeArray for arrays of GUID.
1210 *
1211 * In MS COM, GUID arrays store GUIDs by value and therefore input arrays are
1212 * represented using |GUID *| and out arrays -- using |GUID **|. In XPCOM,
1213 * GUID arrays store pointers to nsID so that input arrays are |const nsID **|
1214 * and out arrays are |nsID ***|. Due to this difference, it is impossible to
1215 * work with arrays of GUID on both platforms by simply using com::SafeArray
1216 * <GUID>. This class is intended to provide some level of cross-platform
1217 * behavior.
1218 *
1219 * The basic usage pattern is basically similar to com::SafeArray<> except that
1220 * you use ComSafeGUIDArrayIn* and ComSafeGUIDArrayOut* macros instead of
1221 * ComSafeArrayIn* and ComSafeArrayOut*. Another important nuance is that the
1222 * raw() array type is different (nsID **, or GUID ** on XPCOM and GUID * on MS
1223 * COM) so it is recommended to use operator[] instead which always returns a
1224 * GUID by value.
1225 *
1226 * Note that due to const modifiers, you cannot use SafeGUIDArray for input GUID
1227 * arrays. Please use SafeConstGUIDArray for this instead.
1228 *
1229 * Other than mentioned above, the functionality of this class is equivalent to
1230 * com::SafeArray<>. See the description of that template and its methods for
1231 * more information.
1232 *
1233 * Output GUID arrays are handled by a separate class, SafeGUIDArrayOut, since
1234 * this class cannot handle them because of const modifiers.
1235 */
1236class SafeGUIDArray : public SafeArray <nsID *>
1237{
1238public:
1239
1240 typedef SafeArray <nsID *> Base;
1241
1242 class nsIDRef
1243 {
1244 public:
1245
1246 nsIDRef (nsID * &aVal) : mVal (aVal) {}
1247
1248 operator const nsID &() const { return mVal ? *mVal : *Empty; }
1249 operator nsID() const { return mVal ? *mVal : *Empty; }
1250
1251 const nsID *operator&() const { return mVal ? mVal : Empty; }
1252
1253 nsIDRef &operator= (const nsID &aThat)
1254 {
1255 if (mVal == NULL)
1256 Copy (&aThat, mVal);
1257 else
1258 *mVal = aThat;
1259 return *this;
1260 }
1261
1262 private:
1263
1264 nsID * &mVal;
1265
1266 static const nsID *Empty;
1267
1268 friend class SafeGUIDArray;
1269 };
1270
1271 /** See SafeArray<>::SafeArray(). */
1272 SafeGUIDArray() {}
1273
1274 /** See SafeArray<>::SafeArray (size_t). */
1275 SafeGUIDArray (size_t aSize) : Base (aSize) {}
1276
1277 /**
1278 * Array access operator that returns an array element by reference. As a
1279 * special case, the return value of this operator on XPCOM is an nsID (GUID)
1280 * reference, instead of an nsID pointer (the actual SafeArray template
1281 * argument), for compatibility with the MS COM version.
1282 *
1283 * The rest is equivalent to SafeArray<>::operator[].
1284 */
1285 nsIDRef operator[] (size_t aIdx)
1286 {
1287 Assert (m.arr != NULL);
1288 Assert (aIdx < size());
1289 return nsIDRef (m.arr [aIdx]);
1290 }
1291
1292 /**
1293 * Const version of #operator[] that returns an array element by value.
1294 */
1295 const nsID &operator[] (size_t aIdx) const
1296 {
1297 Assert (m.arr != NULL);
1298 Assert (aIdx < size());
1299 return m.arr [aIdx] ? *m.arr [aIdx] : *nsIDRef::Empty;
1300 }
1301};
1302
1303/**
1304 * Version of com::SafeArray for const arrays of GUID.
1305 *
1306 * This class is used to work with input GUID array parameters in method
1307 * implementations. See SafeGUIDArray for more details.
1308 */
1309class SafeConstGUIDArray : public SafeArray <const nsID *,
1310 SafeArrayTraits <nsID *> >
1311{
1312public:
1313
1314 typedef SafeArray <const nsID *, SafeArrayTraits <nsID *> > Base;
1315
1316 /** See SafeArray<>::SafeArray(). */
1317 SafeConstGUIDArray() {}
1318
1319 /* See SafeArray<>::SafeArray (ComSafeArrayIn (T, aArg)). */
1320 SafeConstGUIDArray (ComSafeGUIDArrayIn (aArg))
1321 : Base (ComSafeGUIDArrayInArg (aArg)) {}
1322
1323 /**
1324 * Array access operator that returns an array element by reference. As a
1325 * special case, the return value of this operator on XPCOM is nsID (GUID)
1326 * instead of nsID *, for compatibility with the MS COM version.
1327 *
1328 * The rest is equivalent to SafeArray<>::operator[].
1329 */
1330 const nsID &operator[] (size_t aIdx) const
1331 {
1332 AssertReturn (m.arr != NULL, **((const nsID * *) NULL));
1333 AssertReturn (aIdx < size(), **((const nsID * *) NULL));
1334 return *m.arr [aIdx];
1335 }
1336
1337private:
1338
1339 /* These are disabled because of const. */
1340 bool reset (size_t aNewSize) { NOREF (aNewSize); return false; }
1341};
1342
1343#else /* defined (VBOX_WITH_XPCOM) */
1344
1345typedef SafeArray <GUID> SafeGUIDArray;
1346typedef SafeArray <const GUID, SafeArrayTraits <GUID> > SafeConstGUIDArray;
1347
1348#endif /* defined (VBOX_WITH_XPCOM) */
1349
1350////////////////////////////////////////////////////////////////////////////////
1351
1352#if defined (VBOX_WITH_XPCOM)
1353
1354template <class I>
1355struct SafeIfaceArrayTraits
1356{
1357protected:
1358
1359 static void Init (I * &aElem) { aElem = NULL; }
1360 static void Uninit (I * &aElem)
1361 {
1362 if (aElem)
1363 {
1364 aElem->Release();
1365 aElem = NULL;
1366 }
1367 }
1368
1369 static void Copy (I * aFrom, I * &aTo)
1370 {
1371 if (aFrom != NULL)
1372 {
1373 aTo = aFrom;
1374 aTo->AddRef();
1375 }
1376 else
1377 aTo = NULL;
1378 }
1379
1380public:
1381
1382 /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard. */
1383 static I **__asInParam_Arr (I **aArr) { return aArr; }
1384 static I **__asInParam_Arr (const I **aArr) { return const_cast <I **> (aArr); }
1385};
1386
1387#else /* defined (VBOX_WITH_XPCOM) */
1388
1389template <class I>
1390struct SafeIfaceArrayTraits
1391{
1392protected:
1393
1394 static VARTYPE VarType() { return VT_DISPATCH; }
1395 static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
1396 static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
1397
1398 static void Copy (I * aFrom, I * &aTo)
1399 {
1400 if (aFrom != NULL)
1401 {
1402 aTo = aFrom;
1403 aTo->AddRef();
1404 }
1405 else
1406 aTo = NULL;
1407 }
1408
1409 static SAFEARRAY *CreateSafeArray (VARTYPE aVarType, SAFEARRAYBOUND *aBound)
1410 {
1411 NOREF (aVarType);
1412 return SafeArrayCreateEx (VT_DISPATCH, 1, aBound, (PVOID) &_ATL_IIDOF (I));
1413 }
1414};
1415
1416#endif /* defined (VBOX_WITH_XPCOM) */
1417
1418////////////////////////////////////////////////////////////////////////////////
1419
1420/**
1421 * Version of com::SafeArray for arrays of interface pointers.
1422 *
1423 * Except that it manages arrays of interface pointers, the usage of this class
1424 * is identical to com::SafeArray.
1425 *
1426 * @param I Interface class (no asterisk).
1427 */
1428template <class I>
1429class SafeIfaceArray : public SafeArray <I *, SafeIfaceArrayTraits <I> >
1430{
1431public:
1432
1433 typedef SafeArray <I *, SafeIfaceArrayTraits <I> > Base;
1434
1435 /**
1436 * Creates a null array.
1437 */
1438 SafeIfaceArray() {}
1439
1440 /**
1441 * Creates a new array of the given size. All elements of the newly created
1442 * array initialized with null values.
1443 *
1444 * @param aSize Initial number of elements in the array. Must be greater
1445 * than 0.
1446 *
1447 * @note If this object remains null after construction it means that there
1448 * was not enough memory for creating an array of the requested size.
1449 * The constructor will also assert in this case.
1450 */
1451 SafeIfaceArray (size_t aSize) { Base::resize (aSize); }
1452
1453 /**
1454 * Weakly attaches this instance to the existing array passed in a method
1455 * parameter declared using the ComSafeArrayIn macro. When using this call,
1456 * always wrap the parameter name in the ComSafeArrayOutArg macro call like
1457 * this:
1458 * <pre>
1459 * SafeArray safeArray (ComSafeArrayInArg (aArg));
1460 * </pre>
1461 *
1462 * Note that this constructor doesn't take the ownership of the array. In
1463 * particular, this means that operations that operate on the ownership
1464 * (e.g. #detachTo()) are forbidden and will assert.
1465 *
1466 * @param aArg Input method parameter to attach to.
1467 */
1468 SafeIfaceArray (ComSafeArrayIn (I *, aArg))
1469 {
1470#if defined (VBOX_WITH_XPCOM)
1471
1472 AssertReturnVoid (aArg != NULL);
1473
1474 Base::m.size = aArgSize;
1475 Base::m.arr = aArg;
1476 Base::m.isWeak = true;
1477
1478#else /* defined (VBOX_WITH_XPCOM) */
1479
1480 AssertReturnVoid (aArg != NULL);
1481 SAFEARRAY *arg = *aArg;
1482
1483 if (arg)
1484 {
1485 AssertReturnVoid (arg->cDims == 1);
1486
1487 VARTYPE vt;
1488 HRESULT rc = SafeArrayGetVartype (arg, &vt);
1489 AssertComRCReturnVoid (rc);
1490 AssertMsgReturnVoid (vt == VT_UNKNOWN || vt == VT_DISPATCH,
1491 ("Expected vartype VT_UNKNOWN, got %d.\n",
1492 VarType(), vt));
1493 GUID guid;
1494 rc = SafeArrayGetIID (arg, &guid);
1495 AssertComRCReturnVoid (rc);
1496 AssertMsgReturnVoid (InlineIsEqualGUID (_ATL_IIDOF (I), guid),
1497 ("Expected IID {%Vuuid}, got {%Vuuid}.\n",
1498 &_ATL_IIDOF (I), &guid));
1499
1500 rc = SafeArrayAccessData (arg, (void HUGEP **) &m.raw);
1501 AssertComRCReturnVoid (rc);
1502 }
1503
1504 m.arr = arg;
1505 m.isWeak = true;
1506
1507#endif /* defined (VBOX_WITH_XPCOM) */
1508 }
1509
1510 /**
1511 * Creates a deep copy of the given standard C++ container that stores
1512 * interface pointers as objects of the ComPtr <I> class.
1513 *
1514 * @param aCntr Container object to copy.
1515 *
1516 * @param C Standard C++ container template class (normally deduced from
1517 * @c aCntr).
1518 * @param A Standard C++ allocator class (deduced from @c aCntr).
1519 * @param OI Argument to the ComPtr template (deduced from @c aCntr).
1520 */
1521 template <template <typename, typename> class C, class A, class OI>
1522 SafeIfaceArray (const C <ComPtr <OI>, A> & aCntr)
1523 {
1524 typedef C <ComPtr <OI>, A> List;
1525
1526 Base::resize (aCntr.size());
1527 AssertReturnVoid (!Base::isNull());
1528
1529 int i = 0;
1530 for (typename List::const_iterator it = aCntr.begin();
1531 it != aCntr.end(); ++ it, ++ i)
1532#if defined (VBOX_WITH_XPCOM)
1533 Copy (*it, Base::m.arr [i]);
1534#else
1535 Copy (*it, Base::m.raw [i]);
1536#endif
1537 }
1538
1539 /**
1540 * Creates a deep copy of the given standard C++ container that stores
1541 * interface pointers as objects of the ComObjPtr <I> class.
1542 *
1543 * @param aCntr Container object to copy.
1544 *
1545 * @param C Standard C++ container template class (normally deduced from
1546 * @c aCntr).
1547 * @param A Standard C++ allocator class (deduced from @c aCntr).
1548 * @param OI Argument to the ComObjPtr template (deduced from @c aCntr).
1549 */
1550 template <template <typename, typename> class C, class A, class OI>
1551 SafeIfaceArray (const C <ComObjPtr <OI>, A> & aCntr)
1552 {
1553 typedef C <ComObjPtr <OI>, A> List;
1554
1555 Base::resize (aCntr.size());
1556 AssertReturnVoid (!Base::isNull());
1557
1558 int i = 0;
1559 for (typename List::const_iterator it = aCntr.begin();
1560 it != aCntr.end(); ++ it, ++ i)
1561#if defined (VBOX_WITH_XPCOM)
1562 Copy (*it, Base::m.arr [i]);
1563#else
1564 Copy (*it, Base::m.raw [i]);
1565#endif
1566 }
1567
1568 /**
1569 * Creates a deep copy of the given standard C++ map whose values are
1570 * interface pointers stored as objects of the ComPtr <I> class.
1571 *
1572 * @param aMap Map object to copy.
1573 *
1574 * @param C Standard C++ map template class (normally deduced from
1575 * @c aCntr).
1576 * @param L Standard C++ compare class (deduced from @c aCntr).
1577 * @param A Standard C++ allocator class (deduced from @c aCntr).
1578 * @param K Map key class (deduced from @c aCntr).
1579 * @param OI Argument to the ComPtr template (deduced from @c aCntr).
1580 */
1581 template <template <typename, typename, typename, typename>
1582 class C, class L, class A, class K, class OI>
1583 SafeIfaceArray (const C <K, ComPtr <OI>, L, A> & aMap)
1584 {
1585 typedef C <K, ComPtr <OI>, L, A> Map;
1586
1587 Base::resize (aMap.size());
1588 AssertReturnVoid (!Base::isNull());
1589
1590 int i = 0;
1591 for (typename Map::const_iterator it = aMap.begin();
1592 it != aMap.end(); ++ it, ++ i)
1593#if defined (VBOX_WITH_XPCOM)
1594 Copy (it->second, Base::m.arr [i]);
1595#else
1596 Copy (it->second, Base::m.raw [i]);
1597#endif
1598 }
1599
1600 /**
1601 * Creates a deep copy of the given standard C++ map whose values are
1602 * interface pointers stored as objects of the ComObjPtr <I> class.
1603 *
1604 * @param aMap Map object to copy.
1605 *
1606 * @param C Standard C++ map template class (normally deduced from
1607 * @c aCntr).
1608 * @param L Standard C++ compare class (deduced from @c aCntr).
1609 * @param A Standard C++ allocator class (deduced from @c aCntr).
1610 * @param K Map key class (deduced from @c aCntr).
1611 * @param OI Argument to the ComObjPtr template (deduced from @c aCntr).
1612 */
1613 template <template <typename, typename, typename, typename>
1614 class C, class L, class A, class K, class OI>
1615 SafeIfaceArray (const C <K, ComObjPtr <OI>, L, A> & aMap)
1616 {
1617 typedef C <K, ComObjPtr <OI>, L, A> Map;
1618
1619 Base::resize (aMap.size());
1620 AssertReturnVoid (!Base::isNull());
1621
1622 int i = 0;
1623 for (typename Map::const_iterator it = aMap.begin();
1624 it != aMap.end(); ++ it, ++ i)
1625#if defined (VBOX_WITH_XPCOM)
1626 Copy (it->second, Base::m.arr [i]);
1627#else
1628 Copy (it->second, Base::m.raw [i]);
1629#endif
1630 }
1631};
1632
1633} /* namespace com */
1634
1635/** @} */
1636
1637#endif /* ___VBox_com_array_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette