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