| /************************************************************** |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| #ifndef __com_sun_star_ucb_HierarchyDataSource_idl__ |
| #define __com_sun_star_ucb_HierarchyDataSource_idl__ |
| |
| #ifndef __com_sun_star_lang_XMultiServiceFactory_idl__ |
| #include <com/sun/star/lang/XMultiServiceFactory.idl> |
| #endif |
| #ifndef __com_sun_star_lang_XComponent_idl__ |
| #include <com/sun/star/lang/XComponent.idl> |
| #endif |
| |
| //============================================================================= |
| |
| module com { module sun { module star { module ucb { |
| |
| //============================================================================= |
| /** manages one or more complete sets of hierarchy data and serves as a factory |
| for objects that provide access to a subset of the data. |
| |
| <p><b>Note:</b> This is an abstract service. This means, that there should |
| never be implementations that can be instanciated using the service name |
| <code>com.sun.star.ucb.HierarchyDataSource</code>. Each implementation must |
| provide its own service name that can be used to create instances of that |
| service implementation. Important for those service specifications is also |
| to specify which of the optional parts are supported by the implementation. |
| */ |
| published service HierarchyDataSource |
| { |
| //------------------------------------------------------------------------- |
| /** allows creating access objects for specific views such as subsets and |
| fragments of the hierrachy data. |
| |
| <p>The parameter <var>aServiceSpecifier</var> passed to |
| <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member> |
| supports at least the service specifier |
| <code>"com.sun.star.ucb.HierarchyDataReadAccess"</code>, which will |
| create a <b>read-only view</b> to the data. The object that is created |
| implements the service <type>HierarchyDataReadAccess</type>. |
| |
| <p><b>Optionally</b> the factory may support <b>writable views</b>. A |
| writable view is requested by passing the service specifier |
| <code>"com.sun.star.ucb.HierarchyDataReadWriteAccess"</code> to |
| <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member> |
| The object that is created implements the service |
| <type>HierarchyDataReadWriteAccess</type>. |
| |
| <p>The arguments passed to |
| <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member> |
| in parameter <var>aArguments</var> specify the view of the data that |
| should be created. That is, they determine the subset of elements that |
| can be accessed starting from the returned object. Each element of the |
| argument sequence should be a |
| <type scope="com::sun::star::beans">PropertyValue</type>, so that the |
| parameters can be identified by name rather than by position. |
| |
| <p>With both of the standard service specifiers above, an implementation |
| must accept a property named <code>nodepath</code> of type |
| <atom>string</atom>. This property must contain the absolute path to an |
| element of the data. The view that is selected consists of the named |
| element and all its decendants. A path consists of segments that are |
| separated by a single slash ('/'). There is neither a leading nor a |
| trailing slash allowed. The <b>root</b> of the hierarchy data always |
| has an empty path. Refer to <type>HierarchyDataReadAccess</type> for |
| more informtion on hierarchical names. |
| |
| <p>Other arguments can be used to control the behavior of the view. |
| These are different for different implementations. Whether and how they |
| are used may also depend on the configuration store and configuration |
| that were selected when the provider was created. |
| |
| <p>An implementation must ignore unknown arguments. |
| |
| <p>The implementation of |
| <member scope="com::sun::star::lang">XMultiServiceFactory::createInstance</member> |
| must behave exactly as if |
| <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member> |
| were called passing one single property named <code>nodepath</code> |
| where the property value is an empty string. Thus it always creates a |
| view to the root of the hierarchy data. |
| */ |
| interface com::sun::star::lang::XMultiServiceFactory; |
| |
| //------------------------------------------------------------------------- |
| /** allows controlling or observing the lifetime of the hierarchy data |
| source and its views. |
| */ |
| interface com::sun::star::lang::XComponent; |
| }; |
| |
| //============================================================================= |
| |
| }; }; }; }; |
| |
| #endif |