17bbfe820c22c3e599276890d8b7baa48c32abbbvboxsync * MS COM / XPCOM Abstraction Layer - Safe array helper class declaration.
a49dafa13549ac5db76a3c7f5e44ba83485a1971vboxsync * Copyright (C) 2006-2014 Oracle Corporation
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:
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync STDMETHOD(TestArrays)(ComSafeArrayIn(LONG, aIn),
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ComSafeArrayOut(LONG, aOut),
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ComSafeArrayOut(LONG, aRet));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * And the following function bodies:
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync STDMETHODIMP Component::TestArrays(ComSafeArrayIn(LONG, aIn),
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ComSafeArrayOut(LONG, aOut),
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ComSafeArrayOut(LONG, aRet))
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (ComSafeArrayInIsNull(aIn))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return E_INVALIDARG;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (ComSafeArrayOutIsNull(aOut))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return E_POINTER;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (ComSafeArrayOutIsNull(aRet))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return E_POINTER;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync // Use SafeArray to access the input array parameter
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync com::SafeArray<LONG> in(ComSafeArrayInArg(aIn));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync for (size_t i = 0; i < in.size(); ++ i)
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync LogFlow(("*** in[%u]=%d\n", i, in[i]));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync // Use SafeArray to create the return array (the same technique is used
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync // for output array parameters)
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync SafeArray<LONG> ret(in.size() * 2);
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync for (size_t i = 0; i < in.size(); ++ i)
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ret[i] = in[i];
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ret[i + in.size()] = in[i] * 10;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ret.detachTo(ComSafeArrayOutArg(aRet));
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return S_OK;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Such methods can be called from the client code using the following pattern:
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ComPtr<ISomething> component;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync com::SafeArray<LONG> in(3);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync in[0] = -1;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync in[1] = -2;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync in[2] = -3;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync com::SafeArray<LONG> out;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync com::SafeArray<LONG> ret;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync HRESULT rc = component->TestArrays(ComSafeArrayAsInParam(in),
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ComSafeArrayAsOutParam(out),
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ComSafeArrayAsOutParam(ret));
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (SUCCEEDED(rc))
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync for (size_t i = 0; i < ret.size(); ++ i)
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync 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:
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync STDMETHODIMP Component::COMGETTER(Values)(ComSafeArrayOut(int, aValues))
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync // ... assume there is a |std::list<int> mValues| data member
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync com::SafeArray<int> values(mValues);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync 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.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Note that for GUID arrays you should use SafeGUIDArray and
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * SafeConstGUIDArray, customized SafeArray<> specializations.
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync * Also note that in order to pass input BSTR array parameters declared
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * using the ComSafeArrayIn(IN_BSTR, aParam) macro to the SafeArray<>
f72cbd6a549c34992fa79cce84600fe2b92b3299vboxsync * constructor using the ComSafeArrayInArg() macro, you should use IN_BSTR
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * as the SafeArray<> template argument, not just BSTR.
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.
5364452eae1726b30b3af49a60c33b189da75494vboxsync /* Type traits are a C++ 11 feature, so not available everywhere (yet). */
5364452eae1726b30b3af49a60c33b189da75494vboxsync /* Only GCC 4.6 or newer. */
5364452eae1726b30b3af49a60c33b189da75494vboxsync#if (defined(__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__) >= 406) \
af94231fb372dbcb6413fb0e4a6d8a82d0412fb3vboxsync /* Only MSVC++ 16.0 (Visual Studio 2010) or newer. */ \
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
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync * declared using the ComSafeArrayIn macro.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aArray com::SafeArray instance to pass as an input parameter.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync (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
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync * declared using the ComSafeArrayOut macro.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aArray com::SafeArray instance to pass as an output parameter.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync (aArray).__asOutParam_Size(), (aArray).__asOutParam_Arr()
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#else /* !VBOX_WITH_XPCOM */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#define ComSafeArrayAsInParam(aArray) (aArray).__asInParam()
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync#define ComSafeArrayAsOutParam(aArray) (aArray).__asOutParam()
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#endif /* !VBOX_WITH_XPCOM */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync////////////////////////////////////////////////////////////////////////////////
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Provides various helpers for SafeArray.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * @param T Type of array elements.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync /** Initializes memory for aElem. */
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync /** Initializes memory occupied by aElem. */
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync /** Creates a deep copy of aFrom and stores it in aTo. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync 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. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static T *__asInParam_Arr(T *aArr) { return aArr; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static T *__asInParam_Arr(const T *aArr) { return const_cast<T *>(aArr); }
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync // Arbitrary pointers are not supported
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Init(PRUnichar * &aElem) { aElem = NULL; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Copy(const PRUnichar * aFrom, PRUnichar * &aTo)
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync AssertCompile(sizeof(PRUnichar) == sizeof(OLECHAR));
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync aTo = aFrom ? ::SysAllocString((const OLECHAR *)aFrom) : NULL;
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static const PRUnichar **__asInParam_Arr(PRUnichar **aArr)
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static const PRUnichar **__asInParam_Arr(const PRUnichar **aArr) { return aArr; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Init(const PRUnichar * &aElem) { aElem = NULL; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Copy(const PRUnichar * aFrom, const PRUnichar * &aTo)
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync AssertCompile(sizeof(PRUnichar) == sizeof(OLECHAR));
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync aTo = aFrom ? ::SysAllocString((const OLECHAR *)aFrom) : NULL;
66ea7017a123b8b854e76bbfd919a320815058b3vboxsync /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static const PRUnichar **__asInParam_Arr(const PRUnichar **aArr) { return aArr; }
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync /* This specification is also reused for SafeConstGUIDArray, so provide a
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * no-op Init() and Uninit() which are necessary for SafeArray<> but should
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * be never called in context of SafeConstGUIDArray. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Init(const nsID * &aElem) { NOREF(aElem); AssertFailed(); }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Uninit(const nsID * &aElem) { NOREF(aElem); AssertFailed(); }
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync /** Magic to workaround strict rules of par. 4.4.4 of the C++ standard. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static const nsID **__asInParam_Arr(const nsID **aArr) { return aArr; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#else /* !VBOX_WITH_XPCOM */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync////////////////////////////////////////////////////////////////////////////////
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static SAFEARRAY *CreateSafeArray(VARTYPE aVarType, SAFEARRAYBOUND *aBound)
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Provides various helpers for SafeArray.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * @param T Type of array elements.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Specializations of this template must provide the following methods:
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync // Returns the VARTYPE of COM SafeArray elements to be used for T
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync static VARTYPE VarType();
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync // Returns the number of VarType() elements necessary for aSize
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync // elements of T
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static ULONG VarCount(size_t aSize);
f13f1ed69a96abc07232826cd40e8b08ae66afeavboxsync // Returns the number of elements of T that fit into the given number of
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync // VarType() elements (opposite to VarCount(size_t aSize)).
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static size_t Size(ULONG aVarCount);
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync // Creates a deep copy of aFrom and stores it in aTo
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Copy(ULONG aFrom, ULONG &aTo);
f13f1ed69a96abc07232826cd40e8b08ae66afeavboxsync // Arbitrary types are treated as passed by value and each value is
f13f1ed69a96abc07232826cd40e8b08ae66afeavboxsync // represented by a number of VT_Ix type elements where VT_Ix has the
f13f1ed69a96abc07232826cd40e8b08ae66afeavboxsync // biggest possible bitness necessary to represent T w/o a gap. COM enums
f13f1ed69a96abc07232826cd40e8b08ae66afeavboxsync // fall into this category.
8164b4484483bf790b14bd94e37d743f93d9fec4vboxsync * Fallback method in case type traits (VBOX_WITH_TYPE_TRAITS)
8164b4484483bf790b14bd94e37d743f93d9fec4vboxsync * are not available. Always returns unsigned types.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (sizeof(T) % 8 == 0) return (ULONG)((sizeof(T) / 8) * aSize);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (sizeof(T) % 4 == 0) return (ULONG)((sizeof(T) / 4) * aSize);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (sizeof(T) % 2 == 0) return (ULONG)((sizeof(T) / 2) * aSize);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (sizeof(T) % 8 == 0) return (size_t)(aVarCount * 8) / sizeof(T);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (sizeof(T) % 4 == 0) return (size_t)(aVarCount * 4) / sizeof(T);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync if (sizeof(T) % 2 == 0) return (size_t)(aVarCount * 2) / sizeof(T);
f13f1ed69a96abc07232826cd40e8b08ae66afeavboxsync // Arbitrary pointer types are not supported
f13f1ed69a96abc07232826cd40e8b08ae66afeavboxsync/* Although the generic SafeArrayTraits template would work for all integers,
f13f1ed69a96abc07232826cd40e8b08ae66afeavboxsync * we specialize it for some of them in order to use the correct VT_ type */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsyncstruct SafeArrayTraits<LONG> : public SafeArrayTraitsBase
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static ULONG VarCount(size_t aSize) { return (ULONG)aSize; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static size_t Size(ULONG aVarCount) { return (size_t)aVarCount; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Copy(LONG aFrom, LONG &aTo) { aTo = aFrom; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsyncstruct SafeArrayTraits<ULONG> : public SafeArrayTraitsBase
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static ULONG VarCount(size_t aSize) { return (ULONG)aSize; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static size_t Size(ULONG aVarCount) { return (size_t)aVarCount; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Copy(ULONG aFrom, ULONG &aTo) { aTo = aFrom; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsyncstruct SafeArrayTraits<LONG64> : public SafeArrayTraitsBase
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static ULONG VarCount(size_t aSize) { return (ULONG)aSize; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static size_t Size(ULONG aVarCount) { return (size_t)aVarCount; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Copy(LONG64 aFrom, LONG64 &aTo) { aTo = aFrom; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsyncstruct SafeArrayTraits<ULONG64> : public SafeArrayTraitsBase
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static ULONG VarCount(size_t aSize) { return (ULONG)aSize; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static size_t Size(ULONG aVarCount) { return (size_t)aVarCount; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Copy(ULONG64 aFrom, ULONG64 &aTo) { aTo = aFrom; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsyncstruct SafeArrayTraits<BSTR> : public SafeArrayTraitsBase
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static ULONG VarCount(size_t aSize) { return (ULONG)aSize; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static size_t Size(ULONG aVarCount) { return (size_t)aVarCount; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync aTo = aFrom ? ::SysAllocString((const OLECHAR *)aFrom) : NULL;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsyncstruct SafeArrayTraits<GUID> : public SafeArrayTraitsBase
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync /* Use the 64-bit unsigned integer type for GUID */
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync /* GUID is 128 bit, so we need two VT_UI8 */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static size_t Size(ULONG aVarCount) { return (size_t)aVarCount / 2; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static void Copy(GUID aFrom, GUID &aTo) { aTo = aFrom; }
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * Helper for SafeArray::__asOutParam() that automatically updates m.raw after a
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * non-NULL m.arr assignment.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync : arr(aArr), raw(aRaw) { Assert(*aArr == NULL && *aRaw == NULL); }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#endif /* !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
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync * using #operator[] or by accessing 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.
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync * @note The current implementation supports only one-dimensional arrays.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @note This class is not thread-safe.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsynctemplate<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.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * @param aSize Initial number of elements in the array.
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,
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * always wrap the parameter name in the ComSafeArrayInArg macro call like
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * 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.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#else /* !VBOX_WITH_XPCOM */
8164b4484483bf790b14bd94e37d743f93d9fec4vboxsync ("Expected vartype %d or %d, got %d.\n",
8164b4484483bf790b14bd94e37d743f93d9fec4vboxsync# else /* !VBOX_WITH_TYPE_TRAITS */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ("Expected vartype %d, got %d.\n",
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync rc = SafeArrayAccessData(arg, (void HUGEP **)&m.raw);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#endif /* !VBOX_WITH_XPCOM */
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * Creates a deep copy of the given standard C++ container that stores
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * T objects.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param aCntr Container object to copy.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param C Standard C++ container template class (normally deduced from
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @c aCntr).
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync template<template<typename, typename> class C, class A>
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync for (typename C<T, A>::const_iterator it = aCntr.begin();
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * Creates a deep copy of the given standard C++ map that stores T objects
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * as values.
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param aMap Map object to copy.
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param C Standard C++ map template class (normally deduced from
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param L Standard C++ compare class (deduced from @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param A Standard C++ allocator class (deduced from @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param K Map key class (deduced from @c aCntr).
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync template<template<typename, typename, typename, typename>
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync for (typename Map::const_iterator it = aMap.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.
169f826dd7697156030b4a121548552f9b135b98vboxsync * Returns @c true if this instance does not represents a null array.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * Resets this instance to null and, if this instance is not a weak one,
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync * releases any resources occupied 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. */
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * Appends a copy of the given element at the end of the array.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * The array size is increased by one by this method and the additional
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * space is allocated as needed.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * This method is handy in cases where you want to assign a copy of the
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * existing value to the array element, for example:
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * <tt>Bstr string; array.push_back(string);</tt>. If you create a string
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * just to put it in the array, you may find #appendedRaw() more useful.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * @param aElement Element to append.
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * @return @c true on success and @c false if there is not enough
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * memory for resizing.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync return false;
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync return true;
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * Appends an empty element at the end of the array and returns a raw
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * pointer to it suitable for assigning a raw value (w/o constructing a
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * The array size is increased by one by this method and the additional
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * space is allocated as needed.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * Note that in case of raw assignment, value ownership (for types with
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * dynamically allocated data and for interface pointers) is transferred to
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * the safe array object.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * This method is handy for operations like
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * <tt>Bstr("foo").detachTo(array.appendedRaw());</tt>. Don't use it as
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * an l-value (<tt>array.appendedRaw() = SysAllocString(L"tralala");</tt>)
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * since this doesn't check for a NULL condition; use #resize() and
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * #setRawAt() instead. If you need to assign a copy of the existing value
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * instead of transferring the ownership, look at #push_back().
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * @return Raw pointer to the added element or NULL if no memory.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync /* nothing to do here, SafeArrayCreate() has performed element
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * initialization */
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * Resizes the array preserving its contents when possible. If the new size
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * is larger than the old size, new elements are initialized with null
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * values. If the new size is less than the old size, the contents of the
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * array beyond the new size is lost.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aNewSize New number of elements in the array.
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * @return @c true on success and @c false if there is not enough
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * memory for resizing.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync return false;
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync /* initialize the new elements */
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync /* nothing to do here, SafeArrayCreate() has performed element
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * initialization */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync return true;
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * Reinitializes this instance by preallocating space for the given number
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * of elements. The previous array contents is lost.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * @param aNewSize New number of elements in the array.
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * @return @c true on success and @c false if there is not enough
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * memory for resizing.
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 * 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.
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync * @note For weak instances, this call will succeed but the behavior 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 * 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:
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * 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
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * array data when it is no longer needed.
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync * @param aArg Output method parameter to clone to.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync virtual const SafeArray &cloneTo(ComSafeArrayOut(T, aArg)) const
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync /// @todo Implement me!
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Transfers the ownership of this array's data to the specified location
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:
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * safeArray.detachTo(ComSafeArrayOutArg(aArg));
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Detaching the null array is also possible in which case the location will
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * receive NULL.
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
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * no longer needed.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * @param aArg Location to detach to.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync virtual SafeArray &detachTo(ComSafeArrayOut(T, aArg))
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#else /* !VBOX_WITH_XPCOM */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#endif /* !VBOX_WITH_XPCOM */
e081d2eefdae89dce06cd6451f0ce45bf023e6e3vboxsync * Returns a copy of this SafeArray as RTCList<T>.
18dbcbb8555ee72f93ae6e7c08904d066f3d45d4vboxsync inline void initFrom(const com::SafeArray<T> & aRef);
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync // Public methods for internal purposes only.
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync /** Internal function. Never call it directly. */
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync PRUint32 *__asOutParam_Size() { setNull(); return &m.size; }
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync /** Internal function Never call it directly. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync T **__asOutParam_Arr() { Assert(isNull()); return &m.arr; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#else /* !VBOX_WITH_XPCOM */
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync /** Internal function Never call it directly. */
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync /** Internal function Never call it directly. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync { setNull(); return OutSafeArrayDipper(&m.arr, (void **)&m.raw); }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#endif /* !VBOX_WITH_XPCOM */
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * Ensures that the array is big enough to contain aNewSize elements.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * If the new size is greater than the current capacity, a new array is
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * allocated and elements from the old array are copied over. The size of
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * the array doesn't change, only the capacity increases (which is always
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * greater than the size). Note that the additionally allocated elements are
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * left uninitialized by this method.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * If the new size is less than the current size, the existing array is
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * truncated to the specified size and the elements outside the new array
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * boundary are freed.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * If the new size is the same as the current size, nothing happens.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * @param aNewSize New size of the array.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * @return @c true on success and @c false if not enough memory.
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync /* Note: we distinguish between a null array and an empty (zero
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * elements) array. Therefore we never use zero in malloc (even if
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync * aNewSize is zero) to make sure we get a non-null pointer. */
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync return true;
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync /* Allocate in 16-byte pieces. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync size_t newCapacity = RT_MAX((aNewSize + 15) / 16 * 16, 16);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync T *newArr = (T *)nsMemory::Alloc(RT_MAX(newCapacity, 1) * sizeof(T));
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync /* Truncation takes place, uninit exceeding elements and
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * shrink the size. */
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync /* Copy the old contents. */
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync /* Truncation takes place, uninit exceeding elements and
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * shrink the size. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync rc = SafeArrayAccessData(m.arr, (void HUGEP **)&m.raw);
f2a38a61f58a9252205f92a1b17f1e3eba4a91a1vboxsync return true;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#else /* !VBOX_WITH_XPCOM */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#endif /* !VBOX_WITH_XPCOM */
18dbcbb8555ee72f93ae6e7c08904d066f3d45d4vboxsync/* Few fast specializations for primitive array types */
18dbcbb8555ee72f93ae6e7c08904d066f3d45d4vboxsyncinline void com::SafeArray<BYTE>::initFrom(const com::SafeArray<BYTE> & aRef)
6d31d5f5af28ee2dbff98cceb06b5e42d1fa4134vboxsyncinline void com::SafeArray<BYTE>::initFrom(const BYTE* aPtr, size_t aSize)
9171169d99a08b8dba6b409f0fbc598f01b5527fvboxsyncinline void com::SafeArray<SHORT>::initFrom(const com::SafeArray<SHORT> & aRef)
9171169d99a08b8dba6b409f0fbc598f01b5527fvboxsync ::memcpy(raw(), aRef.raw(), sSize * sizeof(SHORT));
9171169d99a08b8dba6b409f0fbc598f01b5527fvboxsyncinline void com::SafeArray<SHORT>::initFrom(const SHORT* aPtr, size_t aSize)
9171169d99a08b8dba6b409f0fbc598f01b5527fvboxsyncinline void com::SafeArray<USHORT>::initFrom(const com::SafeArray<USHORT> & aRef)
9171169d99a08b8dba6b409f0fbc598f01b5527fvboxsync ::memcpy(raw(), aRef.raw(), sSize * sizeof(USHORT));
9171169d99a08b8dba6b409f0fbc598f01b5527fvboxsyncinline void com::SafeArray<USHORT>::initFrom(const USHORT* aPtr, size_t aSize)
1068802cd5ebd6495e27178002fbefa977ca7154vboxsyncinline void com::SafeArray<LONG>::initFrom(const com::SafeArray<LONG> & aRef)
1068802cd5ebd6495e27178002fbefa977ca7154vboxsyncinline void com::SafeArray<LONG>::initFrom(const LONG* aPtr, size_t aSize)
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync////////////////////////////////////////////////////////////////////////////////
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Version of com::SafeArray for arrays of GUID.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * In MS COM, GUID arrays store GUIDs by value and therefore input arrays are
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * represented using |GUID *| and out arrays -- using |GUID **|. In XPCOM,
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * GUID arrays store pointers to nsID so that input arrays are |const nsID **|
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * and out arrays are |nsID ***|. Due to this difference, it is impossible to
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * work with arrays of GUID on both platforms by simply using com::SafeArray
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync * <GUID>. This class is intended to provide some level of cross-platform
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * behavior.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * The basic usage pattern is basically similar to com::SafeArray<> except that
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * you use ComSafeGUIDArrayIn* and ComSafeGUIDArrayOut* macros instead of
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * ComSafeArrayIn* and ComSafeArrayOut*. Another important nuance is that the
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * raw() array type is different (nsID **, or GUID ** on XPCOM and GUID * on MS
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * COM) so it is recommended to use operator[] instead which always returns a
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * GUID by value.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Note that due to const modifiers, you cannot use SafeGUIDArray for input GUID
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * arrays. Please use SafeConstGUIDArray for this instead.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Other than mentioned above, the functionality of this class is equivalent to
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * com::SafeArray<>. See the description of that template and its methods for
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * more information.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Output GUID arrays are handled by a separate class, SafeGUIDArrayOut, since
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * this class cannot handle them because of const modifiers.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync operator const nsID &() const { return mVal ? *mVal : *Empty; }
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync operator nsID() const { return mVal ? *mVal : *Empty; }
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync const nsID *operator&() const { return mVal ? mVal : Empty; }
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync /** See SafeArray<>::SafeArray(). */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync /** See SafeArray<>::SafeArray(size_t). */
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Array access operator that returns an array element by reference. As a
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * special case, the return value of this operator on XPCOM is an nsID (GUID)
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * reference, instead of an nsID pointer (the actual SafeArray template
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * argument), for compatibility with the MS COM version.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * The rest is equivalent to SafeArray<>::operator[].
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Const version of #operator[] that returns an array element by value.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync return m.arr[aIdx] ? *m.arr[aIdx] : *nsIDRef::Empty;
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Version of com::SafeArray for const arrays of GUID.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * This class is used to work with input GUID array parameters in method
dbea238999d6a4b34b9d1bdd1292e29717dd14bevboxsync * implementations. See SafeGUIDArray for more details.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsyncclass SafeConstGUIDArray : public SafeArray<const nsID *,
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync typedef SafeArray<const nsID *, SafeArrayTraits<nsID *> > Base;
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync /** See SafeArray<>::SafeArray(). */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync /* See SafeArray<>::SafeArray(ComSafeArrayIn(T, aArg)). */
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * Array access operator that returns an array element by reference. As a
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * special case, the return value of this operator on XPCOM is nsID (GUID)
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * instead of nsID *, for compatibility with the MS COM version.
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync * The rest is equivalent to SafeArray<>::operator[].
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync AssertReturn(m.arr != NULL, **((const nsID * *)NULL));
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync AssertReturn(aIdx < size(), **((const nsID * *)NULL));
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync /* These are disabled because of const. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync bool reset(size_t aNewSize) { NOREF(aNewSize); return false; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#else /* !VBOX_WITH_XPCOM */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsynctypedef SafeArray<const GUID, SafeArrayTraits<GUID> > SafeConstGUIDArray;
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#endif /* !VBOX_WITH_XPCOM */
dcea3eadf1ecc8f4ac868185a05a63be42a199e4vboxsync////////////////////////////////////////////////////////////////////////////////
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync /* Magic to workaround strict rules of par. 4.4.4 of the C++ standard. */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static I **__asInParam_Arr(I **aArr) { return aArr; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static I **__asInParam_Arr(const I **aArr) { return const_cast<I **>(aArr); }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#else /* !VBOX_WITH_XPCOM */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static ULONG VarCount(size_t aSize) { return (ULONG)aSize; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static size_t Size(ULONG aVarCount) { return (size_t)aVarCount; }
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync static SAFEARRAY *CreateSafeArray(VARTYPE aVarType, SAFEARRAYBOUND *aBound)
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync return SafeArrayCreateEx(VT_DISPATCH, 1, aBound, (PVOID)&_ATL_IIDOF(I));
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#endif /* !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).
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsyncclass SafeIfaceArray : public SafeArray<I *, SafeIfaceArrayTraits<I> >
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync 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.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync SafeIfaceArray(size_t aSize) { Base::resize(aSize); }
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
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * SafeArray safeArray(ComSafeArrayInArg(aArg));
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Note that this constructor doesn't take the ownership of the array. In
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * particular, this means that operations that operate on the ownership
869259a9bb3c1b0f5f98519ca67e0b948bbd52a4vboxsync * (e.g. #detachTo()) are forbidden and will assert.
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * @param aArg Input method parameter to attach to.
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#else /* !VBOX_WITH_XPCOM */
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync AssertMsgReturnVoid(vt == VT_UNKNOWN || vt == VT_DISPATCH,
8164b4484483bf790b14bd94e37d743f93d9fec4vboxsync ("Expected vartype VT_UNKNOWN or VT_DISPATCH, got %d.\n",
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync AssertMsgReturnVoid(InlineIsEqualGUID(_ATL_IIDOF(I), guid),
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync ("Expected IID {%RTuuid}, got {%RTuuid}.\n",
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync rc = SafeArrayAccessData(arg, (void HUGEP **)&m.raw);
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync#endif /* !VBOX_WITH_XPCOM */
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync * Creates a deep copy of the given standard C++ container that stores
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * 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).
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync 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
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * 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).
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync template<template<typename, typename> class C, class A, class OI>
7a18d4bae4d9ff1216be13970ae7815604b3365bvboxsync for (typename List::const_iterator it = aCntr.begin();
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * Creates a deep copy of the given standard C++ map whose values are
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * interface pointers stored as objects of the ComPtr<I> class.
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param aMap Map object to copy.
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param C Standard C++ map template class (normally deduced from
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param L Standard C++ compare class (deduced from @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param A Standard C++ allocator class (deduced from @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param K Map key class (deduced from @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param OI Argument to the ComPtr template (deduced from @c aCntr).
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync template<template<typename, typename, typename, typename>
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync SafeIfaceArray(const C<K, ComPtr<OI>, L, A> & aMap)
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync for (typename Map::const_iterator it = aMap.begin();
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * Creates a deep copy of the given standard C++ map whose values are
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync * interface pointers stored as objects of the ComObjPtr<I> class.
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param aMap Map object to copy.
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param C Standard C++ map template class (normally deduced from
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param L Standard C++ compare class (deduced from @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param A Standard C++ allocator class (deduced from @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param K Map key class (deduced from @c aCntr).
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync * @param OI Argument to the ComObjPtr template (deduced from @c aCntr).
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync template<template<typename, typename, typename, typename>
9fe7370f586fb762a5387f0efa192b1fd9d20af2vboxsync SafeIfaceArray(const C<K, ComObjPtr<OI>, L, A> & aMap)
6009ff7dbed47f682276143b4483fa417e7211f1vboxsync for (typename Map::const_iterator it = aMap.begin();
f9108665f82b59c99ac444815d75af51a14e46c7vboxsync} /* namespace com */
17bbfe820c22c3e599276890d8b7baa48c32abbbvboxsync#endif /* !___VBox_com_array_h */