LibreOffice
LibreOffice 24.8 SDK C/C++ API Reference
Reference.hxx
Go to the documentation of this file.
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 
20 /*
21  * This file is part of LibreOffice published API.
22  */
23 #ifndef INCLUDED_COM_SUN_STAR_UNO_REFERENCE_HXX
24 #define INCLUDED_COM_SUN_STAR_UNO_REFERENCE_HXX
25 
26 #include "sal/config.h"
27 
28 #include <cstddef>
29 #include <ostream>
30 
32 #include "com/sun/star/uno/RuntimeException.hpp"
33 #include "com/sun/star/uno/XInterface.hpp"
34 #include "com/sun/star/uno/Any.hxx"
35 #include "cppu/cppudllapi.h"
36 
37 extern "C" CPPU_DLLPUBLIC rtl_uString * SAL_CALL cppu_unsatisfied_iquery_msg(
40 extern "C" CPPU_DLLPUBLIC rtl_uString * SAL_CALL cppu_unsatisfied_iset_msg(
43 
44 namespace com
45 {
46 namespace sun
47 {
48 namespace star
49 {
50 namespace uno
51 {
52 
53 
54 inline XInterface * BaseReference::iquery(
55  XInterface * pInterface, const Type & rType )
56 {
57  if (pInterface)
58  {
59  Any aRet( pInterface->queryInterface( rType ) );
60  if (typelib_TypeClass_INTERFACE == aRet.pType->eTypeClass)
61  {
62  XInterface * pRet = static_cast< XInterface * >( aRet.pReserved );
63  aRet.pReserved = NULL;
64  return pRet;
65  }
66  }
67  return NULL;
68 }
69 
70 template< class interface_type >
71 inline XInterface * Reference< interface_type >::iquery(
72  XInterface * pInterface )
73 {
74  return BaseReference::iquery(pInterface, interface_type::static_type());
75 }
76 
77 inline XInterface * BaseReference::iquery_throw(
78  XInterface * pInterface, const Type & rType )
79 {
80  XInterface * pQueried = iquery( pInterface, rType );
81  if (pQueried)
82  return pQueried;
83  throw RuntimeException(
85  Reference< XInterface >( pInterface ) );
86 }
87 
88 template< class interface_type >
90  XInterface * pInterface )
91 {
93  pInterface, interface_type::static_type());
94 }
95 
96 template< class interface_type >
97 inline interface_type * Reference< interface_type >::iset_throw(
98  interface_type * pInterface )
99 {
100  if (pInterface)
101  {
102  castToXInterface(pInterface)->acquire();
103  return pInterface;
104  }
105  throw RuntimeException(
106  ::rtl::OUString( cppu_unsatisfied_iset_msg( interface_type::static_type().getTypeLibType() ), SAL_NO_ACQUIRE ),
107  NULL );
108 }
109 
110 template< class interface_type >
112 {
113  if (_pInterface)
114  _pInterface->release();
115 }
116 
117 template< class interface_type >
119 {
120  _pInterface = NULL;
121 }
122 
123 template< class interface_type >
125 {
126  _pInterface = rRef._pInterface;
127  if (_pInterface)
128  _pInterface->acquire();
129 }
130 
131 #if defined LIBO_INTERNAL_ONLY
132 
133 #if !defined(__COVERITY__)
134 template< class interface_type >
136 {
137  _pInterface = rRef._pInterface;
138  rRef._pInterface = nullptr;
139 }
140 #endif
141 
142 template< class interface_type > template< class derived_type >
144  const Reference< derived_type > & rRef,
145  std::enable_if_t<
146  std::is_base_of_v<interface_type, derived_type>
147  && !std::is_same_v<interface_type, XInterface>, void *>)
148 {
149  interface_type * p = rRef.get();
150  _pInterface = castToXInterface(p);
151  if (_pInterface)
152  _pInterface->acquire();
153 }
154 #endif
155 
156 template< class interface_type >
157 inline Reference< interface_type >::Reference( interface_type * pInterface )
158 {
159  _pInterface = castToXInterface(pInterface);
160  if (_pInterface)
161  _pInterface->acquire();
162 }
163 
164 template< class interface_type >
165 inline Reference< interface_type >::Reference( interface_type * pInterface, __sal_NoAcquire )
166 {
167  _pInterface = castToXInterface(pInterface);
168 }
169 
170 template< class interface_type >
172 {
173  _pInterface = castToXInterface(pInterface);
174 }
175 
176 template< class interface_type >
178 {
179  _pInterface = iquery( rRef.get() );
180 }
181 
182 template< class interface_type >
184 {
185  _pInterface = iquery( pInterface );
186 }
187 
188 template< class interface_type >
190 {
191  _pInterface = (typelib_TypeClass_INTERFACE == rAny.pType->eTypeClass
192  ? iquery( static_cast< XInterface * >( rAny.pReserved ) ) : NULL);
193 }
194 
195 template< class interface_type >
197 {
198  _pInterface = iquery_throw( rRef.get() );
199 }
200 
201 template< class interface_type >
203 {
204  _pInterface = iquery_throw( pInterface );
205 }
206 
207 template< class interface_type >
209 {
210  _pInterface = iquery_throw( typelib_TypeClass_INTERFACE == rAny.pType->eTypeClass
211  ? static_cast< XInterface * >( rAny.pReserved ) : NULL );
212 }
213 
214 template< class interface_type >
216 {
217  _pInterface = castToXInterface( iset_throw( rRef.get() ) );
218 }
219 
220 template< class interface_type >
221 inline Reference< interface_type >::Reference( interface_type * pInterface, UnoReference_SetThrow )
222 {
223  _pInterface = castToXInterface( iset_throw( pInterface ) );
224 }
225 
226 
227 template< class interface_type >
229 {
230  if (_pInterface)
231  {
232  XInterface * const pOld = _pInterface;
233  _pInterface = NULL;
234  pOld->release();
235  }
236 }
237 
238 template< class interface_type >
240  interface_type * pInterface )
241 {
242  if (pInterface)
243  castToXInterface(pInterface)->acquire();
244  XInterface * const pOld = _pInterface;
245  _pInterface = castToXInterface(pInterface);
246  if (pOld)
247  pOld->release();
248  return (NULL != pInterface);
249 }
250 
251 template< class interface_type >
253  interface_type * pInterface, __sal_NoAcquire )
254 {
255  XInterface * const pOld = _pInterface;
256  _pInterface = castToXInterface(pInterface);
257  if (pOld)
258  pOld->release();
259  return (NULL != pInterface);
260 }
261 
262 template< class interface_type >
264  interface_type * pInterface, UnoReference_NoAcquire )
265 {
266  return set( pInterface, SAL_NO_ACQUIRE );
267 }
268 
269 
270 template< class interface_type >
272  const Reference< interface_type > & rRef )
273 {
274  return set( castFromXInterface( rRef._pInterface ) );
275 }
276 
277 template< class interface_type >
279  XInterface * pInterface, UnoReference_Query )
280 {
281  return set( castFromXInterface(iquery( pInterface )), SAL_NO_ACQUIRE );
282 }
283 
284 template< class interface_type >
286  const BaseReference & rRef, UnoReference_Query )
287 {
288  return set( castFromXInterface(iquery( rRef.get() )), SAL_NO_ACQUIRE );
289 }
290 
291 
292 template< class interface_type >
294  Any const & rAny, UnoReference_Query )
295 {
296  return set(
297  castFromXInterface(
298  iquery(
299  rAny.pType->eTypeClass == typelib_TypeClass_INTERFACE
300  ? static_cast< XInterface * >( rAny.pReserved ) : NULL )),
301  SAL_NO_ACQUIRE );
302 }
303 
304 
305 template< class interface_type >
307  XInterface * pInterface, UnoReference_QueryThrow )
308 {
309  set( castFromXInterface(iquery_throw( pInterface )), SAL_NO_ACQUIRE );
310 }
311 
312 template< class interface_type >
314  const BaseReference & rRef, UnoReference_QueryThrow )
315 {
316  set( castFromXInterface(iquery_throw( rRef.get() )), SAL_NO_ACQUIRE );
317 }
318 
319 
320 template< class interface_type >
322  Any const & rAny, UnoReference_QueryThrow )
323 {
324  set( castFromXInterface(
325  iquery_throw(
326  rAny.pType->eTypeClass == typelib_TypeClass_INTERFACE
327  ? static_cast< XInterface * >( rAny.pReserved ) : NULL )),
328  SAL_NO_ACQUIRE );
329 }
330 
331 template< class interface_type >
333  interface_type * pInterface, UnoReference_SetThrow )
334 {
335  set( iset_throw( pInterface ), SAL_NO_ACQUIRE );
336 }
337 
338 template< class interface_type >
341 {
342  set( rRef.get(), UNO_SET_THROW );
343 }
344 
345 
346 template< class interface_type >
348  interface_type * pInterface )
349 {
350  set( pInterface );
351  return *this;
352 }
353 
354 template< class interface_type >
356  const Reference< interface_type > & rRef )
357 {
358  set( castFromXInterface( rRef._pInterface ) );
359  return *this;
360 }
361 
362 #if defined LIBO_INTERNAL_ONLY
363 template< class interface_type >
365  Reference< interface_type > && rRef ) noexcept
366 {
367  if (_pInterface)
368  _pInterface->release();
369  _pInterface = rRef._pInterface;
370  rRef._pInterface = nullptr;
371  return *this;
372 }
373 #endif
374 
375 template< class interface_type >
377  const BaseReference & rRef )
378 {
380  castFromXInterface(iquery( rRef.get() )), SAL_NO_ACQUIRE );
381 }
382 
383 template< class interface_type >
385  XInterface * pInterface )
386 {
388  castFromXInterface(iquery( pInterface )), SAL_NO_ACQUIRE );
389 }
390 
391 #if defined LIBO_INTERNAL_ONLY
392 template< class interface_type > template< class other_type >
394 {
395  return Reference< other_type >(*this, UNO_QUERY);
396 }
397 
398 template< class interface_type > template< class other_type >
399 inline Reference< other_type > Reference< interface_type >::queryThrow() const
400 {
401  return Reference< other_type >(*this, UNO_QUERY_THROW);
402 }
403 
404 template< class interface_type >
405 inline Reference< interface_type > Any::query() const
406 {
407  return Reference< interface_type >(*this, UNO_QUERY);
408 }
409 
410 template< class interface_type >
411 inline Reference< interface_type > Any::queryThrow() const
412 {
413  return Reference< interface_type >(*this, UNO_QUERY_THROW);
414 }
415 #endif
416 
417 
418 inline bool BaseReference::operator == ( XInterface * pInterface ) const
419 {
420  if (_pInterface == pInterface)
421  return true;
422  try
423  {
424  // only the query to XInterface must return the same pointer if they belong to same objects
426  Reference< XInterface > x2( pInterface, UNO_QUERY );
427  return (x1._pInterface == x2._pInterface);
428  }
429  catch (RuntimeException &)
430  {
431  return false;
432  }
433 }
434 
435 
437  const BaseReference & rRef ) const
438 {
439  if (_pInterface == rRef._pInterface)
440  return false;
441  try
442  {
443  // only the query to XInterface must return the same pointer:
446  return (x1._pInterface < x2._pInterface);
447  }
448  catch (RuntimeException &)
449  {
450  return false;
451  }
452 }
453 
454 
455 inline bool BaseReference::operator != ( XInterface * pInterface ) const
456 {
457  return (! operator == ( pInterface ));
458 }
459 
460 inline bool BaseReference::operator == ( const BaseReference & rRef ) const
461 {
462  return operator == ( rRef._pInterface );
463 }
464 
465 inline bool BaseReference::operator != ( const BaseReference & rRef ) const
466 {
467  return (! operator == ( rRef._pInterface ));
468 }
469 
470 #if defined LIBO_INTERNAL_ONLY
471 
477 template<typename charT, typename traits> std::basic_ostream<charT, traits> &
479  std::basic_ostream<charT, traits> & stream, BaseReference const & ref)
480 { return stream << ref.get(); }
481 #endif
482 
483 }
484 }
485 }
486 }
487 
488 #if defined LIBO_INTERNAL_ONLY
489 namespace std
490 {
491 
497 template<typename T>
498 struct hash<::css::uno::Reference<T>>
499 {
500  std::size_t operator()(::css::uno::Reference<T> const & s) const
501  { return size_t(s.get()); }
502 };
503 
504 }
505 
506 #endif
507 
508 #endif
509 
510 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
#define SAL_THROW_EXTERN_C()
Nothrow specification for C functions.
Definition: types.h:352
UnoReference_NoAcquire
Enum defining UNO_REF_NO_ACQUIRE for setting reference without acquiring a given interface.
Definition: Reference.h:55
bool set(const Reference< interface_type > &rRef)
Sets the given interface.
Definition: Reference.hxx:271
static SAL_WARN_UNUSED_RESULT Reference< interface_type > query(const BaseReference &rRef)
Queries given interface reference for type interface_type.
Definition: Reference.hxx:376
CPPU_DLLPUBLIC rtl_uString * cppu_unsatisfied_iset_msg(typelib_TypeDescriptionReference *pType) SAL_THROW_EXTERN_C()
#define COVERITY_NOEXCEPT_FALSE
To markup destructors that coverity warns might throw exceptions which won&#39;t throw in practice...
Definition: types.h:367
typelib_TypeDescriptionReference * getTypeLibType() const
Gets the C typelib type description reference pointer.
Definition: Type.h:162
static XInterface * iquery_throw(XInterface *pInterface, const Type &rType)
Queries given interface for type rType.
Definition: Reference.hxx:77
~Reference() COVERITY_NOEXCEPT_FALSE
Destructor: Releases interface if set.
Definition: Reference.hxx:111
bool operator!=(XInterface *pInterface) const
Inequality operator: compares two interfaces Checks if both references are null or refer to the same ...
Definition: Reference.hxx:455
This enum value can be used for implicit interface query.
Definition: Reference.h:157
This enum value can be used for implicit interface query.
Definition: Reference.h:166
bool operator<(const BaseReference &rRef) const
Needed by some STL containers.
Definition: Reference.hxx:436
bool operator==(XInterface *pInterface) const
Equality operator: compares two interfaces Checks if both references are null or refer to the same ob...
Definition: Reference.hxx:418
struct SAL_DLLPUBLIC_RTTI _typelib_TypeDescriptionReference typelib_TypeDescriptionReference
Holds a weak reference to a type description.
std::basic_ostream< charT, traits > & operator<<(std::basic_ostream< charT, traits > &o, Any const &any)
Support for Any in std::ostream (and thus in CPPUNIT_ASSERT or SAL_INFO macros, for example)...
Definition: Any.hxx:708
Reference< interface_type > & operator=(interface_type *pInterface)
Assignment operator: Acquires given interface pointer and sets reference.
Definition: Reference.hxx:347
C++ class representing an IDL any.
Definition: Any.h:57
#define CPPU_DLLPUBLIC
Definition: cppudllapi.h:13
UnoReference_Query
Enum defining UNO_QUERY for implicit interface query.
Definition: Reference.h:153
Definition: Reference.h:175
Definition: types.h:377
Template reference class for interface type derived from BaseReference.
Definition: unotype.hxx:43
interface_type * get() const
Gets interface pointer.
Definition: Reference.h:405
__sal_NoAcquire
Definition: types.h:370
CPPU_DLLPUBLIC rtl_uString * cppu_unsatisfied_iquery_msg(typelib_TypeDescriptionReference *pType) SAL_THROW_EXTERN_C()
void clear()
Clears reference, i.e.
Definition: Reference.hxx:228
type class of interface
Definition: typeclass.h:82
This String class provides base functionality for C++ like Unicode character array handling...
Definition: ustring.hxx:171
definition of a no acquire enum for ctors
Definition: types.h:374
UnoReference_QueryThrow
Enum defining UNO_QUERY_THROW for implicit interface query.
Definition: Reference.h:162
This base class serves as a base class for all template reference classes and has been introduced due...
Definition: Reference.h:66
static XInterface * iquery(XInterface *pInterface, const Type &rType)
Queries given interface for type rType.
Definition: Reference.hxx:54
UnoReference_SetThrow
Enum defining UNO_SET_THROW for throwing if attempts are made to assign a null interface.
Definition: Reference.h:173
Reference()
Default Constructor: Sets null reference.
Definition: Reference.hxx:118
C++ class representing an IDL meta type.
Definition: Type.h:58
XInterface * get() const
Gets interface pointer.
Definition: Reference.h:94
XInterface * _pInterface
the interface pointer
Definition: Reference.h:71