offapi/com/sun/star/ucb/HierarchyDataReadAccess.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_HierarchyDataReadAccess_idl__
  20 #define __com_sun_star_ucb_HierarchyDataReadAccess_idl__
  21
  22 #include <com/sun/star/container/XNameAccess.idl>
  23 #include <com/sun/star/container/XHierarchicalNameAccess.idl>
  24 #include <com/sun/star/util/XChangesNotifier.idl>
  25 #include <com/sun/star/lang/XComponent.idl>
  26
  27
  28 module com { module sun { module star { module ucb {
  29
  30 /** provides read access to a fragment of the hierarchy data.
  31
  32     <p>A hierarchy data source provides access to a tree of hierarchy data
  33     nodes. Each hierarchy data node, except the root node, has a parent that
  34     is a hierarchy data node too. A hierarchy data node has a name.
  35
  36     <p>Each hierarchy data node has three data members:
  37
  38     <ul>
  39     <li>"Title", which is of type `string`. It contains a title
  40     for the node. This value must not be empty.
  41     <li>"TargetURL", which is of type `string`</li> It may contain
  42     any URL, which will be treated as the target of a hierarchy link.
  43     <li>"Children", which is of type HierarchyDataReadAccess or
  44     of type HierarchyDataReadWriteAccess</li>, depending on the
  45     type of the node. This member provides access to the children of a node.
  46     </ul>
  47 */
  48 published service HierarchyDataReadAccess
  49 {
  50     /** gives access to the data members of a hierarchy data node.
  51
  52         <p>Examples:
  53         <ul>
  54         <li><code>getByName( "Title" )</code> will return an `any`
  55         containing a string containing the title of the node.
  56         </li>
  57         <li><code>getByName( "Children" )</code> will return an `any`
  58         containing an implementation of service
  59         HierarchyDataReadAccess, if it was called on a read-only
  60         node. It will return an implementation of service
  61         HierarchyDataReadWriteAccess if it was called on a
  62         writable node.
  63         </li>
  64         </ul>
  65      */
  66     interface com::sun::star::container::XNameAccess;
  67
  68     /** gives access to the data members of a hierarchy data node as well
  69         as to any child nodes or to the data members of child nodes using a
  70         hierarchical name.
  71
  72         <p>A hierarchical name consists of segments that are separated by a
  73         single slash ("/"). There is neither a leading nor a trailing slash
  74         allowed.
  75
  76         <ul>
  77         <li>
  78         path = segment ( '/' segment )*
  79         </li>
  80         <li>
  81         segment = '[' quoted-string ']'
  82         </li>
  83         <li>
  84         quoted-string = "'" escaped-string "'"
  85         </li>
  86         <li>
  87         escaped-string = escaped according to XML attribute naming conventions
  88         </li>
  89         </ul>
  90
  91         <p>Examples:
  92         <ul>
  93         <li>
  94         <code>getByHierarchicalName( "Title" )</code> will return an
  95         `any` containing a string containing the title of the node
  96         itself.
  97         </li>
  98         <li>
  99         <code>getByHierarchicalName( "Children/['subnode1']" )</code> will give
 100         access to the child node named "subnode1" of the node. It will return
 101         an `any` containing an implementation of service
 102         HierarchyDataReadAccess, if it was called on a read-only
 103         node. It will return an implementation of service
 104         HierarchyDataReadWriteAccess if it was called on a
 105         writable node.
 106         </li>
 107         <li>
 108         <code>getByHierarchicalName( "Children/['subnode2']/TargetURL" )</code>
 109         will give direct access to the "TargetURL" data member of the child node
 110         named "subnode2" of the node. It will return an `any`
 111         containing a `string` containing the target URL of the node.
 112         </li>
 113         <li>
 114         <code>getByHierarchicalName( "Children/['subnode3']/Children" )</code>
 115         will give direct access to the "Children" data member of the child node
 116         named "subnode3" of the node. It will return an `any`
 117         containing an implementation of service
 118         HierarchyDataReadAccess, if it was called on a read-only
 119         node. It will return an implementation of service
 120         HierarchyDataReadWriteAccess if it was called on a
 121         writable node.
 122         </li>
 123         </ul>
 124      */
 125     interface com::sun::star::container::XHierarchicalNameAccess;
 126
 127     /** allows registering listeners that observe the hierarchy data source.
 128
 129         <p>A client can register an
 130         com::sun::star::util::XChangesListener, which will
 131         receive notifications for any changes within the hierarchy (fragment)
 132         this object represents.
 133
 134         <p>An implementation should collect as many changes as possible into a
 135         single com::sun::star::util::ChangesEvent.
 136     */
 137     interface com::sun::star::util::XChangesNotifier;
 138
 139     /** allows controlling or observing the lifetime of the hierarchy data
 140         access object.
 141      */
 142     interface com::sun::star::lang::XComponent;
 143 };
 144
 145
 146 }; }; }; };
 147
 148 #endif
 149
 150 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */