1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 #ifndef _COM_SUN_STAR_UNO_REFERENCE_H_ 28 #define _COM_SUN_STAR_UNO_REFERENCE_H_ 29 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 class RuntimeException; 43 class XInterface; 44 class Type; 45 class Any; 46 47 /** Enum defining UNO_REF_NO_ACQUIRE for setting reference without acquiring a given interface. 48 Deprecated, please use SAL_NO_ACQUIRE. 49 @deprecated 50 */ 51 enum UnoReference_NoAcquire 52 { 53 /** This enum value can be used for creating a reference granting a given interface, 54 i.e. transferring ownership to it. 55 */ 56 UNO_REF_NO_ACQUIRE 57 }; 58 59 /** This base class serves as a base class for all template reference classes and 60 has been introduced due to compiler problems with templated operators ==, =!. 61 */ 62 class BaseReference 63 { 64 protected: 65 /** the interface pointer 66 */ 67 XInterface * _pInterface; 68 69 /** Queries given interface for type rType. 70 71 @param pInterface interface pointer 72 @param rType interface type 73 @return interface of demanded type (may be null) 74 */ 75 inline static XInterface * SAL_CALL iquery( XInterface * pInterface, const Type & rType ) 76 SAL_THROW( (RuntimeException) ); 77 #ifndef EXCEPTIONS_OFF 78 /** Queries given interface for type rType. 79 Throws a RuntimeException if the demanded interface cannot be queried. 80 81 @param pInterface interface pointer 82 @param rType interface type 83 @return interface of demanded type 84 */ 85 inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface, const Type & rType ) 86 SAL_THROW( (RuntimeException) ); 87 #endif 88 89 public: 90 /** Gets interface pointer. This call does not acquire the interface. 91 92 @return UNacquired interface pointer 93 */ 94 inline XInterface * SAL_CALL get() const SAL_THROW( () ) 95 { return _pInterface; } 96 97 /** Checks if reference is null. 98 99 @return true if reference acquires an interface, i.e. true if it is not null 100 */ 101 inline sal_Bool SAL_CALL is() const SAL_THROW( () ) 102 { return (0 != _pInterface); } 103 104 /** Equality operator: compares two interfaces 105 Checks if both references are null or refer to the same object. 106 107 @param rRef another interface 108 @return true if both references are null or refer to the same object, false otherwise 109 */ 110 inline sal_Bool SAL_CALL operator == ( XInterface * pInterface ) const SAL_THROW( () ); 111 /** Unequality operator: compares two interfaces 112 Checks if both references are null or refer to the same object. 113 114 @param rRef another interface 115 @return false if both references are null or refer to the same object, true otherwise 116 */ 117 inline sal_Bool SAL_CALL operator != ( XInterface * pInterface ) const SAL_THROW( () ); 118 119 /** Equality operator: compares two interfaces 120 Checks if both references are null or refer to the same object. 121 122 @param rRef another reference 123 @return true if both references are null or refer to the same object, false otherwise 124 */ 125 inline sal_Bool SAL_CALL operator == ( const BaseReference & rRef ) const SAL_THROW( () ); 126 /** Unequality operator: compares two interfaces 127 Checks if both references are null or refer to the same object. 128 129 @param rRef another reference 130 @return false if both references are null or refer to the same object, true otherwise 131 */ 132 inline sal_Bool SAL_CALL operator != ( const BaseReference & rRef ) const SAL_THROW( () ); 133 134 /** Needed by some STL containers. 135 136 @param rRef another reference 137 @return true, if this reference is less than rRef 138 */ 139 inline sal_Bool SAL_CALL operator < ( const BaseReference & rRef ) const SAL_THROW( () ); 140 }; 141 142 /** Enum defining UNO_QUERY and UNO_REF_QUERY for implicit interface query. 143 */ 144 enum UnoReference_Query 145 { 146 /** This enum value can be used for implicit interface query. 147 */ 148 UNO_QUERY, 149 /** This enum value can be used for implicit interface query. 150 */ 151 UNO_REF_QUERY 152 }; 153 #ifndef EXCEPTIONS_OFF 154 /** Enum defining UNO_QUERY_THROW and UNO_REF_QUERY_THROW for implicit interface query. 155 If the demanded interface is unavailable, then a RuntimeException is thrown. 156 */ 157 enum UnoReference_QueryThrow 158 { 159 /** This enum value can be used for implicit interface query. 160 */ 161 UNO_QUERY_THROW, 162 /** This enum value can be used for implicit interface query. 163 */ 164 UNO_REF_QUERY_THROW 165 }; 166 /** Enum defining UNO_SET_THROW for throwing if attempts are made to assign a <NULL/> 167 interface 168 169 @since UDK 3.2.8 170 */ 171 enum UnoReference_SetThrow 172 { 173 UNO_SET_THROW 174 }; 175 #endif 176 177 /** Template reference class for interface type derived from BaseReference. 178 A special constructor given the UNO_QUERY or UNO_REF_QUERY identifier queries interfaces 179 for reference type. 180 */ 181 template< class interface_type > 182 class Reference : public BaseReference 183 { 184 /** Queries given interface for type interface_type. 185 186 @param pInterface interface pointer 187 @return interface of demanded type (may be null) 188 */ 189 inline static XInterface * SAL_CALL iquery( XInterface * pInterface ) 190 SAL_THROW( (RuntimeException) ); 191 #ifndef EXCEPTIONS_OFF 192 /** Queries given interface for type interface_type. 193 Throws a RuntimeException if the demanded interface cannot be queried. 194 195 @param pInterface interface pointer 196 @return interface of demanded type 197 */ 198 inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface ) 199 SAL_THROW( (RuntimeException) ); 200 /** Returns the given interface if it is not <NULL/>, throws a RuntimeException otherwise. 201 202 @param pInterface interface pointer 203 @return pInterface 204 */ 205 inline static interface_type * SAL_CALL iset_throw( interface_type * pInterface ) 206 SAL_THROW( (RuntimeException) ); 207 #endif 208 209 /** Cast from an "interface pointer" (e.g., BaseReference::_pInterface) to a 210 pointer to this interface_type. 211 212 To work around ambiguities in the case of multiple-inheritance interface 213 types (which inherit XInterface more than once), use reinterpret_cast 214 (resp. a sequence of two static_casts, to avoid warnings about 215 reinterpret_cast used between related classes) to switch from a pointer 216 to XInterface to a pointer to this derived interface_type. In 217 principle, this is not guaranteed to work. In practice, it seems to 218 work on all supported platforms. 219 */ 220 static inline interface_type * castFromXInterface(XInterface * p) { 221 return static_cast< interface_type * >(static_cast< void * >(p)); 222 } 223 224 /** Cast from a pointer to this interface_type to an "interface pointer" 225 (e.g., BaseReference::_pInterface). 226 227 To work around ambiguities in the case of multiple-inheritance interface 228 types (which inherit XInterface more than once), use reinterpret_cast 229 (resp. a sequence of two static_casts, to avoid warnings about 230 reinterpret_cast used between related classes) to switch from a pointer 231 to this derived interface_type to a pointer to XInterface. In 232 principle, this is not guaranteed to work. In practice, it seems to 233 work on all supported platforms. 234 */ 235 static inline XInterface * castToXInterface(interface_type * p) { 236 return static_cast< XInterface * >(static_cast< void * >(p)); 237 } 238 239 public: 240 // these are here to force memory de/allocation to sal lib. 241 /** @internal */ 242 inline static void * SAL_CALL operator new ( size_t nSize ) SAL_THROW( () ) 243 { return ::rtl_allocateMemory( nSize ); } 244 /** @internal */ 245 inline static void SAL_CALL operator delete ( void * pMem ) SAL_THROW( () ) 246 { ::rtl_freeMemory( pMem ); } 247 /** @internal */ 248 inline static void * SAL_CALL operator new ( size_t, void * pMem ) SAL_THROW( () ) 249 { return pMem; } 250 /** @internal */ 251 inline static void SAL_CALL operator delete ( void *, void * ) SAL_THROW( () ) 252 {} 253 254 /** Destructor: Releases interface if set. 255 */ 256 inline ~Reference() SAL_THROW( () ); 257 258 /** Default Constructor: Sets null reference. 259 */ 260 inline Reference() SAL_THROW( () ); 261 262 /** Copy constructor: Copies interface reference. 263 264 @param rRef another reference 265 */ 266 inline Reference( const Reference< interface_type > & rRef ) SAL_THROW( () ); 267 /** Constructor: Sets given interface pointer. 268 269 @param pInterface an interface pointer 270 */ 271 inline Reference( interface_type * pInterface ) SAL_THROW( () ); 272 273 /** Constructor: Sets given interface pointer without acquiring it. 274 275 @param pInterface another reference 276 @param dummy SAL_NO_ACQUIRE to force obvious distinction to other constructors 277 */ 278 inline Reference( interface_type * pInterface, __sal_NoAcquire ) SAL_THROW( () ); 279 /** Constructor: Sets given interface pointer without acquiring it. 280 Deprecated, please use SAL_NO_ACQUIRE version. 281 282 @deprecated 283 @param pInterface another reference 284 @param dummy UNO_REF_NO_ACQUIRE to force obvious distinction to other constructors 285 */ 286 inline Reference( interface_type * pInterface, UnoReference_NoAcquire ) SAL_THROW( () ); 287 288 /** Constructor: Queries given interface for reference interface type (interface_type). 289 290 @param rRef another reference 291 @param dummy UNO_QUERY or UNO_REF_QUERY to force obvious distinction to other constructors 292 */ 293 inline Reference( const BaseReference & rRef, UnoReference_Query ) SAL_THROW( (RuntimeException) ); 294 /** Constructor: Queries given interface for reference interface type (interface_type). 295 296 @param pInterface an interface pointer 297 @param dummy UNO_QUERY to force obvious distinction to other constructors 298 */ 299 inline Reference( XInterface * pInterface, UnoReference_Query ) SAL_THROW( (RuntimeException) ); 300 /** Constructor: Queries given any for reference interface type (interface_type). 301 302 @param rAny an any 303 @param dummy UNO_QUERY to force obvious distinction to other constructors 304 */ 305 inline Reference( const Any & rAny, UnoReference_Query ) SAL_THROW( (RuntimeException) ); 306 #ifndef EXCEPTIONS_OFF 307 /** Constructor: Queries given interface for reference interface type (interface_type). 308 Throws a RuntimeException if the demanded interface cannot be queried. 309 310 @param rRef another reference 311 @param dummy UNO_QUERY_THROW or UNO_REF_QUERY_THROW to force obvious distinction 312 to other constructors 313 */ 314 inline Reference( const BaseReference & rRef, UnoReference_QueryThrow ) SAL_THROW( (RuntimeException) ); 315 /** Constructor: Queries given interface for reference interface type (interface_type). 316 Throws a RuntimeException if the demanded interface cannot be queried. 317 318 @param pInterface an interface pointer 319 @param dummy UNO_QUERY_THROW or UNO_REF_QUERY_THROW to force obvious distinction 320 to other constructors 321 */ 322 inline Reference( XInterface * pInterface, UnoReference_QueryThrow ) SAL_THROW( (RuntimeException) ); 323 /** Constructor: Queries given any for reference interface type (interface_type). 324 Throws a RuntimeException if the demanded interface cannot be queried. 325 326 @param rAny an any 327 @param dummy UNO_QUERY_THROW or UNO_REF_QUERY_THROW to force obvious distinction 328 to other constructors 329 */ 330 inline Reference( const Any & rAny, UnoReference_QueryThrow ) SAL_THROW( (RuntimeException) ); 331 /** Constructor: assigns from the given interface of the same type. Throws a RuntimeException 332 if the source interface is <NULL/>. 333 334 @param rRef another interface reference of the same type 335 @param dummy UNO_SET_THROW to distinguish from default copy constructor 336 337 @since UDK 3.2.8 338 */ 339 inline Reference( const Reference< interface_type > & rRef, UnoReference_SetThrow ) SAL_THROW( (RuntimeException) ); 340 /** Constructor: assigns from the given interface of the same type. Throws a RuntimeException 341 if the source interface is <NULL/>. 342 343 @param pInterface an interface pointer 344 @param dummy UNO_SET_THROW to distinguish from default assignment constructor 345 346 @since UDK 3.2.8 347 */ 348 inline Reference( interface_type * pInterface, UnoReference_SetThrow ) SAL_THROW( (RuntimeException) ); 349 #endif 350 351 /** Cast operator to Reference< XInterface >: Reference objects are binary compatible and 352 any interface must be derived from com.sun.star.uno.XInterface. 353 This a useful direct cast possibility. 354 */ 355 inline SAL_CALL operator const Reference< XInterface > & () const SAL_THROW( () ) 356 { return * reinterpret_cast< const Reference< XInterface > * >( this ); } 357 358 /** Dereference operator: Used to call interface methods. 359 360 @return UNacquired interface pointer 361 */ 362 inline interface_type * SAL_CALL operator -> () const SAL_THROW( () ) 363 { return castFromXInterface(_pInterface); } 364 365 /** Gets interface pointer. This call does not acquire the interface. 366 367 @return UNacquired interface pointer 368 */ 369 inline interface_type * SAL_CALL get() const SAL_THROW( () ) 370 { return castFromXInterface(_pInterface); } 371 372 /** Clears reference, i.e. releases interface. Reference is null after clear() call. 373 */ 374 inline void SAL_CALL clear() SAL_THROW( () ); 375 376 /** Sets the given interface. An interface already set will be released. 377 378 @param rRef another reference 379 @return true, if non-null interface was set 380 */ 381 inline sal_Bool SAL_CALL set( const Reference< interface_type > & rRef ) SAL_THROW( () ); 382 /** Sets the given interface. An interface already set will be released. 383 384 @param pInterface another interface 385 @return true, if non-null interface was set 386 */ 387 inline sal_Bool SAL_CALL set( interface_type * pInterface ) SAL_THROW( () ); 388 389 /** Sets interface pointer without acquiring it. An interface already set will be released. 390 391 @param pInterface an interface pointer 392 @param dummy SAL_NO_ACQUIRE to force obvious distinction to set methods 393 @return true, if non-null interface was set 394 */ 395 inline sal_Bool SAL_CALL set( interface_type * pInterface, __sal_NoAcquire ) SAL_THROW( () ); 396 /** Sets interface pointer without acquiring it. An interface already set will be released. 397 Deprecated, please use SAL_NO_ACQUIRE version. 398 399 @deprecated 400 @param pInterface an interface pointer 401 @param dummy UNO_REF_NO_ACQUIRE to force obvious distinction to set methods 402 @return true, if non-null interface was set 403 */ 404 inline sal_Bool SAL_CALL set( interface_type * pInterface, UnoReference_NoAcquire ) SAL_THROW( () ); 405 406 /** Queries given interface for reference interface type (interface_type) and sets it. 407 An interface already set will be released. 408 409 @param pInterface an interface pointer 410 @param dummy UNO_QUERY or UNO_REF_QUERY to force obvious distinction to set methods 411 @return true, if non-null interface was set 412 */ 413 inline sal_Bool SAL_CALL set( XInterface * pInterface, UnoReference_Query ) SAL_THROW( (RuntimeException) ); 414 /** Queries given interface for reference interface type (interface_type) and sets it. 415 An interface already set will be released. 416 417 @param rRef another reference 418 @param dummy UNO_QUERY or UNO_REF_QUERY to force obvious distinction to set methods 419 @return true, if non-null interface was set 420 */ 421 inline sal_Bool SAL_CALL set( const BaseReference & rRef, UnoReference_Query ) SAL_THROW( (RuntimeException) ); 422 423 /** Queries given any for reference interface type (interface_type) 424 and sets it. An interface already set will be released. 425 426 @param rAny 427 an Any containing an interface 428 @param dummy 429 UNO_QUERY or UNO_REF_QUERY to force obvious distinction 430 to set methods 431 @return 432 true, if non-null interface was set 433 */ 434 inline bool set( Any const & rAny, UnoReference_Query ); 435 436 #ifndef EXCEPTIONS_OFF 437 /** Queries given interface for reference interface type (interface_type) and sets it. 438 An interface already set will be released. 439 Throws a RuntimeException if the demanded interface cannot be set. 440 441 @param pInterface an interface pointer 442 @param dummy UNO_QUERY_THROW or UNO_REF_QUERY_THROW to force obvious distinction 443 to set methods 444 */ 445 inline void SAL_CALL set( XInterface * pInterface, UnoReference_QueryThrow ) SAL_THROW( (RuntimeException) ); 446 /** Queries given interface for reference interface type (interface_type) and sets it. 447 An interface already set will be released. 448 Throws a RuntimeException if the demanded interface cannot be set. 449 450 @param rRef another reference 451 @param dummy UNO_QUERY_THROW or UNO_REF_QUERY_THROW to force obvious distinction 452 to set methods 453 */ 454 inline void SAL_CALL set( const BaseReference & rRef, UnoReference_QueryThrow ) SAL_THROW( (RuntimeException) ); 455 456 /** Queries given any for reference interface type (interface_type) and 457 sets it. An interface already set will be released. 458 Throws a RuntimeException if the demanded interface cannot be set. 459 460 @param rAny 461 an Any containing an interface 462 @param dummy 463 UNO_QUERY_THROW or UNO_REF_QUERY_THROW to force obvious 464 distinction to set methods 465 */ 466 inline void set( Any const & rAny, UnoReference_QueryThrow ); 467 /** sets the given interface 468 An interface already set will be released. 469 Throws a RuntimeException if the source interface is <NULL/>. 470 471 @param pInterface an interface pointer 472 @param dummy UNO_SET_THROW to force obvious distinction to other set methods 473 474 @since UDK 3.2.8 475 */ 476 inline void SAL_CALL set( interface_type * pInterface, UnoReference_SetThrow ) SAL_THROW( (RuntimeException) ); 477 /** sets the given interface 478 An interface already set will be released. 479 Throws a RuntimeException if the source interface is <NULL/>. 480 481 @param rRef an interface reference 482 @param dummy UNO_SET_THROW to force obvious distinction to other set methods 483 484 @since UDK 3.2.8 485 */ 486 inline void SAL_CALL set( const Reference< interface_type > & rRef, UnoReference_SetThrow ) SAL_THROW( (RuntimeException) ); 487 488 #endif 489 490 /** Assignment operator: Acquires given interface pointer and sets reference. 491 An interface already set will be released. 492 493 @param pInterface an interface pointer 494 @return this reference 495 */ 496 inline Reference< interface_type > & SAL_CALL operator = ( interface_type * pInterface ) SAL_THROW( () ); 497 /** Assignment operator: Acquires given interface reference and sets reference. 498 An interface already set will be released. 499 500 @param rRef an interface reference 501 @return this reference 502 */ 503 inline Reference< interface_type > & SAL_CALL operator = ( const Reference< interface_type > & rRef ) SAL_THROW( () ); 504 505 /** Queries given interface reference for type interface_type. 506 507 @param rRef interface reference 508 @return interface reference of demanded type (may be null) 509 */ 510 inline static Reference< interface_type > SAL_CALL query( const BaseReference & rRef ) SAL_THROW( (RuntimeException) ); 511 /** Queries given interface for type interface_type. 512 513 @param pInterface interface pointer 514 @return interface reference of demanded type (may be null) 515 */ 516 inline static Reference< interface_type > SAL_CALL query( XInterface * pInterface ) SAL_THROW( (RuntimeException) ); 517 }; 518 519 /** @internal 520 Enables boost::mem_fn and boost::bind to recognize Reference. 521 */ 522 template <typename T> 523 inline T * get_pointer( Reference<T> const& r ) 524 { 525 return r.get(); 526 } 527 528 } 529 } 530 } 531 } 532 533 #endif 534