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 
25 #ifndef EXTENSIONS_OOOIMPROVEMENT_CONFIGURATIONHELPER_HXX
26 #define EXTENSIONS_OOOIMPROVEMENT_CONFIGURATIONHELPER_HXX
27 
28 #include <com/sun/star/uno/XInterface.hpp>
29 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
30 #include <com/sun/star/beans/PropertyValue.hpp>
31 #include <com/sun/star/container/XHierarchicalNameAccess.hpp>
32 #include <com/sun/star/util/XChangesBatch.hpp>
33 #include <rtl/ustring.hxx>
34 
35 
36 namespace oooimprovement
37 {
38     #ifdef css
39         #error css defined globally
40     #endif
41     #define css ::com::sun::star
42     // Copy from comphelper module, we cant use that directly from an extension
43     class MyConfigurationHelper
44     {
45         public:
46             //-----------------------------------------------
47             /** specify all possible modes, which can be used to open a configuration access.
48              *
49              *  @see    openConfig()
50              *  @see    readDirectKey()
51              *  @see    writeDirectKey()
52              */
53             enum EConfigurationModes
54             {
55                 /// opens configuration in read/write mode (without LAZY writing!)
56                 E_STANDARD = 0,
57                 /// configuration will be opened readonly
58                 E_READONLY = 1,
59                 /// all localized nodes will be interpreted as css::uno::XInterface instead of interpreting it as atomic value nodes
60                 E_ALL_LOCALES = 2,
61                 /// enable lazy writing
62                 E_LAZY_WRITE = 4
63             };
64 
65             //-----------------------------------------------
66             /** returns access to the specified configuration package.
67              *
68              *  This method should be used, if e.g. more then one request to the same
69              *  configuration package is needed. The configuration access can be cached
70              *  outside and used inbetween.
71              *
72              *  @param  xSMGR
73              *          the uno service manager, which should be used to create the
74              *          configuration access.
75              *
76              *  @param  sPackage
77              *          the name of the configuration package.
78              *          e.g. <ul>
79              *                  <li>org.openoffice.Office.Common</li>
80              *                  <li>org.openoffice.Office.Common/Menu</li>
81              *               </ul>
82              *
83              *  @param  eMode
84              *          specify the open mode for the returned configuration access.
85              *          It's interpreted as a flag field and can be any usefull combination
86              *          of values of EConfigurationModes.
87              *
88              *  @throw  css::uno::Any exceptions the underlying configuration can throw.
89              *          E.g. css::uno::Exception if the configuration could not be opened.
90              */
91             static css::uno::Reference< css::uno::XInterface> openConfig(
92                 const css::uno::Reference< css::lang::XMultiServiceFactory> xSMGR,
93                 const ::rtl::OUString& sPackage,
94                 sal_Int32 eMode);
95 
96             //-----------------------------------------------
97             /** reads the value of an existing(!) configuration key,
98              *  which is searched relative to the specified configuration access.
99              *
100              *  This method must be used in combination with openConfig().
101              *  The cached configuration access must be provided here ... and
102              *  all operations are made relativ to this access point.
103              *
104              *  @param  xCFG
105              *          the configuration root, where sRelPath should be interpreted.
106              *          as relativ path
107              *
108              *  @param  sRelPath
109              *          path relative to xCFG parameter.
110              *
111              *  @param  sKey
112              *          the configuration node, where we should read the value.
113              *
114              *  @return [css.uno.css::uno::Any]
115              *          the value of sKey.
116              *
117              *  @throw  css::uno::Any exceptions the underlying configuration can throw.
118              *          E.g. css::container::NoSuchElementException if the specified
119              *          key does not exists.
120              */
121             static css::uno::Any readRelativeKey(
122                 const css::uno::Reference< css::uno::XInterface> xCFG,
123                 const ::rtl::OUString& sRelPath,
124                 const ::rtl::OUString& sKey);
125 
126         //-----------------------------------------------
127         /** writes a new value for an existing(!) configuration key,
128          *  which is searched relative to the specified configuration access.
129          *
130          *  This method must be used in combination with openConfig().
131          *  The cached configuration access must be provided here ... and
132          *  all operations are made relativ to this access point.
133          *
134          *  @param  xCFG
135          *          the configuration root, where sRelPath should be interpreted.
136          *          as relativ path
137          *
138          *  @param  sRelPath
139          *          path relative to xCFG parameter.
140          *
141          *  @param  sKey
142          *          the configuration node, where we should write the new value.
143          *
144          *  @param  aValue
145          *          the new value for sKey.
146          *
147          *  @throw  css::uno::Any exceptions the underlying configuration can throw.
148          *          E.g. css::container::NoSuchElementException if the specified
149          *          key does not exists or css::uno::Exception if the provided configuration
150          *          access does not allow writing for this key.
151          */
152         static void writeRelativeKey(
153             const css::uno::Reference< css::uno::XInterface> xCFG,
154             const ::rtl::OUString& sRelPath,
155             const ::rtl::OUString& sKey,
156             const css::uno::Any& aValue);
157 
158         //-----------------------------------------------
159         /** commit all changes made on the specified configuration access.
160          *
161          *  This method must be used in combination with openConfig().
162          *  The cached configuration access must be provided here.
163          *
164          *  @param  xCFG
165          *          the configuration root, where changes should be commited.
166          *
167          *  @throw  css::uno::Any exceptions the underlying configuration can throw.
168          *          E.g. uno::Exception if the provided configuration
169          *          access does not allow writing for this set.
170          */
171         static void flush(const css::uno::Reference< css::uno::XInterface>& xCFG);
172 
173         //-----------------------------------------------
174         /** does the same then openConfig() & readRelativeKey() together.
175          *
176          * This method should be used for reading one key at one code place only.
177          * Because it opens the specified configuration package, reads the key and
178          * closes the configuration again.
179          *
180          * So its not very usefull to use this method for reading multiple keys at the same time.
181          * (Excepting these keys exists inside different configuration packages ...))
182          */
183         static css::uno::Any readDirectKey(
184             const css::uno::Reference< css::lang::XMultiServiceFactory> xSMGR,
185             const ::rtl::OUString& sPackage,
186             const ::rtl::OUString& sRelPath,
187             const ::rtl::OUString& sKey,
188             sal_Int32 eMode);
189 
190         //-----------------------------------------------
191         /** does the same then openConfig() / writeRelativeKey() & flush() together.
192          *
193          * This method should be used for writing one key at one code place only.
194          * Because it opens the specified configuration package, writes the key, flush
195          * all changes and closes the configuration again.
196          *
197          * So its not very usefull to use this method for writing multiple keys at the same time.
198          * (Excepting these keys exists inside different configuration packages ...))
199          */
200         static void writeDirectKey(
201             const css::uno::Reference< css::lang::XMultiServiceFactory> xSMGR,
202             const ::rtl::OUString& sPackage,
203             const ::rtl::OUString& sRelPath,
204             const ::rtl::OUString& sKey,
205             const css::uno::Any& aValue,
206             sal_Int32 eMode);
207     };
208     #undef css
209 }
210 #endif
211