xref: /aoo41x/main/cppu/inc/com/sun/star/uno/Reference.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_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 	*/
get() const90     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 	*/
is() const97 	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     */
castFromXInterface(XInterface * p)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     */
castToXInterface(interface_type * p)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 */
operator new(size_t nSize)238 	inline static void * SAL_CALL operator new ( size_t nSize ) SAL_THROW( () )
239 		{ return ::rtl_allocateMemory( nSize ); }
240     /** @internal */
operator delete(void * pMem)241 	inline static void SAL_CALL operator delete ( void * pMem ) SAL_THROW( () )
242 		{ ::rtl_freeMemory( pMem ); }
243     /** @internal */
operator new(size_t,void * pMem)244 	inline static void * SAL_CALL operator new ( size_t, void * pMem ) SAL_THROW( () )
245 		{ return pMem; }
246     /** @internal */
operator delete(void *,void *)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 	*/
operator ->() const358 	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 	*/
get() const365 	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>
get_pointer(Reference<T> const & r)519 inline T * get_pointer( Reference<T> const& r )
520 {
521     return r.get();
522 }
523 
524 }
525 }
526 }
527 }
528 
529 #endif
530