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

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