offapi/com/sun/star/ucb/HierarchyDataSource.idl

   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 #ifndef __com_sun_star_ucb_HierarchyDataSource_idl__
  20 #define __com_sun_star_ucb_HierarchyDataSource_idl__
  21
  22 #include <com/sun/star/lang/XMultiServiceFactory.idl>
  23 #include <com/sun/star/lang/XComponent.idl>
  24
  25
  26 module com { module sun { module star { module ucb {
  27
  28 /** manages one or more complete sets of hierarchy data and serves as a factory
  29     for objects that provide access to a subset of the data.
  30
  31     <p><b>Note:</b> This is an abstract service. This means, that there should
  32     never be implementations that can be instantiated using the service name
  33     <code>com.sun.star.ucb.HierarchyDataSource</code>. Each implementation must
  34     provide its own service name that can be used to create instances of that
  35     service implementation. Important for those service specifications is also
  36     to specify which of the optional parts are supported by the implementation.
  37 */
  38 published service HierarchyDataSource
  39 {
  40     /** allows creating access objects for specific views such as subsets and
  41         fragments of the hierarchy data.
  42
  43         <p>The parameter <var>aServiceSpecifier</var> passed to
  44         com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
  45         supports at least the service specifier
  46         <code>"com.sun.star.ucb.HierarchyDataReadAccess"</code>, which will
  47         create a <b>read-only view</b> to the data. The object that is created
  48         implements the service HierarchyDataReadAccess.
  49
  50         <p><b>Optionally</b> the factory may support <b>writable views</b>. A
  51         writable view is requested by passing the service specifier
  52         <code>"com.sun.star.ucb.HierarchyDataReadWriteAccess"</code> to
  53         com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
  54         The object that is created implements the service
  55         HierarchyDataReadWriteAccess.
  56
  57         <p>The arguments passed to
  58         com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
  59         in parameter <var>aArguments</var> specify the view of the data that
  60         should be created. That is, they determine the subset of elements that
  61         can be accessed starting from the returned object. Each element of the
  62         argument sequence should be a
  63         com::sun::star::beans::PropertyValue, so that the
  64         parameters can be identified by name rather than by position.
  65
  66         <p>With both of the standard service specifiers above, an implementation
  67         must accept a property named <code>nodepath</code> of type
  68         `string`. This property must contain the absolute path to an
  69         element of the data. The view that is selected consists of the named
  70         element and all its descendants. A path consists of segments that are
  71         separated by a single slash ("/"). There is neither a leading nor a
  72         trailing slash allowed. The <b>root</b> of the hierarchy data always
  73         has an empty path. Refer to HierarchyDataReadAccess for
  74         more information on hierarchical names.
  75
  76         <p>Other arguments can be used to control the behavior of the view.
  77         These are different for different implementations. Whether and how they
  78         are used may also depend on the configuration store and configuration
  79         that were selected when the provider was created.
  80
  81         <p>An implementation must ignore unknown arguments.
  82
  83         <p>The implementation of
  84         com::sun::star::lang::XMultiServiceFactory::createInstance()
  85         must behave exactly as if
  86         com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
  87         were called passing one single property named <code>nodepath</code>
  88         where the property value is an empty string. Thus it always creates a
  89         view to the root of the hierarchy data.
  90      */
  91     interface com::sun::star::lang::XMultiServiceFactory;
  92
  93     /** allows controlling or observing the lifetime of the hierarchy data
  94         source and its views.
  95      */
  96     interface com::sun::star::lang::XComponent;
  97 };
  98
  99
 100 }; }; }; };
 101
 102 #endif
 103
 104 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */