xref: /aoo41x/main/cppu/inc/com/sun/star/uno/Any.h (revision 24f6443d)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 #ifndef _COM_SUN_STAR_UNO_ANY_H_
24 #define _COM_SUN_STAR_UNO_ANY_H_
25 
26 #include <uno/any2.h>
27 #include <typelib/typedescription.h>
28 #include <com/sun/star/uno/Type.h>
29 #include "cppu/unotype.hxx"
30 #include <rtl/alloc.h>
31 
32 
33 namespace com
34 {
35 namespace sun
36 {
37 namespace star
38 {
39 namespace uno
40 {
41 
42 /** C++ class representing an IDL any.
43 	This class is used to transport any type defined in IDL. The class inherits from the
44     binary C representation of uno_Any.
45 	You can insert a value by either using the <<= operators or the template function makeAny().
46     No any can hold an any. You can extract values from an any by using the >>= operators which
47     return true if the any contains an assignable value (no data loss), e.g. the any contains a
48     short and you >>= it into a long variable.
49 */
50 class Any : public uno_Any
51 {
52 public:
53 	// these are here to force memory de/allocation to sal lib.
54     /** @internal */
operator new(size_t nSize)55 	inline static void * SAL_CALL operator new ( size_t nSize ) SAL_THROW( () )
56 		{ return ::rtl_allocateMemory( nSize ); }
57     /** @internal */
operator delete(void * pMem)58 	inline static void SAL_CALL operator delete ( void * pMem ) SAL_THROW( () )
59 		{ ::rtl_freeMemory( pMem ); }
60     /** @internal */
operator new(size_t,void * pMem)61 	inline static void * SAL_CALL operator new ( size_t, void * pMem ) SAL_THROW( () )
62 		{ return pMem; }
63     /** @internal */
operator delete(void *,void *)64 	inline static void SAL_CALL operator delete ( void *, void * ) SAL_THROW( () )
65 		{}
66 
67 	/** Default constructor: Any holds no value; its type is void.
68 	*/
69 	inline Any() SAL_THROW( () );
70 
71     /** Templated ctor.  Sets a copy of the given value.
72 
73         @param value value of the Any
74     */
75     template <typename T>
76     explicit inline Any( T const & value );
77     /// Ctor support for C++ bool.
78     explicit inline Any( bool value );
79 
80 	/** Copy constructor: Sets value of the given any.
81 
82 		@param rAny another any
83 	*/
84 	inline Any( const Any & rAny ) SAL_THROW( () );
85 
86 	/** Constructor: Sets a copy of the given data.
87 
88 		@param pData_ value
89 		@param rType type of value
90 	*/
91 	inline Any( const void * pData_, const Type & rType ) SAL_THROW( () );
92 
93 	/** Constructor: Sets a copy of the given data.
94 
95 		@param pData_ value
96 		@param pTypeDescr type of value
97 	*/
98 	inline Any( const void * pData_, typelib_TypeDescription * pTypeDescr ) SAL_THROW( () );
99 
100 	/** Constructor: Sets a copy of the given data.
101 
102 		@param pData_ value
103 		@param pType type of value
104 	*/
105 	inline Any( const void * pData_, typelib_TypeDescriptionReference * pType ) SAL_THROW( () );
106 
107 	/** Destructor: Destructs any content and frees memory.
108 	*/
109 	inline ~Any() SAL_THROW( () );
110 
111 	/** Assignment operator: Sets the value of the given any.
112 
113 		@param rAny another any (right side)
114 		@return this any
115 	*/
116 	inline Any & SAL_CALL operator = ( const Any & rAny ) SAL_THROW( () );
117 
118 	/** Gets the type of the set value.
119 
120 		@return a Type object of the set value
121 	 */
getValueType() const122 	inline const Type & SAL_CALL getValueType() const SAL_THROW( () )
123 		{ return * reinterpret_cast< const Type * >( &pType ); }
124 	/** Gets the type of the set value.
125 
126 		@return the UNacquired type description reference of the set value
127 	 */
getValueTypeRef() const128 	inline typelib_TypeDescriptionReference * SAL_CALL getValueTypeRef() const SAL_THROW( () )
129 		{ return pType; }
130 
131 	/** Gets the type description of the set value. Provides ownership of the type description!
132 		Call an explicit typelib_typedescription_release() to release afterwards.
133 
134 		@param a pointer to type description pointer
135 	*/
getValueTypeDescription(typelib_TypeDescription ** ppTypeDescr) const136 	inline void SAL_CALL getValueTypeDescription( typelib_TypeDescription ** ppTypeDescr ) const SAL_THROW( () )
137 		{ ::typelib_typedescriptionreference_getDescription( ppTypeDescr, pType ); }
138 
139 	/** Gets the type class of the set value.
140 
141 		@return the type class of the set value
142 	 */
getValueTypeClass() const143 	inline TypeClass SAL_CALL getValueTypeClass() const SAL_THROW( () )
144 		{ return (TypeClass)pType->eTypeClass; }
145 
146 	/** Gets the type name of the set value.
147 
148 		@return the type name of the set value
149 	*/
150 	inline ::rtl::OUString SAL_CALL getValueTypeName() const SAL_THROW( () );
151 
152 	/** Tests if any contains a value.
153 
154 		@return true if any has a value, false otherwise
155 	*/
hasValue() const156 	inline sal_Bool SAL_CALL hasValue() const SAL_THROW( () )
157 		{ return (typelib_TypeClass_VOID != pType->eTypeClass); }
158 
159 	/** Gets a pointer to the set value.
160 
161 		@return a pointer to the set value
162 	*/
getValue() const163 	inline const void * SAL_CALL getValue() const SAL_THROW( () )
164 		{ return pData; }
165 
166 #if ! defined(EXCEPTIONS_OFF)
167     /** Provides a value of specified type, so you can easily write e.g.
168         <pre>
169         sal_Int32 myVal = myAny.get<sal_Int32>();
170         </pre>
171         Widening conversion without data loss is taken into account.
172         Throws a
173         <type scope="com::sun::star::uno">RuntimeException</type>
174         if the specified type cannot be provided.
175 
176         @return value of specified type
177         @exception <type scope="com::sun::star::uno">RuntimeException</type>
178                    in case the specified type cannot be provided
179     */
180     template <typename T>
181     inline T get() const;
182 #endif // ! defined(EXCEPTIONS_OFF)
183 
184 	/** Sets a value. If the any already contains a value, that value will be destructed
185         and its memory freed.
186 
187 		@param pData_ pointer to value
188 		@param rType type of value
189 	*/
190 	inline void SAL_CALL setValue( const void * pData_, const Type & rType ) SAL_THROW( () );
191 	/** Sets a value. If the any already contains a value, that value will be destructed
192 		and its memory freed.
193 
194 		@param pData_ pointer to value
195 		@param pType type of value
196 	*/
197 	inline void SAL_CALL setValue( const void * pData_, typelib_TypeDescriptionReference * pType ) SAL_THROW( () );
198 	/** Sets a value. If the any already contains a value, that value will be destructed
199 		and its memory freed.
200 
201 		@param pData_ pointer to value
202 		@param pTypeDescr type description of value
203 	*/
204 	inline void SAL_CALL setValue( const void * pData_, typelib_TypeDescription * pTypeDescr ) SAL_THROW( () );
205 
206 	/** Clears this any. If the any already contains a value, that value will be destructed
207 		and its memory freed. After this has been called, the any does not contain a value.
208 	*/
209 	inline void SAL_CALL clear() SAL_THROW( () );
210 
211 	/** Tests whether this any is extractable to a value of given type.
212         Widening conversion without data loss is taken into account.
213 
214 		@param rType destination type
215 		@return true if this any is extractable to value of given type (e.g. using >>= operator)
216 	*/
217 	inline sal_Bool SAL_CALL isExtractableTo( const Type & rType ) const SAL_THROW( () );
218 
219 	/** Tests whether this any can provide a value of specified type.
220         Widening conversion without data loss is taken into account.
221 
222 		@return true if this any can provide a value of specified type
223 		(e.g. using >>= operator)
224 	*/
225     template <typename T>
226 	inline bool has() const;
227 
228 	/** Equality operator: compares two anys.
229 		The values need not be of equal type, e.g. a short integer is compared to a long integer.
230 
231 		@param rAny another any (right side)
232 		@return true if both any contains equal values
233 	*/
234 	inline sal_Bool SAL_CALL operator == ( const Any & rAny ) const SAL_THROW( () );
235 	/** Unequality operator: compares two anys.
236 		The values need not be of equal type, e.g. a short integer is compared to a long integer.
237 
238 		@param rAny another any (right side)
239 		@return true if both any contains unequal values
240 	*/
241 	inline sal_Bool SAL_CALL operator != ( const Any & rAny ) const SAL_THROW( () );
242 
243 private:
244     // not impl: forbid use with ambiguous type (sal_Unicode, sal_uInt16)
245     explicit Any( sal_uInt16 );
246 #if defined(_MSC_VER)
247     // Omitting the following private declarations leads to an internal compiler
248     // error on MSVC (version 1310).
249     // not impl: forbid use with ambiguous type (sal_Unicode, sal_uInt16)
250 #if ! defined(EXCEPTIONS_OFF)
251     template <>
252     sal_uInt16 get<sal_uInt16>() const;
253 #endif // ! defined(EXCEPTIONS_OFF)
254     template <>
255 	bool has<sal_uInt16>() const;
256 #endif // defined(_MSC_VER)
257 };
258 
259 /** Template function to generically construct an any from a C++ value.
260 
261     @tplparam C value type
262 	@param value a value
263 	@return an any
264 */
265 template< class C >
266 inline Any SAL_CALL makeAny( const C & value ) SAL_THROW( () );
267 
268 // additionally specialized for C++ bool
269 template<>
270 inline Any SAL_CALL makeAny( bool const & value ) SAL_THROW( () );
271 
272 class BaseReference;
273 class Type;
274 
275 /** Template binary <<= operator to set the value of an any.
276 
277     @tplparam C value type
278 	@param rAny destination any (left side)
279 	@param value source value (right side)
280 */
281 template< class C >
282 inline void SAL_CALL operator <<= ( Any & rAny, const C & value ) SAL_THROW( () );
283 
284 // additionally for C++ bool:
285 inline void SAL_CALL operator <<= ( Any & rAny, bool const & value )
286     SAL_THROW( () );
287 
288 /** Template binary >>= operator to assign a value from an any.
289 	If the any does not contain a value that can be assigned without data loss, then this
290     operation will fail returning false.
291 
292     @tplparam C value type
293 	@param rAny source any (left side)
294 	@param value destination value (right side)
295 	@return true if assignment was possible without data loss
296 */
297 template< class C >
298 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, C & value ) SAL_THROW( () );
299 
300 /** Template equality operator: compares set value of left side any to right side value.
301 	The values need not be of equal type, e.g. a short integer is compared to a long integer.
302 	This operator can be implemented as template member function, if all supported compilers
303     can cope with template member functions.
304 
305     @tplparam C value type
306 	@param rAny another any (left side)
307 	@param value a value (right side)
308 	@return true if values are equal, false otherwise
309 */
310 template< class C >
311 inline sal_Bool SAL_CALL operator == ( const Any & rAny, const C & value ) SAL_THROW( () );
312 /** Template unequality operator: compares set value of left side any to right side value.
313 	The values need not be of equal type, e.g. a short integer is compared to a long integer.
314 	This operator can be implemented as template member function, if all supported compilers
315     can cope with template member functions.
316 
317     @tplparam C value type
318 	@param rAny another any (left side)
319 	@param value a value (right side)
320 	@return true if values are unequal, false otherwise
321 */
322 template< class C >
323 inline sal_Bool SAL_CALL operator != ( const Any & rAny, const C & value ) SAL_THROW( () );
324 
325 // additional specialized >>= and == operators
326 // bool
327 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, sal_Bool & value ) SAL_THROW( () );
328 inline sal_Bool SAL_CALL operator == ( const Any & rAny, const sal_Bool & value ) SAL_THROW( () );
329 template<>
330 inline sal_Bool SAL_CALL operator >>= ( Any const & rAny, bool & value )
331     SAL_THROW( () );
332 template<>
333 inline sal_Bool SAL_CALL operator == ( Any const & rAny, bool const & value )
334     SAL_THROW( () );
335 // byte
336 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, sal_Int8 & value ) SAL_THROW( () );
337 // short
338 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, sal_Int16 & value ) SAL_THROW( () );
339 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, sal_uInt16 & value ) SAL_THROW( () );
340 // long
341 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, sal_Int32 & value ) SAL_THROW( () );
342 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, sal_uInt32 & value ) SAL_THROW( () );
343 // hyper
344 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, sal_Int64 & value ) SAL_THROW( () );
345 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, sal_uInt64 & value ) SAL_THROW( () );
346 // float
347 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, float & value ) SAL_THROW( () );
348 // double
349 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, double & value ) SAL_THROW( () );
350 // string
351 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, ::rtl::OUString & value ) SAL_THROW( () );
352 inline sal_Bool SAL_CALL operator == ( const Any & rAny, const ::rtl::OUString & value ) SAL_THROW( () );
353 // type
354 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, Type & value ) SAL_THROW( () );
355 inline sal_Bool SAL_CALL operator == ( const Any & rAny, const Type & value ) SAL_THROW( () );
356 // any
357 inline sal_Bool SAL_CALL operator >>= ( const Any & rAny, Any & value ) SAL_THROW( () );
358 // interface
359 inline sal_Bool SAL_CALL operator == ( const Any & rAny, const BaseReference & value ) SAL_THROW( () );
360 
361 }
362 }
363 }
364 }
365 
366 /** Gets the meta type of IDL type any.
367 
368     There are cases (involving templates) where uses of getCppuType are known to
369     not compile.  Use cppu::UnoType or cppu::getTypeFavourUnsigned instead.
370 
371 	@param dummy typed pointer for function signature
372 	@return type of IDL type any
373 */
getCppuType(const::com::sun::star::uno::Any *)374 inline const ::com::sun::star::uno::Type & SAL_CALL getCppuType( const ::com::sun::star::uno::Any * ) SAL_THROW( () )
375 {
376     return ::cppu::UnoType< ::com::sun::star::uno::Any >::get();
377 }
378 
379 #endif
380