Branch data 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 : 163110048 : 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 : 18100591 : inline XInterface * SAL_CALL get() const SAL_THROW(())
87 : 18100591 : { 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 : 125704048 : inline sal_Bool SAL_CALL is() const SAL_THROW(())
94 : 125704048 : { 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 : 126337555 : static inline interface_type * castFromXInterface(XInterface * p) {
207 : 126337555 : 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 : 88013648 : static inline XInterface * castToXInterface(interface_type * p) {
222 : 88013648 : 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 : 13325 : inline static void * SAL_CALL operator new ( ::size_t nSize ) SAL_THROW(())
229 : 13325 : { return ::rtl_allocateMemory( nSize ); }
230 : 12624 : inline static void SAL_CALL operator delete ( void * pMem ) SAL_THROW(())
231 : 12624 : { ::rtl_freeMemory( pMem ); }
232 : 95541 : inline static void * SAL_CALL operator new ( ::size_t, void * pMem ) SAL_THROW(())
233 : 95541 : { return pMem; }
234 : : inline static void SAL_CALL operator delete ( void *, void * ) SAL_THROW(())
235 : : {}
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 : 5803655 : inline SAL_CALL operator const Reference< XInterface > & () const SAL_THROW(())
340 : 5803655 : { return * reinterpret_cast< const Reference< XInterface > * >( this ); }
341 : :
342 : : /** Dereference operator: Used to call interface methods.
343 : :
344 : : @return UNacquired interface pointer
345 : : */
346 : 79551142 : inline interface_type * SAL_CALL operator -> () const SAL_THROW(())
347 : 79551142 : { return castFromXInterface(_pInterface); }
348 : :
349 : : /** Gets interface pointer. This call does not acquire the interface.
350 : :
351 : : @return UNacquired interface pointer
352 : : */
353 : 12471662 : inline interface_type * SAL_CALL get() const SAL_THROW(())
354 : 12471662 : { 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 : 12597 : inline T * get_pointer( Reference<T> const& r )
507 : : {
508 : 12597 : return r.get();
509 : : }
510 : : /// @endcond
511 : :
512 : : }
513 : : }
514 : : }
515 : : }
516 : :
517 : : #endif
518 : :
519 : : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
