include/comphelper/componentcontext.hxx

   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 #ifndef COMPHELPER_COMPONENTCONTEXT_HXX
  21 #define COMPHELPER_COMPONENTCONTEXT_HXX
  22
  23 #include <comphelper/comphelperdllapi.h>
  24
  25 #include <com/sun/star/uno/XComponentContext.hpp>
  26 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  27
  28 //........................................................................
  29 namespace comphelper
  30 {
  31 //........................................................................
  32
  33     //====================================================================
  34     //= ComponentContext
  35     //====================================================================
  36     /** a helper class for working with a component context
  37     */
  38     class COMPHELPER_DLLPUBLIC ComponentContext
  39     {
  40     private:
  41         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >        m_xContext;
  42         ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiComponentFactory >  m_xORB;
  43
  44     public:
  45         /** constructs an instance
  46             @param _rxContext
  47                 the component context to manage
  48             @throws ::com::sun::star::lang::NullPointerException
  49                 if the given context, or its component factory, are <NULL/>
  50         */
  51         ComponentContext( const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >& _rxContext );
  52
  53         /** constructs an instance
  54             @param _rxLegacyFactory
  55                 the legacy service factor to obtain the <type scope="com::sun::star::uno">XComponentContext</type> from
  56             @throws ::com::sun::star::uno::RuntimeException
  57                 if the given factory or does not have a DefaultContext property to obtain
  58                 a component context
  59             @throws ::com::sun::star::lang::NullPointerException
  60                 if the given factory is <NULL/>, or provides a component context being <NULL/>, or provides
  61                 a component context whose component factory is <NULL/>
  62         */
  63         ComponentContext( const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxLegacyFactory );
  64
  65         /** returns the ->XComponentContext interface
  66         */
  67         inline ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >
  68             getUNOContext() const { return m_xContext; }
  69
  70         /** determines whether the context is not <NULL/>
  71         */
  72         inline sal_Bool is() const
  73         {
  74             return m_xContext.is();
  75         }
  76
  77         /** creates a component using our component factory/context
  78             @throws ::com::sun::star::uno::Exception
  79             @return
  80                 <TRUE/> if and only if the component could be successfully created
  81         */
  82         template < typename INTERFACE >
  83         bool createComponent( const OUString& _rServiceName, ::com::sun::star::uno::Reference< INTERFACE >& _out_rxComponent ) const
  84         {
  85             _out_rxComponent.clear();
  86             _out_rxComponent = _out_rxComponent.query(
  87                 m_xORB->createInstanceWithContext( _rServiceName, m_xContext )
  88             );
  89             return _out_rxComponent.is();
  90         }
  91
  92         /** creates a component using our component factory/context
  93             @throws ::com::sun::star::uno::Exception
  94             @return
  95                 <TRUE/> if and only if the component could be successfully created
  96         */
  97         template < typename INTERFACE >
  98         bool createComponent( const sal_Char* _pAsciiServiceName, ::com::sun::star::uno::Reference< INTERFACE >& _out_rxComponent ) const
  99         {
 100             return createComponent( OUString::createFromAscii( _pAsciiServiceName ), _out_rxComponent );
 101         }
 102
 103         /** creates a component using our component factory/context, passing creation arguments
 104             @throws ::com::sun::star::uno::Exception
 105             @return
 106                 <TRUE/> if and only if the component could be successfully created
 107         */
 108         template < typename INTERFACE >
 109         bool createComponentWithArguments( const OUString& _rServiceName, const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments, ::com::sun::star::uno::Reference< INTERFACE >& _out_rxComponent ) const
 110         {
 111             _out_rxComponent.clear();
 112             _out_rxComponent = _out_rxComponent.query(
 113                 m_xORB->createInstanceWithArgumentsAndContext( _rServiceName, _rArguments, m_xContext )
 114             );
 115             return _out_rxComponent.is();
 116         }
 117
 118         /** creates a component using our component factory/context, passing creation arguments
 119             @throws ::com::sun::star::uno::Exception
 120             @return
 121                 <TRUE/> if and only if the component could be successfully created
 122         */
 123         template < typename INTERFACE >
 124         bool createComponentWithArguments( const sal_Char* _pAsciiServiceName, const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments, ::com::sun::star::uno::Reference< INTERFACE >& _out_rxComponent ) const
 125         {
 126             return createComponentWithArguments( OUString::createFromAscii( _pAsciiServiceName ), _rArguments, _out_rxComponent );
 127         }
 128
 129         /** creates a component using our component factory/context
 130
 131             @throws ::com::sun::star::lang::ServiceNotRegisteredException
 132                 if the given service is not registered
 133             @throws Exception
 134                 if an exception occurred during creating the component
 135             @return
 136                 the newly created component. Is never <NULL/>.
 137         */
 138         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > createComponent( const OUString& _rServiceName ) const;
 139
 140         /** creates a component using our component factory/context
 141
 142             @throws ::com::sun::star::lang::ServiceNotRegisteredException
 143                 if the given service is not registered
 144             @throws Exception
 145                 if an exception occurred during creating the component
 146             @return
 147                 the newly created component. Is never <NULL/>.
 148         */
 149         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > createComponent( const sal_Char* _pAsciiServiceName ) const
 150         {
 151             return createComponent( OUString::createFromAscii( _pAsciiServiceName ) );
 152         }
 153
 154         /** creates a component using our component factory/context, passing creation arguments
 155
 156             @throws ::com::sun::star::lang::ServiceNotRegisteredException
 157                 if the given service is not registered
 158             @throws Exception
 159                 if an exception occurred during creating the component
 160             @return
 161                 the newly created component. Is never <NULL/>.
 162         */
 163         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > createComponentWithArguments(
 164             const OUString& _rServiceName,
 165             const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments
 166         ) const;
 167
 168         /** creates a component using our component factory/context, passing creation arguments
 169
 170             @throws ::com::sun::star::lang::ServiceNotRegisteredException
 171                 if the given service is not registered
 172             @throws Exception
 173                 if an exception occurred during creating the component
 174             @return
 175                 the newly created component. Is never <NULL/>.
 176         */
 177         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > createComponentWithArguments(
 178                 const sal_Char* _pAsciiServiceName,
 179                 const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments
 180             ) const
 181         {
 182             return createComponentWithArguments( OUString::createFromAscii( _pAsciiServiceName ), _rArguments );
 183         }
 184
 185         /** retrieves a singleton instance from the context
 186
 187             Singletons are collected below the <code>/singletons</code> key in a component context,
 188             so accessing them means retrieving the value under <code>/singletons/&lt;instance_name&gt;</code>.
 189         */
 190         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > getSingleton( const OUString& _rInstanceName ) const;
 191
 192         /** retrieves a singleton instance from the context
 193
 194             Singletons are collected below the <code>/singletons</code> key in a component context,
 195             so accessing them means retrieving the value under <code>/singletons/&lt;instance_name&gt;</code>.
 196         */
 197         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > getSingleton( const sal_Char* _pAsciiInstanceName ) const
 198         {
 199             return getSingleton( OUString::createFromAscii( _pAsciiInstanceName ) );
 200         }
 201
 202         /** returns the ->XMultiServiceFactory interface of ->m_xORB, for passing to
 203             older code which does not yet support ->XMultiComponentFactory
 204             @throws ::com::sun::star::uno::RuntimeException
 205                 if our our component factory does not support this interface
 206         */
 207         ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >
 208             getLegacyServiceFactory() const;
 209
 210         /** retrieves a value from our component context
 211             @param _rName
 212                 the name of the value to retrieve
 213             @return
 214                 the context value with the given name
 215             @seealso XComponentContext::getValueByName
 216             @seealso getContextValueByAsciiName
 217         */
 218         ::com::sun::star::uno::Any
 219                 getContextValueByName( const OUString& _rName ) const;
 220
 221         /** retrieves a value from our component context, specified by 8-bit ASCII string
 222             @param _rName
 223                 the name of the value to retrieve, as ASCII character string
 224             @return
 225                 the context value with the given name
 226             @seealso XComponentContext::getValueByName
 227             @seealso getContextValueByName
 228         */
 229         inline ::com::sun::star::uno::Any
 230                 getContextValueByAsciiName( const sal_Char* _pAsciiName ) const
 231         {
 232             return getContextValueByName( OUString::createFromAscii( _pAsciiName ) );
 233         }
 234
 235     };
 236
 237 //........................................................................
 238 } // namespace comphelper
 239 //........................................................................
 240
 241 #endif // COMPHELPER_COMPONENTCONTEXT_HXX
 242
 243 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */