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