LibreOffice
LibreOffice 7.1 SDK C/C++ API Reference
Reference.h
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 #ifndef INCLUDED_COM_SUN_STAR_UNO_REFERENCE_H
20 #define INCLUDED_COM_SUN_STAR_UNO_REFERENCE_H
21 
22 #include "sal/config.h"
23 
24 #include <cassert>
25 #include <cstddef>
26 
27 #if defined LIBO_INTERNAL_ONLY
28 #include <type_traits>
29 #endif
30 
31 #include "rtl/alloc.h"
32 
33 namespace com
34 {
35 namespace sun
36 {
37 namespace star
38 {
39 namespace uno
40 {
41 
42 class RuntimeException;
43 class XInterface;
44 class Type;
45 class Any;
46 
52 {
57 };
58 
63 {
64 protected:
67  XInterface * _pInterface;
68 
75  inline static XInterface * SAL_CALL iquery( XInterface * pInterface, const Type & rType );
83  inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface, const Type & rType );
84 
85 public:
90  XInterface * SAL_CALL get() const
91  { return _pInterface; }
92 
97  bool SAL_CALL is() const
98  { return (NULL != _pInterface); }
99 
100 #if defined LIBO_INTERNAL_ONLY
105  explicit operator bool() const
106  { return is(); }
107 #endif
108 
115  inline bool SAL_CALL operator == ( XInterface * pInterface ) const;
122  inline bool SAL_CALL operator != ( XInterface * pInterface ) const;
123 
130  inline bool SAL_CALL operator == ( const BaseReference & rRef ) const;
137  inline bool SAL_CALL operator != ( const BaseReference & rRef ) const;
138 
144  inline bool SAL_CALL operator < ( const BaseReference & rRef ) const;
145 };
146 
150 {
153  UNO_QUERY
154 };
159 {
163 };
170 {
172 };
173 
178 template< class interface_type >
179 class SAL_DLLPUBLIC_RTTI Reference : public BaseReference
180 {
186  inline static XInterface * SAL_CALL iquery( XInterface * pInterface );
193  inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface );
199  inline static interface_type * SAL_CALL iset_throw( interface_type * pInterface );
200 
212  static interface_type * castFromXInterface(XInterface * p) {
213  return static_cast< interface_type * >(static_cast< void * >(p));
214  }
215 
227  static XInterface * castToXInterface(interface_type * p) {
228  return static_cast< XInterface * >(static_cast< void * >(p));
229  }
230 
231 public:
233  // these are here to force memory de/allocation to sal lib.
234  static void * SAL_CALL operator new ( ::size_t nSize )
235  { return ::rtl_allocateMemory( nSize ); }
236  static void SAL_CALL operator delete ( void * pMem )
237  { ::rtl_freeMemory( pMem ); }
238  static void * SAL_CALL operator new ( ::size_t, void * pMem )
239  { return pMem; }
240  static void SAL_CALL operator delete ( void *, void * )
241  {}
243 
247 
250  inline Reference();
251 
256  inline Reference( const Reference< interface_type > & rRef );
257 
258 #if defined LIBO_INTERNAL_ONLY
263  inline Reference( Reference< interface_type > && rRef ) noexcept;
264 
273  template< class derived_type >
274  inline Reference(
275  const Reference< derived_type > & rRef,
276  std::enable_if_t<
277  std::is_base_of_v<interface_type, derived_type>
278  && !std::is_same_v<interface_type, XInterface>, void *> = nullptr);
279 #endif
280 
285  inline Reference( interface_type * pInterface );
286 
292  inline Reference( interface_type * pInterface, __sal_NoAcquire dummy);
300  inline SAL_DEPRECATED("use SAL_NO_ACQUIRE version") Reference( interface_type * pInterface, UnoReference_NoAcquire dummy );
301 
307  inline Reference( const BaseReference & rRef, UnoReference_Query dummy );
313  inline Reference( XInterface * pInterface, UnoReference_Query dummy);
319  inline Reference( const Any & rAny, UnoReference_Query dummy);
327  inline Reference( const BaseReference & rRef, UnoReference_QueryThrow dummy );
328 #ifdef LIBO_INTERNAL_ONLY
332  Reference( const Reference< interface_type > & rRef, UnoReference_QueryThrow dummy ) = delete;
333 #endif
341  inline Reference( XInterface * pInterface, UnoReference_QueryThrow dummy );
349  inline Reference( const Any & rAny, UnoReference_QueryThrow dummy );
358  inline Reference( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy );
367  inline Reference( interface_type * pInterface, UnoReference_SetThrow dummy );
368 
373  SAL_CALL operator const Reference< XInterface > & () const
374  { return * reinterpret_cast< const Reference< XInterface > * >( this ); }
375 
380  interface_type * SAL_CALL operator -> () const {
381  assert(_pInterface != NULL);
382  return castFromXInterface(_pInterface);
383  }
384 
390  interface_type & SAL_CALL operator * () const {
391  assert(_pInterface != NULL);
392  return *castFromXInterface(_pInterface);
393  }
394 
399  interface_type * SAL_CALL get() const
400  { return castFromXInterface(_pInterface); }
401 
404  inline void SAL_CALL clear();
405 
411  inline bool SAL_CALL set( const Reference< interface_type > & rRef );
417  inline bool SAL_CALL set( interface_type * pInterface );
418 
425  inline bool SAL_CALL set( interface_type * pInterface, __sal_NoAcquire dummy);
434  inline SAL_DEPRECATED("use SAL_NO_ACQUIRE version") bool SAL_CALL set( interface_type * pInterface, UnoReference_NoAcquire dummy);
435 
443  inline bool SAL_CALL set( XInterface * pInterface, UnoReference_Query dummy );
451  inline bool SAL_CALL set( const BaseReference & rRef, UnoReference_Query dummy);
452 
464  inline bool set( Any const & rAny, UnoReference_Query dummy );
465 
474  inline void SAL_CALL set( XInterface * pInterface, UnoReference_QueryThrow dummy );
483  inline void SAL_CALL set( const BaseReference & rRef, UnoReference_QueryThrow dummy );
484 #ifdef LIBO_INTERNAL_ONLY
488  void set( const Reference< interface_type > & rRef, UnoReference_QueryThrow dummy ) = delete;
489 #endif
490 
500  inline void set( Any const & rAny, UnoReference_QueryThrow dummy);
510  inline void SAL_CALL set( interface_type * pInterface, UnoReference_SetThrow dummy);
520  inline void SAL_CALL set( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy);
521 
522 
529  inline Reference< interface_type > & SAL_CALL operator = ( interface_type * pInterface );
536  inline Reference< interface_type > & SAL_CALL operator = ( const Reference< interface_type > & rRef );
537 #if defined LIBO_INTERNAL_ONLY
544  inline Reference< interface_type > & SAL_CALL operator = ( Reference< interface_type > && rRef ) noexcept;
545 #endif
551  SAL_WARN_UNUSED_RESULT inline static Reference< interface_type > SAL_CALL query( const BaseReference & rRef );
557  SAL_WARN_UNUSED_RESULT inline static Reference< interface_type > SAL_CALL query( XInterface * pInterface );
558 };
559 
560 }
561 }
562 }
563 }
564 
565 #endif
566 
567 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
#define SAL_DEPRECATED(message)
Use as follows: SAL_DEPRECATED("Don't use, it's evil.") void doit(int nPara);.
Definition: types.h:445
__sal_NoAcquire
Definition: types.h:349
#define COVERITY_NOEXCEPT_FALSE
To markup destructors that coverity warns might throw exceptions which won't throw in practice,...
Definition: types.h:333
#define SAL_WARN_UNUSED_RESULT
Use this as markup for functions and methods whose return value must be checked.
Definition: types.h:280
SAL_DLLPUBLIC void rtl_freeMemory(void *Ptr) SAL_THROW_EXTERN_C()
Free memory.
SAL_DLLPUBLIC void * rtl_allocateMemory(sal_Size Bytes) SAL_THROW_EXTERN_C()
Allocate memory.
Definition: types.h:355
UnoReference_NoAcquire
Enum defining UNO_REF_NO_ACQUIRE for setting reference without acquiring a given interface.
Definition: Reference.h:52
@ UNO_REF_NO_ACQUIRE
This enum value can be used for creating a reference granting a given interface, i....
Definition: Reference.h:56
UnoReference_QueryThrow
Enum defining UNO_QUERY_THROW for implicit interface query.
Definition: Reference.h:159
@ UNO_QUERY_THROW
This enum value can be used for implicit interface query.
Definition: Reference.h:162
UnoReference_Query
Enum defining UNO_QUERY for implicit interface query.
Definition: Reference.h:150
@ UNO_QUERY
This enum value can be used for implicit interface query.
Definition: Reference.h:153
UnoReference_SetThrow
Enum defining UNO_SET_THROW for throwing if attempts are made to assign a null interface.
Definition: Reference.h:170
@ UNO_SET_THROW
Definition: Reference.h:171
Template reference class for interface type derived from BaseReference.
Definition: Reference.h:180
interface_type * get() const
Gets interface pointer.
Definition: Reference.h:399
C++ class representing an IDL any.
Definition: Any.h:53
This base class serves as a base class for all template reference classes and has been introduced due...
Definition: Reference.h:63
bool operator<(const BaseReference &rRef) const
Needed by some STL containers.
Definition: Reference.hxx:403
static XInterface * iquery(XInterface *pInterface, const Type &rType)
Queries given interface for type rType.
Definition: Reference.hxx:50
bool operator!=(XInterface *pInterface) const
Inequality operator: compares two interfaces Checks if both references are null or refer to the same ...
Definition: Reference.hxx:422
XInterface * _pInterface
the interface pointer
Definition: Reference.h:67
static XInterface * iquery_throw(XInterface *pInterface, const Type &rType)
Queries given interface for type rType.
Definition: Reference.hxx:73
XInterface * get() const
Gets interface pointer.
Definition: Reference.h:90
bool is() const
Checks if reference is null.
Definition: Reference.h:97
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:385
C++ class representing an IDL meta type.
Definition: Type.h:55