LibreOffice
LibreOffice 6.0 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 #include <rtl/alloc.h>
28 
29 namespace com
30 {
31 namespace sun
32 {
33 namespace star
34 {
35 namespace uno
36 {
37 
38 class RuntimeException;
39 class XInterface;
40 class Type;
41 class Any;
42 
48 {
53 };
54 
59 {
60 protected:
63  XInterface * _pInterface;
64 
71  inline static XInterface * SAL_CALL iquery( XInterface * pInterface, const Type & rType );
79  inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface, const Type & rType );
80 
81 public:
86  XInterface * SAL_CALL get() const
87  { return _pInterface; }
88 
93  bool SAL_CALL is() const
94  { return (NULL != _pInterface); }
95 
96 #if defined LIBO_INTERNAL_ONLY
97 
101  explicit operator bool() const
102  { return is(); }
103 #endif
104 
111  inline bool SAL_CALL operator == ( XInterface * pInterface ) const;
118  inline bool SAL_CALL operator != ( XInterface * pInterface ) const;
119 
126  inline bool SAL_CALL operator == ( const BaseReference & rRef ) const;
133  inline bool SAL_CALL operator != ( const BaseReference & rRef ) const;
134 
140  inline bool SAL_CALL operator < ( const BaseReference & rRef ) const;
141 };
142 
146 {
150 };
155 {
159 };
166 {
168 };
169 
171 namespace detail {
172 
173 // A mechanism to enable up-casts, used by the Reference conversion constructor,
174 // but at the same time disable up-casts to XInterface, so that the conversion
175 // operator for that special case is used in an expression like
176 // Reference< XInterface >(x); heavily borrowed from boost::is_base_and_derived
177 // (which manages to avoid compilation problems with ambiguous bases and cites
178 // comp.lang.c++.moderated mail <http://groups.google.com/groups?
179 // selm=df893da6.0301280859.522081f7%40posting.google.com> "SuperSubclass
180 // (is_base_and_derived) complete implementation!" by Rani Sharoni and cites
181 // Aleksey Gurtovoy for the workaround for MSVC), to avoid including Boost
182 // headers in URE headers (could ultimately be based on C++11 std::is_base_of):
183 
184 template< typename T1, typename T2 > struct UpCast {
185 private:
186  template< bool, typename U1, typename > struct C
187  { typedef U1 t; };
188 
189  template< typename U1, typename U2 > struct C< false, U1, U2 >
190  { typedef U2 t; };
191 
192  struct S { char c[2]; };
193 
194 #if defined _MSC_VER && _MSC_VER < 1800
195  static char f(T2 *, long);
196  static S f(T1 * const &, int);
197 #else
198  template< typename U > static char f(T2 *, U);
199  static S f(T1 *, int);
200 #endif
201 
202  struct H {
203  H(); // avoid C2514 "class has no constructors" from MSVC
204 #if defined _MSC_VER && _MSC_VER < 1800
205  operator T1 * const & () const;
206 #else
207  operator T1 * () const;
208 #endif
209  operator T2 * ();
210  };
211 
212 public:
213  typedef typename C< sizeof (f(H(), 0)) == 1, void *, void >::t t;
214 };
215 
216 template< typename T2 > struct UpCast< XInterface, T2 > {};
217 
218 }
220 
225 template< class interface_type >
226 class SAL_DLLPUBLIC_RTTI Reference : public BaseReference
227 {
233  inline static XInterface * SAL_CALL iquery( XInterface * pInterface );
240  inline static XInterface * SAL_CALL iquery_throw( XInterface * pInterface );
246  inline static interface_type * SAL_CALL iset_throw( interface_type * pInterface );
247 
259  static interface_type * castFromXInterface(XInterface * p) {
260  return static_cast< interface_type * >(static_cast< void * >(p));
261  }
262 
274  static XInterface * castToXInterface(interface_type * p) {
275  return static_cast< XInterface * >(static_cast< void * >(p));
276  }
277 
278 public:
280  // these are here to force memory de/allocation to sal lib.
281  static void * SAL_CALL operator new ( ::size_t nSize )
282  { return ::rtl_allocateMemory( nSize ); }
283  static void SAL_CALL operator delete ( void * pMem )
284  { ::rtl_freeMemory( pMem ); }
285  static void * SAL_CALL operator new ( ::size_t, void * pMem )
286  { return pMem; }
287  static void SAL_CALL operator delete ( void *, void * )
288  {}
290 
293  inline ~Reference() COVERITY_NOEXCEPT_FALSE;
294 
297  inline Reference();
298 
303  inline Reference( const Reference< interface_type > & rRef );
304 
305 #if defined LIBO_INTERNAL_ONLY
306 
310  inline Reference( Reference< interface_type > && rRef );
311 #endif
312 
321  template< class derived_type >
322  inline Reference(
323  const Reference< derived_type > & rRef,
324  typename detail::UpCast< interface_type, derived_type >::t = 0 );
325 
330  inline Reference( interface_type * pInterface );
331 
337  inline Reference( interface_type * pInterface, __sal_NoAcquire dummy);
345  inline SAL_DEPRECATED("use SAL_NO_ACQUIRE version") Reference( interface_type * pInterface, UnoReference_NoAcquire dummy );
346 
352  inline Reference( const BaseReference & rRef, UnoReference_Query dummy );
358  inline Reference( XInterface * pInterface, UnoReference_Query dummy);
364  inline Reference( const Any & rAny, UnoReference_Query dummy);
372  inline Reference( const BaseReference & rRef, UnoReference_QueryThrow dummy );
380  inline Reference( XInterface * pInterface, UnoReference_QueryThrow dummy );
388  inline Reference( const Any & rAny, UnoReference_QueryThrow dummy );
397  inline Reference( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy );
406  inline Reference( interface_type * pInterface, UnoReference_SetThrow dummy );
407 
412  SAL_CALL operator const Reference< XInterface > & () const
413  { return * reinterpret_cast< const Reference< XInterface > * >( this ); }
414 
419  interface_type * SAL_CALL operator -> () const {
420  assert(_pInterface != NULL);
421  return castFromXInterface(_pInterface);
422  }
423 
428  interface_type * SAL_CALL get() const
429  { return castFromXInterface(_pInterface); }
430 
433  inline void SAL_CALL clear();
434 
440  inline bool SAL_CALL set( const Reference< interface_type > & rRef );
446  inline bool SAL_CALL set( interface_type * pInterface );
447 
454  inline bool SAL_CALL set( interface_type * pInterface, __sal_NoAcquire dummy);
463  inline SAL_DEPRECATED("use SAL_NO_ACQUIRE version") bool SAL_CALL set( interface_type * pInterface, UnoReference_NoAcquire dummy);
464 
472  inline bool SAL_CALL set( XInterface * pInterface, UnoReference_Query dummy );
480  inline bool SAL_CALL set( const BaseReference & rRef, UnoReference_Query dummy);
481 
493  inline bool set( Any const & rAny, UnoReference_Query dummy );
494 
503  inline void SAL_CALL set( XInterface * pInterface, UnoReference_QueryThrow dummy );
512  inline void SAL_CALL set( const BaseReference & rRef, UnoReference_QueryThrow dummy );
513 
523  inline void set( Any const & rAny, UnoReference_QueryThrow dummy);
533  inline void SAL_CALL set( interface_type * pInterface, UnoReference_SetThrow dummy);
543  inline void SAL_CALL set( const Reference< interface_type > & rRef, UnoReference_SetThrow dummy);
544 
545 
552  inline Reference< interface_type > & SAL_CALL operator = ( interface_type * pInterface );
559  inline Reference< interface_type > & SAL_CALL operator = ( const Reference< interface_type > & rRef );
560 #if defined LIBO_INTERNAL_ONLY
561 
567  inline Reference< interface_type > & SAL_CALL operator = ( Reference< interface_type > && rRef );
568 #endif
569 
574  inline static SAL_WARN_UNUSED_RESULT Reference< interface_type > SAL_CALL query( const BaseReference & rRef );
580  inline static SAL_WARN_UNUSED_RESULT Reference< interface_type > SAL_CALL query( XInterface * pInterface );
581 };
582 
583 }
584 }
585 }
586 }
587 
588 #endif
589 
590 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
bool is() const
Checks if reference is null.
Definition: Reference.h:93
This enum value can be used for implicit interface query.
Definition: Reference.h:149
C++ class representing an IDL any.
Definition: Any.h:52
SAL_DLLPUBLIC void rtl_freeMemory(void *Ptr) SAL_THROW_EXTERN_C()
Free memory.
Definition: types.h:383
#define COVERITY_NOEXCEPT_FALSE
To markup destructors that coverity warns might throw exceptions which won&#39;t throw in practice...
Definition: types.h:361
UnoReference_QueryThrow
Enum defining UNO_QUERY_THROW for implicit interface query.
Definition: Reference.h:154
UnoReference_Query
Enum defining UNO_QUERY for implicit interface query.
Definition: Reference.h:145
__sal_NoAcquire
Definition: types.h:376
#define SAL_WARN_UNUSED_RESULT
Use this as markup for functions and methods whose return value must be checked.
Definition: types.h:307
C++ class representing an IDL meta type.
Definition: Type.h:54
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:383
bool operator!=(XInterface *pInterface) const
Unequality operator: compares two interfaces Checks if both references are null or refer to the same ...
Definition: Reference.hxx:420
UnoReference_SetThrow
Enum defining UNO_SET_THROW for throwing if attempts are made to assign a null interface.
Definition: Reference.h:165
Definition: Reference.h:167
#define SAL_DEPRECATED(message)
Use as follows: SAL_DEPRECATED("Don&#39;t use, it&#39;s evil.") void doit(int nPara);.
Definition: types.h:493
Template reference class for interface type derived from BaseReference.
Definition: unotype.hxx:39
SAL_DLLPUBLIC void * rtl_allocateMemory(sal_Size Bytes) SAL_THROW_EXTERN_C()
Allocate memory.
This enum value can be used for creating a reference granting a given interface, i.e.
Definition: Reference.h:52
This base class serves as a base class for all template reference classes and has been introduced due...
Definition: Reference.h:58
This enum value can be used for implicit interface query.
Definition: Reference.h:158
static XInterface * iquery(XInterface *pInterface, const Type &rType)
Queries given interface for type rType.
Definition: Reference.hxx:50
UnoReference_NoAcquire
Enum defining UNO_REF_NO_ACQUIRE for setting reference without acquiring a given interface.
Definition: Reference.h:47
bool operator<(const BaseReference &rRef) const
Needed by some STL containers.
Definition: Reference.hxx:401
static XInterface * iquery_throw(XInterface *pInterface, const Type &rType)
Queries given interface for type rType.
Definition: Reference.hxx:73
XInterface * _pInterface
the interface pointer
Definition: Reference.h:63