1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef COMPHELPER_COMPONENTCONTEXT_HXX
25 #define COMPHELPER_COMPONENTCONTEXT_HXX
26 
27 #include <comphelper/comphelperdllapi.h>
28 
29 /** === begin UNO includes === **/
30 #include <com/sun/star/uno/XComponentContext.hpp>
31 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
32 /** === end UNO includes === **/
33 
34 //........................................................................
35 namespace comphelper
36 {
37 //........................................................................
38 
39 	//====================================================================
40 	//= ComponentContext
41 	//====================================================================
42     /** a helper class for working with a component context
43     */
44 	class COMPHELPER_DLLPUBLIC ComponentContext
45 	{
46     private:
47         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >        m_xContext;
48         ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiComponentFactory >  m_xORB;
49 
50     public:
51         /** constructs an instance
52             @param _rxContext
53                 the component context to manage
54             @throws ::com::sun::star::lang::NullPointerException
55                 if the given context, or its component factory, are <NULL/>
56         */
57         ComponentContext( const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >& _rxContext );
58 
59         /** constructs an instance
60             @param _rxLegacyFactory
61                 the legacy service factor to obtain the <type scope="com::sun::star::uno">XComponentContext</type> from
62             @throws ::com::sun::star::uno::RuntimeException
63                 if the given factory or does not have a DefaultContext property to obtain
64                 a component context
65             @throws ::com::sun::star::lang::NullPointerException
66                 if the given factory is <NULL/>, or provides a component context being <NULL/>, or provides
67                 a component context whose component factory is <NULL/>
68         */
69         ComponentContext( const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxLegacyFactory );
70 
71         /** returns the ->XComponentContext interface
72         */
73         inline ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >
getUNOContext() const74             getUNOContext() const { return m_xContext; }
75 
76         /** determines whether the context is not <NULL/>
77         */
is() const78         inline sal_Bool is() const
79         {
80             return m_xContext.is();
81         }
82 
83         /** creates a component using our component factory/context
84             @throws ::com::sun::star::uno::Exception
85             @return
86                 <TRUE/> if and only if the component could be successfully created
87         */
88         template < typename INTERFACE >
createComponent(const::rtl::OUString & _rServiceName,::com::sun::star::uno::Reference<INTERFACE> & _out_rxComponent) const89         bool createComponent( const ::rtl::OUString& _rServiceName, ::com::sun::star::uno::Reference< INTERFACE >& _out_rxComponent ) const
90         {
91             _out_rxComponent.clear();
92             _out_rxComponent = _out_rxComponent.query(
93                 m_xORB->createInstanceWithContext( _rServiceName, m_xContext )
94             );
95             return _out_rxComponent.is();
96         }
97 
98         /** creates a component using our component factory/context
99             @throws ::com::sun::star::uno::Exception
100             @return
101                 <TRUE/> if and only if the component could be successfully created
102         */
103         template < typename INTERFACE >
createComponent(const sal_Char * _pAsciiServiceName,::com::sun::star::uno::Reference<INTERFACE> & _out_rxComponent) const104         bool createComponent( const sal_Char* _pAsciiServiceName, ::com::sun::star::uno::Reference< INTERFACE >& _out_rxComponent ) const
105         {
106             return createComponent( ::rtl::OUString::createFromAscii( _pAsciiServiceName ), _out_rxComponent );
107         }
108 
109         /** creates a component using our component factory/context, passing creation arguments
110             @throws ::com::sun::star::uno::Exception
111             @return
112                 <TRUE/> if and only if the component could be successfully created
113         */
114         template < typename INTERFACE >
createComponentWithArguments(const::rtl::OUString & _rServiceName,const::com::sun::star::uno::Sequence<::com::sun::star::uno::Any> & _rArguments,::com::sun::star::uno::Reference<INTERFACE> & _out_rxComponent) const115         bool createComponentWithArguments( const ::rtl::OUString& _rServiceName, const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments, ::com::sun::star::uno::Reference< INTERFACE >& _out_rxComponent ) const
116         {
117             _out_rxComponent.clear();
118             _out_rxComponent = _out_rxComponent.query(
119                 m_xORB->createInstanceWithArgumentsAndContext( _rServiceName, _rArguments, m_xContext )
120             );
121             return _out_rxComponent.is();
122         }
123 
124         /** creates a component using our component factory/context, passing creation arguments
125             @throws ::com::sun::star::uno::Exception
126             @return
127                 <TRUE/> if and only if the component could be successfully created
128         */
129         template < typename INTERFACE >
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) const130         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
131         {
132             return createComponentWithArguments( ::rtl::OUString::createFromAscii( _pAsciiServiceName ), _rArguments, _out_rxComponent );
133         }
134 
135         /** creates a component using our component factory/context
136 
137             @throws ::com::sun::star::lang::ServiceNotRegisteredException
138                 if the given service is not registered
139             @throws Exception
140                 if an exception occurred during creating the component
141             @return
142                 the newly created component. Is never <NULL/>.
143         */
144         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > createComponent( const ::rtl::OUString& _rServiceName ) const;
145 
146         /** creates a component using our component factory/context
147 
148             @throws ::com::sun::star::lang::ServiceNotRegisteredException
149                 if the given service is not registered
150             @throws Exception
151                 if an exception occurred during creating the component
152             @return
153                 the newly created component. Is never <NULL/>.
154         */
createComponent(const sal_Char * _pAsciiServiceName) const155         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > createComponent( const sal_Char* _pAsciiServiceName ) const
156         {
157             return createComponent( ::rtl::OUString::createFromAscii( _pAsciiServiceName ) );
158         }
159 
160         /** creates a component using our component factory/context, passing creation arguments
161 
162             @throws ::com::sun::star::lang::ServiceNotRegisteredException
163                 if the given service is not registered
164             @throws Exception
165                 if an exception occurred during creating the component
166             @return
167                 the newly created component. Is never <NULL/>.
168         */
169         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > createComponentWithArguments(
170             const ::rtl::OUString& _rServiceName,
171             const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments
172         ) const;
173 
174         /** creates a component using our component factory/context, passing creation arguments
175 
176             @throws ::com::sun::star::lang::ServiceNotRegisteredException
177                 if the given service is not registered
178             @throws Exception
179                 if an exception occurred during creating the component
180             @return
181                 the newly created component. Is never <NULL/>.
182         */
createComponentWithArguments(const sal_Char * _pAsciiServiceName,const::com::sun::star::uno::Sequence<::com::sun::star::uno::Any> & _rArguments) const183         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > createComponentWithArguments(
184                 const sal_Char* _pAsciiServiceName,
185                 const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments
186             ) const
187         {
188             return createComponentWithArguments( ::rtl::OUString::createFromAscii( _pAsciiServiceName ), _rArguments );
189         }
190 
191         /** retrieves a singleton instance from the context
192 
193             Singletons are collected below the <code>/singletons</code> key in a component context,
194             so accessing them means retrieving the value under <code>/singletons/&lt;instance_name&gt;</code>.
195         */
196         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > getSingleton( const ::rtl::OUString& _rInstanceName ) const;
197 
198         /** retrieves a singleton instance from the context
199 
200             Singletons are collected below the <code>/singletons</code> key in a component context,
201             so accessing them means retrieving the value under <code>/singletons/&lt;instance_name&gt;</code>.
202         */
getSingleton(const sal_Char * _pAsciiInstanceName) const203         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > getSingleton( const sal_Char* _pAsciiInstanceName ) const
204         {
205             return getSingleton( ::rtl::OUString::createFromAscii( _pAsciiInstanceName ) );
206         }
207 
208         /** returns the ->XMultiServiceFactory interface of ->m_xORB, for passing to
209             older code which does not yet support ->XMultiComponentFactory
210             @throws ::com::sun::star::uno::RuntimeException
211                 if our our component factory does not support this interface
212         */
213         ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >
214             getLegacyServiceFactory() const;
215 
216         /** retrieves a value from our component context
217             @param _rName
218                 the name of the value to retrieve
219             @return
220                 the context value with the given name
221             @seealso XComponentContext::getValueByName
222             @seealso getContextValueByAsciiName
223         */
224         ::com::sun::star::uno::Any
225                 getContextValueByName( const ::rtl::OUString& _rName ) const;
226 
227         /** retrieves a value from our component context, specified by 8-bit ASCII string
228             @param _rName
229                 the name of the value to retrieve, as ASCII character string
230             @return
231                 the context value with the given name
232             @seealso XComponentContext::getValueByName
233             @seealso getContextValueByName
234         */
235         inline ::com::sun::star::uno::Any
getContextValueByAsciiName(const sal_Char * _pAsciiName) const236                 getContextValueByAsciiName( const sal_Char* _pAsciiName ) const
237         {
238             return getContextValueByName( ::rtl::OUString::createFromAscii( _pAsciiName ) );
239         }
240 
241 	};
242 
243 //........................................................................
244 } // namespace comphelper
245 //........................................................................
246 
247 #endif // COMPHELPER_COMPONENTCONTEXT_HXX
248 
249