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