Line data Source code
1 : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 : /*
3 : * This file is part of the LibreOffice project.
4 : *
5 : * This Source Code Form is subject to the terms of the Mozilla Public
6 : * License, v. 2.0. If a copy of the MPL was not distributed with this
7 : * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 : *
9 : * This file incorporates work covered by the following license notice:
10 : *
11 : * Licensed to the Apache Software Foundation (ASF) under one or more
12 : * contributor license agreements. See the NOTICE file distributed
13 : * with this work for additional information regarding copyright
14 : * ownership. The ASF licenses this file to you under the Apache
15 : * License, Version 2.0 (the "License"); you may not use this file
16 : * except in compliance with the License. You may obtain a copy of
17 : * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18 : */
19 : #ifndef _COM_SUN_STAR_UNO_REFERENCE_H_
20 : #define _COM_SUN_STAR_UNO_REFERENCE_H_
21 :
22 : #include <rtl/alloc.h>
23 :
24 :
25 : namespace com
26 : {
27 : namespace sun
28 : {
29 : namespace star
30 : {
31 : namespace uno
32 : {
33 :
34 : class RuntimeException;
35 : class XInterface;
36 : class Type;
37 : class Any;
38 :
39 : /** Enum defining UNO_REF_NO_ACQUIRE for setting reference without acquiring a given interface.
40 : Deprecated, please use SAL_NO_ACQUIRE.
41 : @deprecated
42 : */
43 : enum UnoReference_NoAcquire
44 : {
45 : /** This enum value can be used for creating a reference granting a given interface,
46 : i.e. transferring ownership to it.
47 : */
48 : UNO_REF_NO_ACQUIRE
49 : };
50 :
51 : /** This base class serves as a base class for all template reference classes and
52 : has been introduced due to compiler problems with templated operators ==, =!.
53 : */
54 94509123 : class BaseReference
55 : {
56 : protected:
57 : /** the interface pointer
58 : */
59 : XInterface * _pInterface;
60 :
61 : /** Queries given interface for type rType.
62 :
63 : @param pInterface interface pointer
64 : @param rType interface type
65 : @return interface of demanded type (may be null)
66 : */
67 : inline static XInterface * SAL_CALL iquery( XInterface * pInterface, const Type & rType )
68 : SAL_THROW( (RuntimeException) );
69 : #ifndef EXCEPTIONS_OFF
70 : /** Queries given interface for type rType.
71 : Throws a RuntimeException if the demanded interface cannot be queried.
72 :
73 : @param pInterface interface pointer
74 : @param rType interface type
75 : @return interface of demanded type
76 : */
77 : inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface, const Type & rType )
78 : SAL_THROW( (RuntimeException) );
79 : #endif
80 :
81 : public:
82 : /** Gets interface pointer. This call does not acquire the interface.
83 :
84 : @return UNacquired interface pointer
85 : */
86 11152541 : inline XInterface * SAL_CALL get() const SAL_THROW(())
87 11152541 : { return _pInterface; }
88 :
89 : /** Checks if reference is null.
90 :
91 : @return true if reference acquires an interface, i.e. true if it is not null
92 : */
93 74605959 : inline sal_Bool SAL_CALL is() const SAL_THROW(())
94 74605959 : { return (0 != _pInterface); }
95 :
96 : /** Equality operator: compares two interfaces
97 : Checks if both references are null or refer to the same object.
98 :
99 : @param pInterface another interface
100 : @return true if both references are null or refer to the same object, false otherwise
101 : */
102 : inline sal_Bool SAL_CALL operator == ( XInterface * pInterface ) const SAL_THROW(());
103 : /** Unequality operator: compares two interfaces
104 : Checks if both references are null or refer to the same object.
105 :
106 : @param pInterface another interface
107 : @return false if both references are null or refer to the same object, true otherwise
108 : */
109 : inline sal_Bool SAL_CALL operator != ( XInterface * pInterface ) const SAL_THROW(());
110 :
111 : /** Equality operator: compares two interfaces
112 : Checks if both references are null or refer to the same object.
113 :
114 : @param rRef another reference
115 : @return true if both references are null or refer to the same object, false otherwise
116 : */
117 : inline sal_Bool SAL_CALL operator == ( const BaseReference & rRef ) const SAL_THROW(());
118 : /** Unequality operator: compares two interfaces
119 : Checks if both references are null or refer to the same object.
120 :
121 : @param rRef another reference
122 : @return false if both references are null or refer to the same object, true otherwise
123 : */
124 : inline sal_Bool SAL_CALL operator != ( const BaseReference & rRef ) const SAL_THROW(());
125 :
126 : /** Needed by some STL containers.
127 :
128 : @param rRef another reference
129 : @return true, if this reference is less than rRef
130 : */
131 : inline sal_Bool SAL_CALL operator < ( const BaseReference & rRef ) const SAL_THROW(());
132 : };
133 :
134 : /** Enum defining UNO_QUERY for implicit interface query.
135 : */
136 : enum UnoReference_Query
137 : {
138 : /** This enum value can be used for implicit interface query.
139 : */
140 : UNO_QUERY,
141 : };
142 : #ifndef EXCEPTIONS_OFF
143 : /** Enum defining UNO_QUERY_THROW for implicit interface query.
144 : If the demanded interface is unavailable, then a RuntimeException is thrown.
145 : */
146 : enum UnoReference_QueryThrow
147 : {
148 : /** This enum value can be used for implicit interface query.
149 : */
150 : UNO_QUERY_THROW,
151 : };
152 : /** Enum defining UNO_SET_THROW for throwing if attempts are made to assign a null
153 : interface
154 :
155 : @since UDK 3.2.8
156 : */
157 : enum UnoReference_SetThrow
158 : {
159 : UNO_SET_THROW
160 : };
161 : #endif
162 :
163 : /// @cond INTERNAL
164 : namespace detail {
165 :
166 : // A mechanism to enable up-casts, used by the Reference conversion constructor,
167 : // but at the same time disable up-casts to XInterface, so that the conversion
168 : // operator for that special case is used in an expression like
169 : // Reference< XInterface >(x); heavily borrowed from boost::is_base_and_derived
170 : // (which manages to avoid compilation problems with ambiguous bases and cites
171 : // comp.lang.c++.moderated mail <http://groups.google.com/groups?
172 : // selm=df893da6.0301280859.522081f7%40posting.google.com> "SuperSubclass
173 : // (is_base_and_derived) complete implementation!" by Rani Sharoni and cites
174 : // Aleksey Gurtovoy for the workaround for MSVC), to avoid including Boost
175 : // headers in URE headers (could ultimately be based on C++11 std::is_base_of):
176 :
177 : template< typename T1, typename T2 > struct UpCast {
178 : private:
179 : template< bool, typename U1, typename > struct C
180 : { typedef U1 t; };
181 :
182 : template< typename U1, typename U2 > struct C< false, U1, U2 >
183 : { typedef U2 t; };
184 :
185 : struct S { char c[2]; };
186 :
187 : #if defined _MSC_VER
188 : static char f(T2 *, long);
189 : static S f(T1 * const &, int);
190 : #else
191 : template< typename U > static char f(T2 *, U);
192 : static S f(T1 *, int);
193 : #endif
194 :
195 : struct H {
196 : H(); // avoid C2514 "class has no constructors" from MSVC 2008
197 : #if defined _MSC_VER
198 : operator T1 * const & () const;
199 : #else
200 : operator T1 * () const;
201 : #endif
202 : operator T2 * ();
203 : };
204 :
205 : public:
206 : typedef typename C< sizeof (f(H(), 0)) == 1, void *, void >::t t;
207 : };
208 :
209 : template< typename T2 > struct UpCast< XInterface, T2 > {};
210 :
211 : }
212 : /// @endcond
213 :
214 : /** Template reference class for interface type derived from BaseReference.
215 : A special constructor given the UNO_QUERY identifier queries interfaces
216 : for reference type.
217 : */
218 : template< class interface_type >
219 : class Reference : public BaseReference
220 : {
221 : /** Queries given interface for type interface_type.
222 :
223 : @param pInterface interface pointer
224 : @return interface of demanded type (may be null)
225 : */
226 : inline static XInterface * SAL_CALL iquery( XInterface * pInterface )
227 : SAL_THROW( (RuntimeException) );
228 : #ifndef EXCEPTIONS_OFF
229 : /** Queries given interface for type interface_type.
230 : Throws a RuntimeException if the demanded interface cannot be queried.
231 :
232 : @param pInterface interface pointer
233 : @return interface of demanded type
234 : */
235 : inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface )
236 : SAL_THROW( (RuntimeException) );
237 : /** Returns the given interface if it is not <NULL/>, throws a RuntimeException otherwise.
238 :
239 : @param pInterface interface pointer
240 : @return pInterface
241 : */
242 : inline static interface_type * SAL_CALL iset_throw( interface_type * pInterface )
243 : SAL_THROW( (RuntimeException) );
244 : #endif
245 :
246 : /** Cast from an "interface pointer" (e.g., BaseReference::_pInterface) to a
247 : pointer to this interface_type.
248 :
249 : To work around ambiguities in the case of multiple-inheritance interface
250 : types (which inherit XInterface more than once), use reinterpret_cast
251 : (resp. a sequence of two static_casts, to avoid warnings about
252 : reinterpret_cast used between related classes) to switch from a pointer
253 : to XInterface to a pointer to this derived interface_type. In
254 : principle, this is not guaranteed to work. In practice, it seems to
255 : work on all supported platforms.
256 : */
257 69255278 : static inline interface_type * castFromXInterface(XInterface * p) {
258 69255278 : return static_cast< interface_type * >(static_cast< void * >(p));
259 : }
260 :
261 : /** Cast from a pointer to this interface_type to an "interface pointer"
262 : (e.g., BaseReference::_pInterface).
263 :
264 : To work around ambiguities in the case of multiple-inheritance interface
265 : types (which inherit XInterface more than once), use reinterpret_cast
266 : (resp. a sequence of two static_casts, to avoid warnings about
267 : reinterpret_cast used between related classes) to switch from a pointer
268 : to this derived interface_type to a pointer to XInterface. In
269 : principle, this is not guaranteed to work. In practice, it seems to
270 : work on all supported platforms.
271 : */
272 51730359 : static inline XInterface * castToXInterface(interface_type * p) {
273 51730359 : return static_cast< XInterface * >(static_cast< void * >(p));
274 : }
275 :
276 : public:
277 : /// @cond INTERNAL
278 : // these are here to force memory de/allocation to sal lib.
279 8544 : inline static void * SAL_CALL operator new ( ::size_t nSize ) SAL_THROW(())
280 8544 : { return ::rtl_allocateMemory( nSize ); }
281 8523 : inline static void SAL_CALL operator delete ( void * pMem ) SAL_THROW(())
282 8523 : { ::rtl_freeMemory( pMem ); }
283 0 : inline static void * SAL_CALL operator new ( ::size_t, void * pMem ) SAL_THROW(())
284 0 : { return pMem; }
285 0 : inline static void SAL_CALL operator delete ( void *, void * ) SAL_THROW(())
286 0 : {}
287 : /// @endcond
288 :
289 : /** Destructor: Releases interface if set.
290 : */
291 : inline ~Reference() SAL_THROW(());
292 :
293 : /** Default Constructor: Sets null reference.
294 : */
295 : inline Reference() SAL_THROW(());
296 :
297 : /** Copy constructor: Copies interface reference.
298 :
299 : @param rRef another reference
300 : */
301 : inline Reference( const Reference< interface_type > & rRef ) SAL_THROW(());
302 :
303 : /** Up-casting conversion constructor: Copies interface reference.
304 :
305 : Does not work for up-casts to ambiguous bases. For the special case of
306 : up-casting to Reference< XInterface >, see the corresponding conversion
307 : operator.
308 :
309 : @param rRef another reference
310 : */
311 : template< class derived_type >
312 : inline Reference(
313 : const Reference< derived_type > & rRef,
314 : typename detail::UpCast< interface_type, derived_type >::t = 0 )
315 : SAL_THROW(());
316 :
317 : /** Constructor: Sets given interface pointer.
318 :
319 : @param pInterface an interface pointer
320 : */
321 : inline Reference( interface_type * pInterface ) SAL_THROW(());
322 :
323 : /** Constructor: Sets given interface pointer without acquiring it.
324 :
325 : @param pInterface another reference
326 : @param dummy SAL_NO_ACQUIRE to force obvious distinction to other constructors
327 : */
328 : inline Reference( interface_type * pInterface, __sal_NoAcquire dummy) SAL_THROW(());
329 : /** Constructor: Sets given interface pointer without acquiring it.
330 : Deprecated, please use SAL_NO_ACQUIRE version.
331 :
332 : @deprecated
333 : @param pInterface another reference
334 : @param dummy UNO_REF_NO_ACQUIRE to force obvious distinction to other constructors
335 : */
336 : inline Reference( interface_type * pInterface, UnoReference_NoAcquire dummy ) SAL_THROW(());
337 :
338 : /** Constructor: Queries given interface for reference interface type (interface_type).
339 :
340 : @param rRef another reference
341 : @param dummy UNO_QUERY to force obvious distinction to other constructors
342 : */
343 : inline Reference( const BaseReference & rRef, UnoReference_Query dummy ) SAL_THROW( (RuntimeException) );
344 : /** Constructor: Queries given interface for reference interface type (interface_type).
345 :
346 : @param pInterface an interface pointer
347 : @param dummy UNO_QUERY to force obvious distinction to other constructors
348 : */
349 : inline Reference( XInterface * pInterface, UnoReference_Query dummy) SAL_THROW( (RuntimeException) );
350 : /** Constructor: Queries given any for reference interface type (interface_type).
351 :
352 : @param rAny an any
353 : @param dummy UNO_QUERY to force obvious distinction to other constructors
354 : */
355 : inline Reference( const Any & rAny, UnoReference_Query dummy) SAL_THROW( (RuntimeException) );
356 : #ifndef EXCEPTIONS_OFF
357 : /** Constructor: Queries given interface for reference interface type (interface_type).
358 : Throws a RuntimeException if the demanded interface cannot be queried.
359 :
360 : @param rRef another reference
361 : @param dummy UNO_QUERY_THROW to force obvious distinction
362 : to other constructors
363 : */
364 : inline Reference( const BaseReference & rRef, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
365 : /** Constructor: Queries given interface for reference interface type (interface_type).
366 : Throws a RuntimeException if the demanded interface cannot be queried.
367 :
368 : @param pInterface an interface pointer
369 : @param dummy UNO_QUERY_THROW to force obvious distinction
370 : to other constructors
371 : */
372 : inline Reference( XInterface * pInterface, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
373 : /** Constructor: Queries given any for reference interface type (interface_type).
374 : Throws a RuntimeException if the demanded interface cannot be queried.
375 :
376 : @param rAny an any
377 : @param dummy UNO_QUERY_THROW to force obvious distinction
378 : to other constructors
379 : */
380 : inline Reference( const Any & rAny, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
381 : /** Constructor: assigns from the given interface of the same type. Throws a RuntimeException
382 : if the source interface is NULL.
383 :
384 : @param rRef another interface reference of the same type
385 : @param dummy UNO_SET_THROW to distinguish from default copy constructor
386 :
387 : @since UDK 3.2.8
388 : */
389 : inline Reference( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy ) SAL_THROW( (RuntimeException) );
390 : /** Constructor: assigns from the given interface of the same type. Throws a RuntimeException
391 : if the source interface is NULL.
392 :
393 : @param pInterface an interface pointer
394 : @param dummy UNO_SET_THROW to distinguish from default assignment constructor
395 :
396 : @since UDK 3.2.8
397 : */
398 : inline Reference( interface_type * pInterface, UnoReference_SetThrow dummy ) SAL_THROW( (RuntimeException) );
399 : #endif
400 :
401 : /** Cast operator to Reference< XInterface >: Reference objects are binary compatible and
402 : any interface must be derived from com.sun.star.uno.XInterface.
403 : This a useful direct cast possibility.
404 : */
405 2821411 : inline SAL_CALL operator const Reference< XInterface > & () const SAL_THROW(())
406 2821411 : { return * reinterpret_cast< const Reference< XInterface > * >( this ); }
407 :
408 : /** Dereference operator: Used to call interface methods.
409 :
410 : @return UNacquired interface pointer
411 : */
412 42155696 : inline interface_type * SAL_CALL operator -> () const SAL_THROW(())
413 42155696 : { return castFromXInterface(_pInterface); }
414 :
415 : /** Gets interface pointer. This call does not acquire the interface.
416 :
417 : @return UNacquired interface pointer
418 : */
419 7105816 : inline interface_type * SAL_CALL get() const SAL_THROW(())
420 7105816 : { return castFromXInterface(_pInterface); }
421 :
422 : /** Clears reference, i.e. releases interface. Reference is null after clear() call.
423 : */
424 : inline void SAL_CALL clear() SAL_THROW(());
425 :
426 : /** Sets the given interface. An interface already set will be released.
427 :
428 : @param rRef another reference
429 : @return true, if non-null interface was set
430 : */
431 : inline sal_Bool SAL_CALL set( const Reference< interface_type > & rRef ) SAL_THROW(());
432 : /** Sets the given interface. An interface already set will be released.
433 :
434 : @param pInterface another interface
435 : @return true, if non-null interface was set
436 : */
437 : inline sal_Bool SAL_CALL set( interface_type * pInterface ) SAL_THROW(());
438 :
439 : /** Sets interface pointer without acquiring it. An interface already set will be released.
440 :
441 : @param pInterface an interface pointer
442 : @param dummy SAL_NO_ACQUIRE to force obvious distinction to set methods
443 : @return true, if non-null interface was set
444 : */
445 : inline sal_Bool SAL_CALL set( interface_type * pInterface, __sal_NoAcquire dummy) SAL_THROW(());
446 : /** Sets interface pointer without acquiring it. An interface already set will be released.
447 : Deprecated, please use SAL_NO_ACQUIRE version.
448 :
449 : @deprecated
450 : @param pInterface an interface pointer
451 : @param dummy UNO_REF_NO_ACQUIRE to force obvious distinction to set methods
452 : @return true, if non-null interface was set
453 : */
454 : inline sal_Bool SAL_CALL set( interface_type * pInterface, UnoReference_NoAcquire dummy) SAL_THROW(());
455 :
456 : /** Queries given interface for reference interface type (interface_type) and sets it.
457 : An interface already set will be released.
458 :
459 : @param pInterface an interface pointer
460 : @param dummy UNO_QUERY to force obvious distinction to set methods
461 : @return true, if non-null interface was set
462 : */
463 : inline sal_Bool SAL_CALL set( XInterface * pInterface, UnoReference_Query dummy ) SAL_THROW( (RuntimeException) );
464 : /** Queries given interface for reference interface type (interface_type) and sets it.
465 : An interface already set will be released.
466 :
467 : @param rRef another reference
468 : @param dummy UNO_QUERY to force obvious distinction to set methods
469 : @return true, if non-null interface was set
470 : */
471 : inline sal_Bool SAL_CALL set( const BaseReference & rRef, UnoReference_Query dummy) SAL_THROW( (RuntimeException) );
472 :
473 : /** Queries given any for reference interface type (interface_type)
474 : and sets it. An interface already set will be released.
475 :
476 : @param rAny
477 : an Any containing an interface
478 : @param dummy
479 : UNO_QUERY to force obvious distinction
480 : to set methods
481 : @return
482 : true, if non-null interface was set
483 : */
484 : inline bool set( Any const & rAny, UnoReference_Query dummy );
485 :
486 : #ifndef EXCEPTIONS_OFF
487 : /** Queries given interface for reference interface type (interface_type) and sets it.
488 : An interface already set will be released.
489 : Throws a RuntimeException if the demanded interface cannot be set.
490 :
491 : @param pInterface an interface pointer
492 : @param dummy UNO_QUERY_THROW to force obvious distinction
493 : to set methods
494 : */
495 : inline void SAL_CALL set( XInterface * pInterface, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
496 : /** Queries given interface for reference interface type (interface_type) and sets it.
497 : An interface already set will be released.
498 : Throws a RuntimeException if the demanded interface cannot be set.
499 :
500 : @param rRef another reference
501 : @param dummy UNO_QUERY_THROW to force obvious distinction
502 : to set methods
503 : */
504 : inline void SAL_CALL set( const BaseReference & rRef, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
505 :
506 : /** Queries given any for reference interface type (interface_type) and
507 : sets it. An interface already set will be released.
508 : Throws a RuntimeException if the demanded interface cannot be set.
509 :
510 : @param rAny
511 : an Any containing an interface
512 : @param dummy
513 : UNO_QUERY_THROW to force obvious distinction to set methods
514 : */
515 : inline void set( Any const & rAny, UnoReference_QueryThrow dummy);
516 : /** sets the given interface
517 : An interface already set will be released.
518 : Throws a RuntimeException if the source interface is @b NULL.
519 :
520 : @param pInterface an interface pointer
521 : @param dummy UNO_SET_THROW to force obvious distinction to other set methods
522 :
523 : @since UDK 3.2.8
524 : */
525 : inline void SAL_CALL set( interface_type * pInterface, UnoReference_SetThrow dummy) SAL_THROW( (RuntimeException) );
526 : /** sets the given interface
527 : An interface already set will be released.
528 : Throws a RuntimeException if the source interface is @b NULL.
529 :
530 : @param rRef an interface reference
531 : @param dummy UNO_SET_THROW to force obvious distinction to other set methods
532 :
533 : @since UDK 3.2.8
534 : */
535 : inline void SAL_CALL set( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy) SAL_THROW( (RuntimeException) );
536 :
537 : #endif
538 :
539 : /** Assignment operator: Acquires given interface pointer and sets reference.
540 : An interface already set will be released.
541 :
542 : @param pInterface an interface pointer
543 : @return this reference
544 : */
545 : inline Reference< interface_type > & SAL_CALL operator = ( interface_type * pInterface ) SAL_THROW(());
546 : /** Assignment operator: Acquires given interface reference and sets reference.
547 : An interface already set will be released.
548 :
549 : @param rRef an interface reference
550 : @return this reference
551 : */
552 : inline Reference< interface_type > & SAL_CALL operator = ( const Reference< interface_type > & rRef ) SAL_THROW(());
553 :
554 : /** Queries given interface reference for type interface_type.
555 :
556 : @param rRef interface reference
557 : @return interface reference of demanded type (may be null)
558 : */
559 : inline static Reference< interface_type > SAL_CALL query( const BaseReference & rRef ) SAL_THROW( (RuntimeException) );
560 : /** Queries given interface for type interface_type.
561 :
562 : @param pInterface interface pointer
563 : @return interface reference of demanded type (may be null)
564 : */
565 : inline static Reference< interface_type > SAL_CALL query( XInterface * pInterface ) SAL_THROW( (RuntimeException) );
566 : };
567 :
568 : /// @cond INTERNAL
569 : /** Enables boost::mem_fn and boost::bind to recognize Reference.
570 : */
571 : template <typename T>
572 4279 : inline T * get_pointer( Reference<T> const& r )
573 : {
574 4279 : return r.get();
575 : }
576 : /// @endcond
577 :
578 : }
579 : }
580 : }
581 : }
582 :
583 : #endif
584 :
585 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
