offapi/com/sun/star/embed/XRelationshipAccess.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_embed_XRelationshipAccess_idl__
  20 #define __com_sun_star_embed_XRelationshipAccess_idl__
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23 #include <com/sun/star/beans/StringPair.idl>
  24 #include <com/sun/star/container/NoSuchElementException.idl>
  25 #include <com/sun/star/container/ElementExistException.idl>
  26 #include <com/sun/star/io/IOException.idl>
  27
  28
  29  module com {  module sun {  module star {  module embed {
  30
  31 /** This interface allows to get access to relationship data.
  32
  33     <p>
  34     The relationship data is organized as a set of entries. Each of entry
  35     is represented by a set of tags, where each tag has unique for this entry
  36     name and a string value. An entry must contain at least one tag named
  37     "ID", the value of this tag must be unique for the whole set of entries,
  38     this tag is used as a unique identifier of an entry.
  39     </p>
  40  */
  41 published interface XRelationshipAccess : ::com::sun::star::uno::XInterface
  42 {
  43     /** allows to detect whether there is an entry with specified value of
  44         "ID" tag.
  45
  46         @param sID
  47             the value of "ID" tag
  48
  49         @throws ::com::sun::star::io::IOException
  50             in case there is a problem reading the relations info
  51      */
  52     boolean hasByID( [in] string sID )
  53         raises( ::com::sun::star::io::IOException );
  54
  55     /** retrieves the value of "Target" tag from the entry with specified "ID"
  56         tag.
  57
  58         <p>
  59         If the entry has no "Target" tag an empty string is returned.
  60         </p>
  61
  62         @param sID
  63             the value of "ID" tag
  64
  65         @throws ::com::sun::star::container::NoSuchElementException
  66             in case there is no entry with specified tag
  67
  68         @throws ::com::sun::star::io::IOException
  69             in case there is a problem reading the relations info
  70      */
  71     string getTargetByID( [in] string sID )
  72         raises( ::com::sun::star::container::NoSuchElementException,
  73                 ::com::sun::star::io::IOException );
  74
  75     /** retrieves the value of "Type" tag from the entry with specified "ID"
  76         tag.
  77
  78         <p>
  79         If the entry has no "Type" tag an empty string is returned.
  80         </p>
  81
  82         @param sID
  83             the value of "ID" tag
  84
  85         @throws ::com::sun::star::container::NoSuchElementException
  86             in case there is no entry with specified tag
  87
  88         @throws ::com::sun::star::io::IOException
  89             in case there is a problem reading the relations info
  90      */
  91     string getTypeByID( [in] string sID )
  92         raises( ::com::sun::star::container::NoSuchElementException,
  93                 ::com::sun::star::io::IOException );
  94
  95     /** retrieves the sequence containing all the tags from the entry with
  96         specified value of "ID" tag.
  97
  98         @param sID
  99             the value of "ID" tag
 100
 101         @returns
 102             sequence, each element of the sequence represents tag,
 103             ::com::sun::star::beans::StringPair::First
 104             represents the tag name and
 105             ::com::sun::star::beans::StringPair::Second
 106             represents the tag value
 107
 108         @throws ::com::sun::star::container::NoSuchElementException
 109             in case there is no entry with specified tag
 110
 111         @throws ::com::sun::star::io::IOException
 112             in case there is a problem reading the relations info
 113      */
 114     sequence< ::com::sun::star::beans::StringPair >
 115             getRelationshipByID( [in] string sID )
 116         raises( ::com::sun::star::container::NoSuchElementException,
 117                 ::com::sun::star::io::IOException );
 118
 119     /** retrieves the sequence containing all the entries which "Type" tag
 120         takes the specified value.
 121
 122         @param sType
 123             specified value of "Type" tag, the parameter can contain an empty
 124             string, in this case all the entries that have empty "Type" tag or
 125             no such tag at all are returned
 126
 127         @returns
 128             sequence of entries, each entry is represented by sequence,
 129             each element of the sequence represents tag,
 130             ::com::sun::star::beans::StringPair::First
 131             represents the tag name and
 132             ::com::sun::star::beans::StringPair::Second
 133             represents the tag value.
 134             The sequence should contain the "ID" tag.
 135
 136         @throws ::com::sun::star::io::IOException
 137             in case there is a problem reading the relations info
 138      */
 139     sequence< sequence< ::com::sun::star::beans::StringPair > >
 140             getRelationshipsByType( [in] string sType )
 141         raises( ::com::sun::star::io::IOException );
 142
 143     /** retrieves the sequence containing all the entries controlled by the
 144         object.
 145
 146         @returns
 147             sequence of entries, each entry is represented by sequence,
 148             each element of the sequence represents tag,
 149             ::com::sun::star::beans::StringPair::First
 150             represents the tag name and
 151             ::com::sun::star::beans::StringPair::Second
 152             represents the tag value
 153
 154         @throws ::com::sun::star::io::IOException
 155             in case there is a problem reading the relations info
 156      */
 157     sequence< sequence< ::com::sun::star::beans::StringPair > >
 158             getAllRelationships()
 159         raises( ::com::sun::star::io::IOException );
 160
 161     /** allows to insert an entry.
 162
 163         @param sID
 164             the value of "ID" tag
 165
 166         @param aEntry
 167             a sequence, each element of the sequence represents tag,
 168             ::com::sun::star::beans::StringPair::First
 169             represents the tag name and
 170             ::com::sun::star::beans::StringPair::Second
 171             represents the tag value.
 172             May not contain "ID" tag, that is already specified in previous
 173             parameter.
 174
 175         @param bReplace
 176             specifies whether the replacement of existing entry is allowed
 177
 178         @throws ::com::sun::star::io::IOException
 179             in case there is a problem reading/writing the relations info
 180
 181         @throws ::com::sun::star::container::ElementExistException
 182             in case an element with the specified "ID" tag exists already, and
 183             no replacement is allowed
 184      */
 185     void insertRelationshipByID(
 186             [in] string sID,
 187             [in] sequence< ::com::sun::star::beans::StringPair > aEntry,
 188             [in] boolean bReplace )
 189         raises( ::com::sun::star::container::ElementExistException,
 190                 ::com::sun::star::io::IOException );
 191
 192     /** allows to remove an entry.
 193
 194         @param sID
 195             the value of "ID" tag
 196
 197         @throws ::com::sun::star::container::NoSuchElementException
 198             in case there is no entry with specified tag
 199
 200         @throws ::com::sun::star::io::IOException
 201             in case there is a problem reading/writing the relations info
 202      */
 203     void removeRelationshipByID( [in] string sID )
 204         raises( ::com::sun::star::container::NoSuchElementException,
 205                 ::com::sun::star::io::IOException );
 206
 207     /** allows to insert a set of entries
 208
 209         @param aEntries
 210             sequence of entries, each entry is represented by sequence,
 211             each element of the sequence represents tag,
 212             ::com::sun::star::beans::StringPair::First
 213             represents the tag name and
 214             ::com::sun::star::beans::StringPair::Second
 215             represents the tag value.
 216             Each entry must contain "ID" tag.
 217
 218         @param bReplace
 219             specifies whether the replacement of existing entry is allowed
 220
 221         @throws ::com::sun::star::container::ElementExistException
 222             in case an element with the provided "ID" tag exists already, and
 223             no replacement is allowed
 224
 225         @throws ::com::sun::star::io::IOException
 226             in case there is a problem reading/writing the relations info
 227      */
 228     void insertRelationships(
 229             [in] sequence< sequence< ::com::sun::star::beans::StringPair > > aEntries,
 230             [in] boolean bReplace )
 231         raises( ::com::sun::star::container::ElementExistException,
 232                 ::com::sun::star::io::IOException );
 233
 234     /** allows to clear the set of entries.
 235
 236         @throws ::com::sun::star::io::IOException
 237             in case there is a problem reading/writing the relations info
 238      */
 239     void clearRelationships()
 240         raises( ::com::sun::star::io::IOException );
 241
 242 };
 243
 244
 245 }; }; }; };
 246
 247 #endif
 248
 249 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */