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 11887287 : 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 1682855 : inline XInterface * SAL_CALL get() const SAL_THROW(())
87 1682855 : { 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 8729725 : inline sal_Bool SAL_CALL is() const SAL_THROW(())
94 8729725 : { 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 : /** Template reference class for interface type derived from BaseReference.
164 : A special constructor given the UNO_QUERY identifier queries interfaces
165 : for reference type.
166 : */
167 : template< class interface_type >
168 : class Reference : public BaseReference
169 : {
170 : /** Queries given interface for type interface_type.
171 :
172 : @param pInterface interface pointer
173 : @return interface of demanded type (may be null)
174 : */
175 : inline static XInterface * SAL_CALL iquery( XInterface * pInterface )
176 : SAL_THROW( (RuntimeException) );
177 : #ifndef EXCEPTIONS_OFF
178 : /** Queries given interface for type interface_type.
179 : Throws a RuntimeException if the demanded interface cannot be queried.
180 :
181 : @param pInterface interface pointer
182 : @return interface of demanded type
183 : */
184 : inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface )
185 : SAL_THROW( (RuntimeException) );
186 : /** Returns the given interface if it is not <NULL/>, throws a RuntimeException otherwise.
187 :
188 : @param pInterface interface pointer
189 : @return pInterface
190 : */
191 : inline static interface_type * SAL_CALL iset_throw( interface_type * pInterface )
192 : SAL_THROW( (RuntimeException) );
193 : #endif
194 :
195 : /** Cast from an "interface pointer" (e.g., BaseReference::_pInterface) to a
196 : pointer to this interface_type.
197 :
198 : To work around ambiguities in the case of multiple-inheritance interface
199 : types (which inherit XInterface more than once), use reinterpret_cast
200 : (resp. a sequence of two static_casts, to avoid warnings about
201 : reinterpret_cast used between related classes) to switch from a pointer
202 : to XInterface to a pointer to this derived interface_type. In
203 : principle, this is not guaranteed to work. In practice, it seems to
204 : work on all supported platforms.
205 : */
206 10477977 : static inline interface_type * castFromXInterface(XInterface * p) {
207 10477977 : return static_cast< interface_type * >(static_cast< void * >(p));
208 : }
209 :
210 : /** Cast from a pointer to this interface_type to an "interface pointer"
211 : (e.g., BaseReference::_pInterface).
212 :
213 : To work around ambiguities in the case of multiple-inheritance interface
214 : types (which inherit XInterface more than once), use reinterpret_cast
215 : (resp. a sequence of two static_casts, to avoid warnings about
216 : reinterpret_cast used between related classes) to switch from a pointer
217 : to this derived interface_type to a pointer to XInterface. In
218 : principle, this is not guaranteed to work. In practice, it seems to
219 : work on all supported platforms.
220 : */
221 7241903 : static inline XInterface * castToXInterface(interface_type * p) {
222 7241903 : return static_cast< XInterface * >(static_cast< void * >(p));
223 : }
224 :
225 : public:
226 : /// @cond INTERNAL
227 : // these are here to force memory de/allocation to sal lib.
228 2144 : inline static void * SAL_CALL operator new ( ::size_t nSize ) SAL_THROW(())
229 2144 : { return ::rtl_allocateMemory( nSize ); }
230 709 : inline static void SAL_CALL operator delete ( void * pMem ) SAL_THROW(())
231 709 : { ::rtl_freeMemory( pMem ); }
232 10953 : inline static void * SAL_CALL operator new ( ::size_t, void * pMem ) SAL_THROW(())
233 10953 : { return pMem; }
234 0 : inline static void SAL_CALL operator delete ( void *, void * ) SAL_THROW(())
235 0 : {}
236 : /// @endcond
237 :
238 : /** Destructor: Releases interface if set.
239 : */
240 : inline ~Reference() SAL_THROW(());
241 :
242 : /** Default Constructor: Sets null reference.
243 : */
244 : inline Reference() SAL_THROW(());
245 :
246 : /** Copy constructor: Copies interface reference.
247 :
248 : @param rRef another reference
249 : */
250 : inline Reference( const Reference< interface_type > & rRef ) SAL_THROW(());
251 : /** Constructor: Sets given interface pointer.
252 :
253 : @param pInterface an interface pointer
254 : */
255 : inline Reference( interface_type * pInterface ) SAL_THROW(());
256 :
257 : /** Constructor: Sets given interface pointer without acquiring it.
258 :
259 : @param pInterface another reference
260 : @param dummy SAL_NO_ACQUIRE to force obvious distinction to other constructors
261 : */
262 : inline Reference( interface_type * pInterface, __sal_NoAcquire dummy) SAL_THROW(());
263 : /** Constructor: Sets given interface pointer without acquiring it.
264 : Deprecated, please use SAL_NO_ACQUIRE version.
265 :
266 : @deprecated
267 : @param pInterface another reference
268 : @param dummy UNO_REF_NO_ACQUIRE to force obvious distinction to other constructors
269 : */
270 : inline Reference( interface_type * pInterface, UnoReference_NoAcquire dummy ) SAL_THROW(());
271 :
272 : /** Constructor: Queries given interface for reference interface type (interface_type).
273 :
274 : @param rRef another reference
275 : @param dummy UNO_QUERY to force obvious distinction to other constructors
276 : */
277 : inline Reference( const BaseReference & rRef, UnoReference_Query dummy ) SAL_THROW( (RuntimeException) );
278 : /** Constructor: Queries given interface for reference interface type (interface_type).
279 :
280 : @param pInterface an interface pointer
281 : @param dummy UNO_QUERY to force obvious distinction to other constructors
282 : */
283 : inline Reference( XInterface * pInterface, UnoReference_Query dummy) SAL_THROW( (RuntimeException) );
284 : /** Constructor: Queries given any for reference interface type (interface_type).
285 :
286 : @param rAny an any
287 : @param dummy UNO_QUERY to force obvious distinction to other constructors
288 : */
289 : inline Reference( const Any & rAny, UnoReference_Query dummy) SAL_THROW( (RuntimeException) );
290 : #ifndef EXCEPTIONS_OFF
291 : /** Constructor: Queries given interface for reference interface type (interface_type).
292 : Throws a RuntimeException if the demanded interface cannot be queried.
293 :
294 : @param rRef another reference
295 : @param dummy UNO_QUERY_THROW to force obvious distinction
296 : to other constructors
297 : */
298 : inline Reference( const BaseReference & rRef, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
299 : /** Constructor: Queries given interface for reference interface type (interface_type).
300 : Throws a RuntimeException if the demanded interface cannot be queried.
301 :
302 : @param pInterface an interface pointer
303 : @param dummy UNO_QUERY_THROW to force obvious distinction
304 : to other constructors
305 : */
306 : inline Reference( XInterface * pInterface, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
307 : /** Constructor: Queries given any for reference interface type (interface_type).
308 : Throws a RuntimeException if the demanded interface cannot be queried.
309 :
310 : @param rAny an any
311 : @param dummy UNO_QUERY_THROW to force obvious distinction
312 : to other constructors
313 : */
314 : inline Reference( const Any & rAny, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
315 : /** Constructor: assigns from the given interface of the same type. Throws a RuntimeException
316 : if the source interface is NULL.
317 :
318 : @param rRef another interface reference of the same type
319 : @param dummy UNO_SET_THROW to distinguish from default copy constructor
320 :
321 : @since UDK 3.2.8
322 : */
323 : inline Reference( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy ) SAL_THROW( (RuntimeException) );
324 : /** Constructor: assigns from the given interface of the same type. Throws a RuntimeException
325 : if the source interface is NULL.
326 :
327 : @param pInterface an interface pointer
328 : @param dummy UNO_SET_THROW to distinguish from default assignment constructor
329 :
330 : @since UDK 3.2.8
331 : */
332 : inline Reference( interface_type * pInterface, UnoReference_SetThrow dummy ) SAL_THROW( (RuntimeException) );
333 : #endif
334 :
335 : /** Cast operator to Reference< XInterface >: Reference objects are binary compatible and
336 : any interface must be derived from com.sun.star.uno.XInterface.
337 : This a useful direct cast possibility.
338 : */
339 536965 : inline SAL_CALL operator const Reference< XInterface > & () const SAL_THROW(())
340 536965 : { return * reinterpret_cast< const Reference< XInterface > * >( this ); }
341 :
342 : /** Dereference operator: Used to call interface methods.
343 :
344 : @return UNacquired interface pointer
345 : */
346 7041042 : inline interface_type * SAL_CALL operator -> () const SAL_THROW(())
347 7041042 : { return castFromXInterface(_pInterface); }
348 :
349 : /** Gets interface pointer. This call does not acquire the interface.
350 :
351 : @return UNacquired interface pointer
352 : */
353 632917 : inline interface_type * SAL_CALL get() const SAL_THROW(())
354 632917 : { return castFromXInterface(_pInterface); }
355 :
356 : /** Clears reference, i.e. releases interface. Reference is null after clear() call.
357 : */
358 : inline void SAL_CALL clear() SAL_THROW(());
359 :
360 : /** Sets the given interface. An interface already set will be released.
361 :
362 : @param rRef another reference
363 : @return true, if non-null interface was set
364 : */
365 : inline sal_Bool SAL_CALL set( const Reference< interface_type > & rRef ) SAL_THROW(());
366 : /** Sets the given interface. An interface already set will be released.
367 :
368 : @param pInterface another interface
369 : @return true, if non-null interface was set
370 : */
371 : inline sal_Bool SAL_CALL set( interface_type * pInterface ) SAL_THROW(());
372 :
373 : /** Sets interface pointer without acquiring it. An interface already set will be released.
374 :
375 : @param pInterface an interface pointer
376 : @param dummy SAL_NO_ACQUIRE to force obvious distinction to set methods
377 : @return true, if non-null interface was set
378 : */
379 : inline sal_Bool SAL_CALL set( interface_type * pInterface, __sal_NoAcquire dummy) SAL_THROW(());
380 : /** Sets interface pointer without acquiring it. An interface already set will be released.
381 : Deprecated, please use SAL_NO_ACQUIRE version.
382 :
383 : @deprecated
384 : @param pInterface an interface pointer
385 : @param dummy UNO_REF_NO_ACQUIRE to force obvious distinction to set methods
386 : @return true, if non-null interface was set
387 : */
388 : inline sal_Bool SAL_CALL set( interface_type * pInterface, UnoReference_NoAcquire dummy) SAL_THROW(());
389 :
390 : /** Queries given interface for reference interface type (interface_type) and sets it.
391 : An interface already set will be released.
392 :
393 : @param pInterface an interface pointer
394 : @param dummy UNO_QUERY to force obvious distinction to set methods
395 : @return true, if non-null interface was set
396 : */
397 : inline sal_Bool SAL_CALL set( XInterface * pInterface, UnoReference_Query dummy ) SAL_THROW( (RuntimeException) );
398 : /** Queries given interface for reference interface type (interface_type) and sets it.
399 : An interface already set will be released.
400 :
401 : @param rRef another reference
402 : @param dummy UNO_QUERY to force obvious distinction to set methods
403 : @return true, if non-null interface was set
404 : */
405 : inline sal_Bool SAL_CALL set( const BaseReference & rRef, UnoReference_Query dummy) SAL_THROW( (RuntimeException) );
406 :
407 : /** Queries given any for reference interface type (interface_type)
408 : and sets it. An interface already set will be released.
409 :
410 : @param rAny
411 : an Any containing an interface
412 : @param dummy
413 : UNO_QUERY to force obvious distinction
414 : to set methods
415 : @return
416 : true, if non-null interface was set
417 : */
418 : inline bool set( Any const & rAny, UnoReference_Query dummy );
419 :
420 : #ifndef EXCEPTIONS_OFF
421 : /** Queries given interface for reference interface type (interface_type) and sets it.
422 : An interface already set will be released.
423 : Throws a RuntimeException if the demanded interface cannot be set.
424 :
425 : @param pInterface an interface pointer
426 : @param dummy UNO_QUERY_THROW to force obvious distinction
427 : to set methods
428 : */
429 : inline void SAL_CALL set( XInterface * pInterface, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
430 : /** Queries given interface for reference interface type (interface_type) and sets it.
431 : An interface already set will be released.
432 : Throws a RuntimeException if the demanded interface cannot be set.
433 :
434 : @param rRef another reference
435 : @param dummy UNO_QUERY_THROW to force obvious distinction
436 : to set methods
437 : */
438 : inline void SAL_CALL set( const BaseReference & rRef, UnoReference_QueryThrow dummy ) SAL_THROW( (RuntimeException) );
439 :
440 : /** Queries given any for reference interface type (interface_type) and
441 : sets it. An interface already set will be released.
442 : Throws a RuntimeException if the demanded interface cannot be set.
443 :
444 : @param rAny
445 : an Any containing an interface
446 : @param dummy
447 : UNO_QUERY_THROW to force obvious distinction to set methods
448 : */
449 : inline void set( Any const & rAny, UnoReference_QueryThrow dummy);
450 : /** sets the given interface
451 : An interface already set will be released.
452 : Throws a RuntimeException if the source interface is <NULL/>.
453 :
454 : @param pInterface an interface pointer
455 : @param dummy UNO_SET_THROW to force obvious distinction to other set methods
456 :
457 : @since UDK 3.2.8
458 : */
459 : inline void SAL_CALL set( interface_type * pInterface, UnoReference_SetThrow dummy) SAL_THROW( (RuntimeException) );
460 : /** sets the given interface
461 : An interface already set will be released.
462 : Throws a RuntimeException if the source interface is <NULL/>.
463 :
464 : @param rRef an interface reference
465 : @param dummy UNO_SET_THROW to force obvious distinction to other set methods
466 :
467 : @since UDK 3.2.8
468 : */
469 : inline void SAL_CALL set( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy) SAL_THROW( (RuntimeException) );
470 :
471 : #endif
472 :
473 : /** Assignment operator: Acquires given interface pointer and sets reference.
474 : An interface already set will be released.
475 :
476 : @param pInterface an interface pointer
477 : @return this reference
478 : */
479 : inline Reference< interface_type > & SAL_CALL operator = ( interface_type * pInterface ) SAL_THROW(());
480 : /** Assignment operator: Acquires given interface reference and sets reference.
481 : An interface already set will be released.
482 :
483 : @param rRef an interface reference
484 : @return this reference
485 : */
486 : inline Reference< interface_type > & SAL_CALL operator = ( const Reference< interface_type > & rRef ) SAL_THROW(());
487 :
488 : /** Queries given interface reference for type interface_type.
489 :
490 : @param rRef interface reference
491 : @return interface reference of demanded type (may be null)
492 : */
493 : inline static Reference< interface_type > SAL_CALL query( const BaseReference & rRef ) SAL_THROW( (RuntimeException) );
494 : /** Queries given interface for type interface_type.
495 :
496 : @param pInterface interface pointer
497 : @return interface reference of demanded type (may be null)
498 : */
499 : inline static Reference< interface_type > SAL_CALL query( XInterface * pInterface ) SAL_THROW( (RuntimeException) );
500 : };
501 :
502 : /// @cond INTERNAL
503 : /** Enables boost::mem_fn and boost::bind to recognize Reference.
504 : */
505 : template <typename T>
506 4193 : inline T * get_pointer( Reference<T> const& r )
507 : {
508 4193 : return r.get();
509 : }
510 : /// @endcond
511 :
512 : }
513 : }
514 : }
515 : }
516 :
517 : #endif
518 :
519 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
