LibreOffice
LibreOffice 25.2 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 
20 /*
21  * This file is part of LibreOffice published API.
22  */
23 #ifndef INCLUDED_COM_SUN_STAR_UNO_REFERENCE_H
24 #define INCLUDED_COM_SUN_STAR_UNO_REFERENCE_H
25 
26 #include "sal/config.h"
27 
28 #include <cassert>
29 #include <cstddef>
30 
31 #if defined LIBO_INTERNAL_ONLY
32 #include <type_traits>
33 #endif
34 
35 #include "rtl/alloc.h"
36 
37 namespace com
38 {
39 namespace sun
40 {
41 namespace star
42 {
43 namespace uno
44 {
45 
46 class RuntimeException;
47 class XInterface;
48 class Type;
49 class Any;
50 
56 {
61 };
62 
67 {
68 protected:
71  XInterface * _pInterface;
72 
79  inline static XInterface * SAL_CALL iquery( XInterface * pInterface, const Type & rType );
87  inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface, const Type & rType );
88 
89 public:
94  XInterface * SAL_CALL get() const
95  { return _pInterface; }
96 
101  bool SAL_CALL is() const
102  { return (NULL != _pInterface); }
103 
104 #if defined LIBO_INTERNAL_ONLY
105 
109  explicit operator bool() const
110  { return is(); }
111 #endif
112 
119  inline bool SAL_CALL operator == ( XInterface * pInterface ) const;
126  inline bool SAL_CALL operator != ( XInterface * pInterface ) const;
127 
134  inline bool SAL_CALL operator == ( const BaseReference & rRef ) const;
141  inline bool SAL_CALL operator != ( const BaseReference & rRef ) const;
142 
148  inline bool SAL_CALL operator < ( const BaseReference & rRef ) const;
149 };
150 
154 {
158 };
163 {
167 };
174 {
176 };
177 
182 template< class interface_type >
183 class SAL_DLLPUBLIC_RTTI Reference : public BaseReference
184 {
190  inline static XInterface * SAL_CALL iquery( XInterface * pInterface );
197  inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface );
203  inline static interface_type * SAL_CALL iset_throw( interface_type * pInterface );
204 
216  static interface_type * castFromXInterface(XInterface * p) {
217  return static_cast< interface_type * >(static_cast< void * >(p));
218  }
219 
231  static XInterface * castToXInterface(interface_type * p) {
232  return static_cast< XInterface * >(static_cast< void * >(p));
233  }
234 
235 public:
237  // these are here to force memory de/allocation to sal lib.
238  static void * SAL_CALL operator new ( ::size_t nSize )
239  { return ::rtl_allocateMemory( nSize ); }
240  static void SAL_CALL operator delete ( void * pMem )
241  { ::rtl_freeMemory( pMem ); }
242  static void * SAL_CALL operator new ( ::size_t, void * pMem )
243  { return pMem; }
244  static void SAL_CALL operator delete ( void *, void * )
245  {}
247 
250  inline ~Reference() COVERITY_NOEXCEPT_FALSE;
251 
254  inline Reference();
255 
260  inline Reference( const Reference< interface_type > & rRef );
261 
262 #if defined LIBO_INTERNAL_ONLY
263 
267 #if !defined(__COVERITY__) // suppress COPY_INSTEAD_OF_MOVE suggestions
268  inline Reference( Reference< interface_type > && rRef ) noexcept;
269 #endif
270 
279  template< class derived_type >
280  inline Reference(
281  const Reference< derived_type > & rRef,
282  std::enable_if_t<
283  std::is_base_of_v<interface_type, derived_type>
284  && !std::is_same_v<interface_type, XInterface>, void *> = nullptr);
285 #endif
286 
291  inline Reference( interface_type * pInterface );
292 
298  inline Reference( interface_type * pInterface, __sal_NoAcquire dummy);
306  inline SAL_DEPRECATED("use SAL_NO_ACQUIRE version") Reference( interface_type * pInterface, UnoReference_NoAcquire dummy );
307 
313  inline Reference( const BaseReference & rRef, UnoReference_Query dummy );
319  inline Reference( XInterface * pInterface, UnoReference_Query dummy);
325  inline Reference( const Any & rAny, UnoReference_Query dummy);
333  inline Reference( const BaseReference & rRef, UnoReference_QueryThrow dummy );
334 #ifdef LIBO_INTERNAL_ONLY
335 
338  Reference( const Reference< interface_type > & rRef, UnoReference_QueryThrow dummy ) = delete;
339 #endif
340 
347  inline Reference( XInterface * pInterface, UnoReference_QueryThrow dummy );
355  inline Reference( const Any & rAny, UnoReference_QueryThrow dummy );
364  inline Reference( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy );
373  inline Reference( interface_type * pInterface, UnoReference_SetThrow dummy );
374 
379  SAL_CALL operator const Reference< XInterface > & () const
380  { return * reinterpret_cast< const Reference< XInterface > * >( this ); }
381 
386  interface_type * SAL_CALL operator -> () const {
387  assert(_pInterface != NULL);
388  return castFromXInterface(_pInterface);
389  }
390 
396  interface_type & SAL_CALL operator * () const {
397  assert(_pInterface != NULL);
398  return *castFromXInterface(_pInterface);
399  }
400 
405  interface_type * SAL_CALL get() const
406  { return castFromXInterface(_pInterface); }
407 
410  inline void SAL_CALL clear();
411 
417  inline bool SAL_CALL set( const Reference< interface_type > & rRef );
423  inline bool SAL_CALL set( interface_type * pInterface );
424 
431  inline bool SAL_CALL set( interface_type * pInterface, __sal_NoAcquire dummy);
440  inline SAL_DEPRECATED("use SAL_NO_ACQUIRE version") bool SAL_CALL set( interface_type * pInterface, UnoReference_NoAcquire dummy);
441 
449  inline bool SAL_CALL set( XInterface * pInterface, UnoReference_Query dummy );
457  inline bool SAL_CALL set( const BaseReference & rRef, UnoReference_Query dummy);
458 
470  inline bool set( Any const & rAny, UnoReference_Query dummy );
471 
480  inline void SAL_CALL set( XInterface * pInterface, UnoReference_QueryThrow dummy );
489  inline void SAL_CALL set( const BaseReference & rRef, UnoReference_QueryThrow dummy );
490 #ifdef LIBO_INTERNAL_ONLY
491 
494  void set( const Reference< interface_type > & rRef, UnoReference_QueryThrow dummy ) = delete;
495 #endif
496 
506  inline void set( Any const & rAny, UnoReference_QueryThrow dummy);
516  inline void SAL_CALL set( interface_type * pInterface, UnoReference_SetThrow dummy);
526  inline void SAL_CALL set( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy);
527 
528 
535  inline Reference< interface_type > & SAL_CALL operator = ( interface_type * pInterface );
542  inline Reference< interface_type > & SAL_CALL operator = ( const Reference< interface_type > & rRef );
543 #if defined LIBO_INTERNAL_ONLY
544 
550  inline Reference< interface_type > & operator = ( Reference< interface_type > && rRef ) noexcept;
551 #endif
552 
557  SAL_WARN_UNUSED_RESULT inline static Reference< interface_type > SAL_CALL query( const BaseReference & rRef );
563  SAL_WARN_UNUSED_RESULT inline static Reference< interface_type > SAL_CALL query( XInterface * pInterface );
564 #if defined LIBO_INTERNAL_ONLY
565 
571  template< class other_type > inline Reference< other_type > query() const;
578  template< class other_type > inline Reference< other_type > queryThrow() const;
579 #endif
580 };
581 
582 }
583 }
584 }
585 }
586 
587 #endif
588 
589 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
UnoReference_NoAcquire
Enum defining UNO_REF_NO_ACQUIRE for setting reference without acquiring a given interface.
Definition: Reference.h:55
This enum value can be used for creating a reference granting a given interface, i.e.
Definition: Reference.h:60
#define COVERITY_NOEXCEPT_FALSE
To markup destructors that coverity warns might throw exceptions which won&#39;t throw in practice...
Definition: types.h:367
bool is() const
Checks if reference is null.
Definition: Reference.h:101
static XInterface * iquery_throw(XInterface *pInterface, const Type &rType)
Queries given interface for type rType.
Definition: Reference.hxx:77
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
#define SAL_DEPRECATED(message)
Use as follows: SAL_DEPRECATED("Don&#39;t use, it&#39;s evil.") void doit(int nPara);.
Definition: types.h:492
C++ class representing an IDL any.
Definition: Any.h:57
SAL_DLLPUBLIC void * rtl_allocateMemory(sal_Size Bytes) SAL_THROW_EXTERN_C()
Allocate memory.
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
__sal_NoAcquire
Definition: types.h:370
UnoReference_QueryThrow
Enum defining UNO_QUERY_THROW for implicit interface query.
Definition: Reference.h:162
#define SAL_WARN_UNUSED_RESULT
Use this as markup for functions and methods whose return value must be used.
Definition: types.h:288
This base class serves as a base class for all template reference classes and has been introduced due...
Definition: Reference.h:66
SAL_DLLPUBLIC void rtl_freeMemory(void *Ptr) SAL_THROW_EXTERN_C()
Free memory.
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
C++ class representing an IDL meta type.
Definition: Type.h:58
XInterface * _pInterface
the interface pointer
Definition: Reference.h:71