offapi/com/sun/star/embed/XRelationshipAccess.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XRelationshipAccess.idl,v $
  10  * $Revision: 1.3 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_embed_XRelationshipAccess_idl__
  31 #define __com_sun_star_embed_XRelationshipAccess_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_beans_StringPair_idl__
  38 #include <com/sun/star/beans/StringPair.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  42 #include <com/sun/star/container/NoSuchElementException.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_container_ElementExistException_idl__
  46 #include <com/sun/star/container/ElementExistException.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_io_IOException_idl__
  50 #include <com/sun/star/io/IOException.idl>
  51 #endif
  52
  53 //============================================================================
  54
  55  module com {  module sun {  module star {  module embed {
  56
  57 //============================================================================
  58 /** This interface allows to ge access to relationship data.
  59
  60     <p>
  61     The relationship data is organized as a set of entries. Each of entry
  62     is represented by a set of tags, where each tag has unique for this entry
  63     name and a string value. An entry must contain at least one tag named
  64     "ID", the value of this tag must be uniqued for the whole set of entries,
  65     this tag is used as a uniqued identified of an entry.
  66     </p>
  67  */
  68 interface XRelationshipAccess : ::com::sun::star::uno::XInterface
  69 {
  70     // -----------------------------------------------------------------------
  71     /** allows to detect whether there is an entry with specified value of
  72         "ID" tag.
  73
  74         @param sID
  75             the value of "ID" tag
  76
  77         @throws ::com::sun::star::io::IOException
  78             in case there is a problem reading the relations info
  79      */
  80     boolean hasByID( [in] string sID )
  81         raises( ::com::sun::star::io::IOException );
  82
  83     // -----------------------------------------------------------------------
  84     /** retrieves the value of "Target" tag from the entry with specified "ID"
  85         tag.
  86
  87         <p>
  88         If the entry has no "Target" tag an empty string is returned.
  89         </p>
  90
  91         @param sID
  92             the value of "ID" tag
  93
  94         @throws ::com::sun::star::container::NoSuchElementException
  95             in case there is no entry with specified tag
  96
  97         @throws ::com::sun::star::io::IOException
  98             in case there is a problem reading the relations info
  99      */
 100     string getTargetByID( [in] string sID )
 101         raises( ::com::sun::star::container::NoSuchElementException,
 102                 ::com::sun::star::io::IOException );
 103
 104     // -----------------------------------------------------------------------
 105     /** retrieves the value of "Type" tag from the entry with specified "ID"
 106         tag.
 107
 108         <p>
 109         If the entry has no "Type" tag an empty string is returned.
 110         </p>
 111
 112         @param sID
 113             the value of "ID" tag
 114
 115         @throws ::com::sun::star::container::NoSuchElementException
 116             in case there is no entry with specified tag
 117
 118         @throws ::com::sun::star::io::IOException
 119             in case there is a problem reading the relations info
 120      */
 121     string getTypeByID( [in] string sID )
 122         raises( ::com::sun::star::container::NoSuchElementException,
 123                 ::com::sun::star::io::IOException );
 124
 125     // -----------------------------------------------------------------------
 126     /** retrieves the sequence containing all the tags from the entry with
 127         specified value of "ID" tag.
 128
 129         @param sID
 130             the value of "ID" tag
 131
 132         @returns
 133             sequence, each element of the sequence represents tag,
 134             <type scope="::com::sun::star::beans">StringPair</type>::First
 135             represents the tag name and
 136             <type scope="::com::sun::star::beans">StringPair</type>::Second
 137             represents the tag value
 138
 139         @throws ::com::sun::star::container::NoSuchElementException
 140             in case there is no entry with specified tag
 141
 142         @throws ::com::sun::star::io::IOException
 143             in case there is a problem reading the relations info
 144      */
 145     sequence< ::com::sun::star::beans::StringPair >
 146             getRelationshipByID( [in] string sID )
 147         raises( ::com::sun::star::container::NoSuchElementException,
 148                 ::com::sun::star::io::IOException );
 149
 150     // -----------------------------------------------------------------------
 151     /** retrieves the sequence containing all the entries which "Type" tag
 152         takes the specified value.
 153
 154         @param sType
 155             specified value of "Type" tag, the parameter can contain an empty
 156             string, in this case all the entries that have empty "Type" tag or
 157             no such tag at all are returned
 158
 159         @returns
 160             sequence of entries, each entry is represented by sequence,
 161             each element of the sequence represents tag,
 162             <type scope="::com::sun::star::beans">StringPair</type>::First
 163             represents the tag name and
 164             <type scope="::com::sun::star::beans">StringPair</type>::Second
 165             represents the tag value.
 166             The sequence should contain the "ID" tag.
 167
 168         @throws ::com::sun::star::io::IOException
 169             in case there is a problem reading the relations info
 170      */
 171     sequence< sequence< ::com::sun::star::beans::StringPair > >
 172             getRelationshipsByType( [in] string sType )
 173         raises( ::com::sun::star::io::IOException );
 174
 175     // -----------------------------------------------------------------------
 176     /** retrieves the sequence containing all the entries controlled by the
 177         object.
 178
 179         @returns
 180             sequence of entries, each entry is represented by sequence,
 181             each element of the sequence represents tag,
 182             <type scope="::com::sun::star::beans">StringPair</type>::First
 183             represents the tag name and
 184             <type scope="::com::sun::star::beans">StringPair</type>::Second
 185             represents the tag value
 186
 187         @throws ::com::sun::star::io::IOException
 188             in case there is a problem reading the relations info
 189      */
 190     sequence< sequence< ::com::sun::star::beans::StringPair > >
 191             getAllRelationships()
 192         raises( ::com::sun::star::io::IOException );
 193
 194     // -----------------------------------------------------------------------
 195     /** allows to insert an entry.
 196
 197         @param sID
 198             the value of "ID" tag
 199
 200         @param aEntry
 201             a sequence, each element of the sequence represents tag,
 202             <type scope="::com::sun::star::beans">StringPair</type>::First
 203             represents the tag name and
 204             <type scope="::com::sun::star::beans">StringPair</type>::Second
 205             represents the tag value.
 206             May not contain "ID" tag, that is already specified in previous
 207             parameter.
 208
 209         @param bReplace
 210             specifies whether the replacement of existing entry is allowed
 211
 212         @throws ::com::sun::star::io::IOException
 213             in case there is a problem reading/writing the relations info
 214
 215         @throws ::com::sun::star::container::ElementExistException
 216             in case an element with the specified "ID" tag exists already, and
 217             no replacement is allowed
 218      */
 219     void insertRelationshipByID(
 220             [in] string sID,
 221             [in] sequence< ::com::sun::star::beans::StringPair > aEntry,
 222             [in] boolean bReplace )
 223         raises( ::com::sun::star::container::ElementExistException,
 224                 ::com::sun::star::io::IOException );
 225
 226     // -----------------------------------------------------------------------
 227     /** allows to remove an entry.
 228
 229         @param sID
 230             the value of "ID" tag
 231
 232         @throws ::com::sun::star::container::NoSuchElementException
 233             in case there is no entry with specified tag
 234
 235         @throws ::com::sun::star::io::IOException
 236             in case there is a problem reading/writing the relations info
 237      */
 238     void removeRelationshipByID( [in] string sID )
 239         raises( ::com::sun::star::container::NoSuchElementException,
 240                 ::com::sun::star::io::IOException );
 241
 242     // -----------------------------------------------------------------------
 243     /** allows to insert a set of entries
 244
 245         @param aEntries
 246             sequence of entries, each entry is represented by sequence,
 247             each element of the sequence represents tag,
 248             <type scope="::com::sun::star::beans">StringPair</type>::First
 249             represents the tag name and
 250             <type scope="::com::sun::star::beans">StringPair</type>::Second
 251             represents the tag value.
 252             Each entry must contain "ID" tag.
 253
 254         @param bReplace
 255             specifies whether the replacement of existing entry is allowed
 256
 257         @throws ::com::sun::star::container::ElementExistException
 258             in case an element with the provided "ID" tag exists already, and
 259             no replacement is allowed
 260
 261         @throws ::com::sun::star::io::IOException
 262             in case there is a problem reading/writing the relations info
 263      */
 264     void insertRelationships(
 265             [in] sequence< sequence< ::com::sun::star::beans::StringPair > > aEntries,
 266             [in] boolean bReplace )
 267         raises( ::com::sun::star::container::ElementExistException,
 268                 ::com::sun::star::io::IOException );
 269
 270     // -----------------------------------------------------------------------
 271     /** allows to clear the set of entries.
 272
 273         @throws ::com::sun::star::io::IOException
 274             in case there is a problem reading/writing the relations info
 275      */
 276     void clearRelationships()
 277         raises( ::com::sun::star::io::IOException );
 278
 279 };
 280
 281 //============================================================================
 282
 283 }; }; }; };
 284
 285 #endif
 286