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
55 enum UnoReference_NoAcquire
56{
60 UNO_REF_NO_ACQUIRE
61};
62
66 class BaseReference
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
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
153 enum UnoReference_Query
154{
157 UNO_QUERY
158};
162 enum UnoReference_QueryThrow
163{
166 UNO_QUERY_THROW
167};
173 enum UnoReference_SetThrow
174{
175 UNO_SET_THROW
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
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
338 Reference( const Reference< interface_type > & rRef, UnoReference_QueryThrow dummy ) = delete;
339#endif
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
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
550 inline Reference< interface_type > & operator = ( Reference< interface_type > && rRef ) noexcept;
551#endif
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
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: */
config.h
SAL_DEPRECATED
#define SAL_DEPRECATED(message)
Use as follows: SAL_DEPRECATED("Don't use, it's evil.") void doit(int nPara);.
Definition: types.h:492
__sal_NoAcquire
__sal_NoAcquire
Definition: types.h:371
COVERITY_NOEXCEPT_FALSE
#define COVERITY_NOEXCEPT_FALSE
To markup destructors that coverity warns might throw exceptions which won't throw in practice,...
Definition: types.h:367
SAL_WARN_UNUSED_RESULT
#define SAL_WARN_UNUSED_RESULT
Use this as markup for functions and methods whose return value must be used.
Definition: types.h:288
alloc.h
rtl_freeMemory
SAL_DLLPUBLIC void rtl_freeMemory(void *Ptr) SAL_THROW_EXTERN_C()
Free memory.
rtl_allocateMemory
SAL_DLLPUBLIC void * rtl_allocateMemory(sal_Size Bytes) SAL_THROW_EXTERN_C()
Allocate memory.
com
Definition: types.h:377
com::sun::star::uno::UnoReference_NoAcquire
UnoReference_NoAcquire
Enum defining UNO_REF_NO_ACQUIRE for setting reference without acquiring a given interface.
Definition: Reference.h:56
com::sun::star::uno::UNO_REF_NO_ACQUIRE
@ UNO_REF_NO_ACQUIRE
This enum value can be used for creating a reference granting a given interface, i....
Definition: Reference.h:60
com::sun::star::uno::UnoReference_QueryThrow
UnoReference_QueryThrow
Enum defining UNO_QUERY_THROW for implicit interface query.
Definition: Reference.h:163
com::sun::star::uno::UNO_QUERY_THROW
@ UNO_QUERY_THROW
This enum value can be used for implicit interface query.
Definition: Reference.h:166
com::sun::star::uno::UnoReference_Query
UnoReference_Query
Enum defining UNO_QUERY for implicit interface query.
Definition: Reference.h:154
com::sun::star::uno::UNO_QUERY
@ UNO_QUERY
This enum value can be used for implicit interface query.
Definition: Reference.h:157
com::sun::star::uno::UnoReference_SetThrow
UnoReference_SetThrow
Enum defining UNO_SET_THROW for throwing if attempts are made to assign a null interface.
Definition: Reference.h:174
com::sun::star::uno::UNO_SET_THROW
@ UNO_SET_THROW
Definition: Reference.h:175
com::sun::star::uno::Reference
Template reference class for interface type derived from BaseReference.
Definition: Reference.h:184
com::sun::star::uno::Reference::get
interface_type * get() const
Gets interface pointer.
Definition: Reference.h:405
com::sun::star::uno::Any
C++ class representing an IDL any.
Definition: Any.h:58
com::sun::star::uno::BaseReference
This base class serves as a base class for all template reference classes and has been introduced due...
Definition: Reference.h:67
com::sun::star::uno::BaseReference::operator<
bool operator<(const BaseReference &rRef) const
Needed by some STL containers.
Definition: Reference.hxx:436
com::sun::star::uno::BaseReference::iquery
static XInterface * iquery(XInterface *pInterface, const Type &rType)
Queries given interface for type rType.
Definition: Reference.hxx:54
com::sun::star::uno::BaseReference::operator!=
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
com::sun::star::uno::BaseReference::get
XInterface * get() const
Gets interface pointer.
Definition: Reference.h:94
com::sun::star::uno::BaseReference::_pInterface
XInterface * _pInterface
the interface pointer
Definition: Reference.h:71
com::sun::star::uno::BaseReference::iquery_throw
static XInterface * iquery_throw(XInterface *pInterface, const Type &rType)
Queries given interface for type rType.
Definition: Reference.hxx:77
com::sun::star::uno::BaseReference::is
bool is() const
Checks if reference is null.
Definition: Reference.h:101
com::sun::star::uno::BaseReference::operator==
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
com::sun::star::uno::Type
C++ class representing an IDL meta type.
Definition: Type.h:59