array.h revision 7a18d4bae4d9ff1216be13970ae7815604b3365b
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * MS COM / XPCOM Abstraction Layer:
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Safe array helper class declaration
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Copyright (C) 2006-2007 innotek GmbH
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * available from http://www.virtualbox.org. This file is free software;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * you can redistribute it and/or modify it under the terms of the GNU
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * General Public License (GPL) as published by the Free Software
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * The contents of this file may alternatively be used under the terms
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * of the Common Development and Distribution License Version 1.0
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * VirtualBox OSE distribution, in which case the provisions of the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * CDDL are applicable instead of those of the GPL.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * You may elect to license modified versions of this file under the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * terms and conditions of either the GPL or the CDDL or both.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync/** @defgroup grp_COM_arrays COM/XPCOM Arrays
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * The COM/XPCOM array support layer provides a cross-platform way to pass
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * arrays to and from COM interface methods and consists of the com::SafeArray
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * template and a set of ComSafeArray* macros part of which is defined in
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * This layer works with interface attributes and method parameters that have
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * the 'safearray="yes"' attribute in the XIDL definition:
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync <interface name="ISomething" ...>
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync <method name="testArrays">
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync <param name="inArr" type="long" dir="in" safearray="yes"/>
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync <param name="outArr" type="long" dir="out" safearray="yes"/>
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync <param name="retArr" type="long" dir="return" safearray="yes"/>
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync </interface>
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Methods generated from this and similar definitions are implemented in
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * component classes using the following declarations:
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync STDMETHOD(TestArrays) (ComSafeArrayIn (LONG, aIn),
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ComSafeArrayOut (LONG, aOut),
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ComSafeArrayOut (LONG, aRet));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * And the following function bodies:
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync STDMETHODIMP Component::TestArrays (ComSafeArrayIn (LONG, aIn),
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ComSafeArrayOut (LONG, aOut),
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ComSafeArrayOut (LONG, aRet))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync if (ComSafeArrayInIsNull (aIn))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return E_INVALIDARG;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync if (ComSafeArrayOutIsNull (aOut))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return E_POINTER;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync if (ComSafeArrayOutIsNull (aRet))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return E_POINTER;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync // Use SafeArray to access the input array parameter
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync com::SafeArray <LONG> in (ComSafeArrayInArg (aIn));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync for (size_t i = 0; i < in.size(); ++ i)
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync LogFlow (("*** in[%u]=%d\n", i, in [i]));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync // Use SafeArray to create the return array (the same technique is used
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync // for output array paramters)
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync SafeArray <LONG> ret (in.size() * 2);
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync for (size_t i = 0; i < in.size(); ++ i)
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ret [i] = in [i];
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ret [i + in.size()] = in [i] * 10;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ret.detachTo (ComSafeArrayOutArg (aRet));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return S_OK;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Such methods can be called from the client code using the following pattern:
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ComPtr <ISomething> component;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync com::SafeArray <LONG> in (3);
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync in [0] = -1;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync in [1] = -2;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync in [2] = -3;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync com::SafeArray <LONG> out;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync com::SafeArray <LONG> ret;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync HRESULT rc = component->TestArrays (ComSafeArrayAsInParam (in),
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ComSafeArrayAsOutParam (out),
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ComSafeArrayAsOutParam (ret));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync if (SUCCEEDED (rc))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync for (size_t i = 0; i < ret.size(); ++ i)
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync printf ("*** ret[%u]=%d\n", i, ret [i]);
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * For interoperability with standard C++ containers, there is a template
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * constructor that takes such a container as argument and performs a deep copy
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * of its contents. This can be used in method implementations like this:
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync STDMETHODIMP Component::COMGETTER(Values) (ComSafeArrayOut (int, aValues))
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync // ... assume there is a |std::list <int> mValues| data member
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync com::SafeArray <int> values (mValues);
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync values.detachTo (ComSafeArrayOutArg (aValues));
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync return S_OK;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * The current implementation of the SafeArray layer supports all types normally
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * allowed in XIDL as array element types (including 'wstring' and 'uuid').
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * However, 'pointer-to-...' types (e.g. 'long *', 'wstring *') are not
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * supported and therefore cannot be used as element types.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Arrays of interface pointers are also supported but they require to use a
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * special SafeArray implementation, com::SafeIfacePointer, which takes the
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * interface class name as a template argument (e.g. com::SafeIfacePointer
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * <IUnknown>). This implementation functions identically to com::SafeArray.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Wraps the given com::SafeArray instance to generate an expression that is
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * suitable for passing it to functions that take input safearray parameters
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * declared using the ComSafeArrayIn marco.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aArray com::SafeArray instance to pass as an input parameter.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync (aArray).size(), (aArray).__asInParam_Arr (aArray.raw())
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Wraps the given com::SafeArray instance to generate an expression that is
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * suitable for passing it to functions that take output safearray parameters
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * declared using the ComSafeArrayOut marco.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aArray com::SafeArray instance to pass as an output parameter.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync (aArray).__asOutParam_Size(), (aArray).__asOutParam_Arr()
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#else /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#define ComSafeArrayAsInParam(aArray) (aArray).__asInParam()
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#define ComSafeArrayAsOutParam(aArray) (aArray).__asOutParam()
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#endif /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync////////////////////////////////////////////////////////////////////////////////
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Contains various helper constants for SafeArray.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync static void Copy (const T &aFrom, T &aTo) { aTo = aFrom; }
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard (that
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * in particular forbid casts of 'char **' to 'const char **'). Then initial
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * reason for this magic is that XPIDL declares input strings
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * (char/PRUnichar pointers) as const but doesn't do so for pointers to
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * arrays. */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync static T *__asInParam_Arr (T *aArr) { return aArr; }
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync static T *__asInParam_Arr (const T *aArr) { return const_cast <T *> (aArr); }
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync // Arbitrary pointers are not supported
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync static void Init (PRUnichar * &aElem) { aElem = NULL; }
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync static void Copy (const PRUnichar * aFrom, PRUnichar * &aTo)
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync AssertCompile (sizeof (PRUnichar) == sizeof (OLECHAR));
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync aTo = aFrom ? ::SysAllocString ((const OLECHAR *) aFrom) : NULL;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync static const PRUnichar **__asInParam_Arr (PRUnichar **aArr)
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync static const PRUnichar **__asInParam_Arr (const PRUnichar **aArr) { return aArr; }
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#else /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync////////////////////////////////////////////////////////////////////////////////
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Contains various helper constants for SafeArray.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync // Arbitrary types are not supported
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync static void Copy (LONG aFrom, LONG &aTo) { aTo = aFrom; }
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync static void Copy (ULONG aFrom, ULONG &aTo) { aTo = aFrom; }
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync aTo = aFrom ? ::SysAllocString ((const OLECHAR *) aFrom) : NULL;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#endif /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync////////////////////////////////////////////////////////////////////////////////
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * The SafeArray class represents the safe array type used in COM to pass arrays
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * to/from interface methods.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * This helper class hides all MSCOM/XPCOM specific implementation details and,
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * together with ComSafeArrayIn, ComSafeArrayOut and ComSafeArrayRet macros,
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * provides a platform-neutral way to handle safe arrays in the method
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * implementation.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * When an instance of this class is destroyed, it automatically frees all
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * resources occupied by individual elements of the array as well as by the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * array itself. However, when the value of an element is manually changed
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * using #operator[] or by acessing array data through the #raw() pointer, it is
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * the caller's responsibility to free resources occupied by the previous
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * element's value.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Also, objects of this class do not support copy and assignment operations and
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * therefore cannot be returned from functions by value. In other words, this
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * class is just a temporary storage for handling interface method calls and not
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * intended to be used to store arrays as data members and such -- you should
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * use normal list/vector classes for that.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @note The current implementation supports only one-dimentional arrays.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @note This class is not thread-safe.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsynctemplate <typename T, class Traits = SafeArrayTraits <T> >
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Creates a null array.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Creates a new array of the given size. All elements of the newly created
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * array initialized with null values.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aSize Initial number of elements in the array. Must be greater
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @note If this object remains null after construction it means that there
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * was not enough memory for creating an array of the requested size.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * The constructor will also assert in this case.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Weakly attaches this instance to the existing array passed in a method
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * parameter declared using the ComSafeArrayIn macro. When using this call,
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * always wrap the parameter name in the ComSafeArrayOutArg macro call like
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * SafeArray safeArray (ComSafeArrayInArg (aArg));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Note that this constructor doesn't take the ownership of the array. In
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * particular, it means that operations that operate on the ownership (e.g.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * #detachTo()) are forbidden and will assert.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aArg Input method parameter to attach to.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#else /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync ("Expected vartype %d, got %d.\n",
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#endif /* defined (VBOX_WITH_XPCOM) */
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Creates a deep copy of the goven standard C++ container.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param aCntr Container object to copy.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param C Standard C++ container template class (normally deduced from
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @c aCntr).
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync for (typename C <T>::const_iterator it = aCntr.begin();
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Destroys this instance after calling #setNull() to release allocated
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * resources. See #setNull() for more details.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Returns @c true if this instance represents a null array.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Resets this instance to null and, if this instance is not a weak one,
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * releases any resources ocuppied by the array data.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @note This method destroys (cleans up) all elements of the array using
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * the corresponding cleanup routine for the element type before the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * array itself is destroyed.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Returns @c true if this instance is weak. A weak instance doesn't own the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * array data and therefore operations manipulating the ownership (e.g.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * #detachTo()) are forbidden and will assert.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /** Number of elements in the array. */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Resizes the array preserving its contents when possible. If the new size
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * is bigger than the old size, new elements are initialized with null
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * values. If the new size is smaller than the old size, the contents of the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * array above the new size is lost.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aNewSize New number of elements in the array.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @return @c true on success and false if there is not enough
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * memory for resizing.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /// @todo Implement me!
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Reinitializes this instance by preallocating space for the given number
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * of elements. The previous array contents is lost.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aNewSize New number of elements in the array.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @return @c true on success and false if there is not enough
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * memory for resizing.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync m.arr = (T *) nsMemory::Alloc (aNewSize * sizeof (T));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return true;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Returns a pointer to the raw array data. Use this raw pointer with care
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * as no type or bound checking is done for you in this case.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @note This method returns @c NULL when this instance is null.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @see #operator[]
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Const version of #raw().
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync const T *raw() const
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Array access operator that returns an array element by reference. A bit
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * safer than #raw(): asserts and returns an invalid reference if this
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * instance is null or if the index is out of bounds.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @note For weak instances, this call will succeed but the beiavior of
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * changing the contents of an element of the weak array instance is
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * undefined and may lead to a program crash on some platforms.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Const version of #operator[] that returns an array element by value.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync AssertReturn (unconst (this)->accessRaw() != NULL, *((T *) NULL));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Creates a copy of this array and stores it in a method parameter declared
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * using the ComSafeArrayOut macro. When using this call, always wrap the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * parameter name in the ComSafeArrayOutArg macro call like this:
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * safeArray.cloneTo (ComSafeArrayOutArg (aArg));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @note It is assumed that the ownership of the returned copy is
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * transferred to the caller of the method and he is responsible to free the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * array data when it is no more necessary.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aArg Output method parameter to clone to.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync virtual const SafeArray &cloneTo (ComSafeArrayOut (T, aArg)) const
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /// @todo Implement me!
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Transfers the ownership of this array's data to a method parameter
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * declared using the ComSafeArrayOut macro and makes this array a null
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * array. When using this call, always wrap the parameter name in the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * ComSafeArrayOutArg macro call like this:
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * safeArray.detachTo (ComSafeArrayOutArg (aArg));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @note Since the ownership of the array data is transferred to the
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * caller of the method, he is responsible to free the array data when it is
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * no more necessary.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aArg Output method parameter to detach to.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync virtual SafeArray &detachTo (ComSafeArrayOut (T, aArg))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#else /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#endif /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync // public methods for internal purposes only
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /** Internal funciton. Never call it directly. */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync PRUint32 *__asOutParam_Size() { setNull(); return &m.size; }
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /** Internal funciton. Never call it directly. */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync T **__asOutParam_Arr() { Assert (isNull()); return &m.arr; }
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#else /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /** Internal funciton. Never call it directly. */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /** Internal funciton. Never call it directly. */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync SAFEARRAY ** __asOutParam() { setNull(); return &m.arr; }
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#endif /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#else /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /** Requests access to the raw data pointer. */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync HRESULT rc = SafeArrayAccessData (m.arr, (void HUGEP **) &m.raw);
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#endif /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#else /* defined (VBOX_WITH_XPCOM) */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#endif /* defined (VBOX_WITH_XPCOM) */
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync////////////////////////////////////////////////////////////////////////////////
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard. */
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync static I **__asInParam_Arr (I **aArr) { return aArr; }
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync static I **__asInParam_Arr (const I **aArr) { return const_cast <I **> (aArr); }
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync#else /* defined (VBOX_WITH_XPCOM) */
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync#endif /* defined (VBOX_WITH_XPCOM) */
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync////////////////////////////////////////////////////////////////////////////////
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Version of com::SafeArray for arrays of interface pointers.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Except that it manages arrays of interface pointers, the usage of this class
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * is identical to com::SafeArray.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param I Interface class (no asterisk).
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsyncclass SafeIfaceArray : public SafeArray <I *, SafeIfaceArrayTraits <I> >
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync typedef SafeArray <I *, SafeIfaceArrayTraits <I> > Base;
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Creates a null array.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Creates a new array of the given size. All elements of the newly created
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * array initialized with null values.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param aSize Initial number of elements in the array. Must be greater
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @note If this object remains null after construction it means that there
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * was not enough memory for creating an array of the requested size.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * The constructor will also assert in this case.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Weakly attaches this instance to the existing array passed in a method
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * parameter declared using the ComSafeArrayIn macro. When using this call,
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * always wrap the parameter name in the ComSafeArrayOutArg macro call like
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * SafeArray safeArray (ComSafeArrayInArg (aArg));
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Note that this constructor doesn't take the ownership of the array. In
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * particular, it means that operations that operate on the ownership (e.g.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * #detachTo()) are forbidden and will assert.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param aArg Input method parameter to attach to.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync#else /* defined (VBOX_WITH_XPCOM) */
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync ("Expected vartype VT_UNKNOWN, got %d.\n",
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync AssertMsgReturnVoid (InlineIsEqualGUID (_ATL_IIDOF (I), guid),
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync ("Expected IID {%Vuuid}, got {%Vuuid}.\n",
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync#endif /* defined (VBOX_WITH_XPCOM) */
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Creates a deep copy of the given standard C++ container that stores
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * interface pointers as objects of the ComPtr <I> class.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param aCntr Container object to copy.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param C Standard C++ container template class (normally deduced from
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @c aCntr).
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param A Standard C++ allocator class (deduced from @c aCntr).
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param OI Argument to the ComPtr template (deduced from @c aCntr).
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync template <template <typename, typename> class C, class A, class OI>
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync for (typename List::const_iterator it = aCntr.begin();
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Creates a deep copy of the given standard C++ container that stores
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * interface pointers as objects of the ComObjPtr <I> class.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param aCntr Container object to copy.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param C Standard C++ container template class (normally deduced from
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @c aCntr).
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param A Standard C++ allocator class (deduced from @c aCntr).
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param OI Argument to the ComObjPtr template (deduced from @c aCntr).
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync template <template <typename, typename> class C, class A, class OI>
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync SafeIfaceArray (const C <ComObjPtr <OI>, A> & aCntr)
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync for (typename List::const_iterator it = aCntr.begin();
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Reinitializes this instance by preallocating space for the given number
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * of elements. The previous array contents is lost.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param aNewSize New number of elements in the array.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @return @c true on success and false if there is not enough
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * memory for resizing.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync Base::m.arr = (I **) nsMemory::Alloc (aNewSize * sizeof (I *));
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync return true;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync} /* namespace com */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#endif /* ___VBox_com_array_h */