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