include/com/sun/star/uno/Any.h

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