udkapi/com/sun/star/registry/XRegistryKey.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
  20
  21
  22 module com { module sun { module star { module registry {
  23
  24 /** makes structural information (except regarding tree structures)
  25     of a single registry key accessible.
  26
  27     <p>This is the main interface for registry keys.<p>
  28
  29     @see XSimpleRegistry
  30 */
  31 published interface XRegistryKey: com::sun::star::uno::XInterface
  32 {
  33     /** This is the key of the entry relative to its parent.<p>
  34
  35         <p>The access path starts with the root "/" and all parent
  36         entry names are delimited with slashes "/" too, like in a
  37         UNIX (R) file system. Slashes which are part of single names
  38         are represented as hexadecimals preceded with a "%" like in
  39         URL syntax.
  40      */
  41     [readonly, attribute] string    KeyName;
  42
  43     /** checks if the key can be overwritten.
  44
  45         @throws InvalidRegistryException
  46         if the registry is not open.
  47     */
  48     boolean isReadOnly()
  49             raises( com::sun::star::registry::InvalidRegistryException );
  50
  51     /** checks if the key points to an open valid key in the data-source.
  52     */
  53     boolean isValid();
  54
  55     /** @returns
  56         the type of the specified key.
  57
  58         @param rKeyName
  59         specifies the relative path from the current key to
  60         the key of the type which will be returned.
  61
  62         @throws InvalidRegistryException
  63         if the registry is not open.
  64     */
  65     com::sun::star::registry::RegistryKeyType getKeyType( [in] string rKeyName )
  66             raises( com::sun::star::registry::InvalidRegistryException );
  67
  68     /** @returns
  69         the type of the key value or NOT_DEFINED if the key has no value.
  70
  71         @throws InvalidRegistryException
  72         if the registry is not open.
  73     */
  74     com::sun::star::registry::RegistryValueType getValueType()
  75             raises( com::sun::star::registry::InvalidRegistryException );
  76
  77     /** @returns
  78         a long value if the key contains one.
  79
  80         @throws InvalidRegistryException
  81         if the registry is not open.
  82
  83         @throws InvalidValueException
  84         if the value is not of type long.
  85     */
  86     long getLongValue()
  87             raises( com::sun::star::registry::InvalidRegistryException,
  88                     com::sun::star::registry::InvalidValueException );
  89
  90     /** sets a long value to the key.
  91
  92         <p>If the key already has a value, the value will be
  93         overridden.
  94
  95         @throws InvalidRegistryException
  96         if the registry is not open.
  97     */
  98     void setLongValue( [in] long value )
  99             raises( com::sun::star::registry::InvalidRegistryException );
 100
 101     // DOCUMENTATION CHANGED FOR XRegistryKey::getLongListValue
 102     /** @returns
 103         a sequence of longs if the key contains a long list value.
 104
 105          @throws InvalidRegistryException
 106          if the registry is not open.
 107
 108          @throws InvalidValueException
 109          if the actual value is not of type long list.
 110     */
 111     sequence<long> getLongListValue()
 112             raises( com::sun::star::registry::InvalidRegistryException,
 113                     com::sun::star::registry::InvalidValueException );
 114
 115     /** sets a long list value to the key.
 116
 117         <p>If the key already has a value, the value will be
 118         overridden.
 119
 120         @throws InvalidRegistryException
 121         if the registry is not open.
 122     */
 123     void setLongListValue( [in] sequence<long> seqValue )
 124             raises( com::sun::star::registry::InvalidRegistryException );
 125
 126     // DOCUMENTATION CHANGED FOR XRegistryKey::getAsciiValue
 127     /** @returns
 128         an ascii string value if the key contains one.
 129
 130          @throws InvalidRegistryException
 131          if the registry is not open.
 132
 133          @throws InvalidValueException
 134          if the actual value is not of type ascii.
 135     */
 136     string getAsciiValue()
 137             raises( com::sun::star::registry::InvalidRegistryException,
 138                     com::sun::star::registry::InvalidValueException );
 139
 140     /** sets an ASCII string value to the key.
 141
 142         <p>The high byte of the string should be NULL.  If not, there
 143         is no guarantee that the string will be correctly transported.
 144         If the key already has a value, the value will be overridden.
 145
 146         @throws InvalidRegistryException
 147         if the registry is not open.
 148     */
 149     void setAsciiValue( [in] string value )
 150             raises( com::sun::star::registry::InvalidRegistryException );
 151
 152     // DOCUMENTATION CHANGED FOR XRegistryKey::getAsciiListValue
 153     /** @returns
 154         a sequence of ascii strings if the key contains an ascii list value.
 155
 156          @throws InvalidRegistryException
 157          if the registry is not open.
 158
 159          @throws InvalidValueException
 160          if the actual value is not of type ascii list.
 161     */
 162     sequence<string> getAsciiListValue()
 163             raises( com::sun::star::registry::InvalidRegistryException,
 164                     com::sun::star::registry::InvalidValueException );
 165
 166     /** sets an ASCII string list value to the key.
 167
 168         <p>The high byte of the string should be NULL. If not, there
 169         is no guarantee that the string will be correctly transported.
 170         If the key already has a value, the value will be overridden.
 171
 172         @throws InvalidRegistryException
 173         if the registry is not open.
 174     */
 175     void setAsciiListValue( [in] sequence<string> seqValue )
 176             raises( com::sun::star::registry::InvalidRegistryException );
 177
 178     // DOCUMENTATION CHANGED FOR XRegistryKey::getStringValue
 179     /** @returns
 180         a unicode string value if the key contains one.
 181
 182          @throws InvalidRegistryException
 183          if the registry is not open.
 184
 185          @throws InvalidValueException
 186          if the actual value is not of type string.
 187     */
 188     string getStringValue()
 189             raises( com::sun::star::registry::InvalidRegistryException,
 190                     com::sun::star::registry::InvalidValueException );
 191
 192     /** sets a unicode string value to the key.
 193
 194         <p> If the key already has a value, the value will be
 195         overridden.
 196
 197         @throws InvalidRegistryException
 198         if the registry is not open.
 199     */
 200     void setStringValue( [in] string value )
 201             raises( com::sun::star::registry::InvalidRegistryException );
 202
 203     // DOCUMENTATION CHANGED FOR XRegistryKey::getStringListValue
 204     /** @returns
 205         a sequence of unicode strings if the key contains a unicode string list value.
 206
 207          @throws InvalidRegistryException
 208          if the registry is not open.
 209
 210          @throws InvalidValueException
 211          if the actual value is not of type string list.
 212     */
 213     sequence<string> getStringListValue()
 214             raises( com::sun::star::registry::InvalidRegistryException,
 215                     com::sun::star::registry::InvalidValueException );
 216
 217     /** sets a unicode string value to the key.
 218
 219         <p>If the key already has a value, the value will be overridden.
 220
 221         @throws InvalidRegistryException
 222         if the registry is not open.
 223     */
 224     void setStringListValue( [in] sequence<string> seqValue )
 225             raises( com::sun::star::registry::InvalidRegistryException );
 226
 227     // DOCUMENTATION CHANGED FOR XRegistryKey::getBinaryValue
 228     /** @returns
 229         a binary value if the key contains one.
 230
 231          @throws InvalidRegistryException
 232          if the registry is not open.
 233
 234          @throws InvalidValueException
 235          if the actual value is not of type binary.
 236     */
 237     sequence<byte> getBinaryValue()
 238             raises( com::sun::star::registry::InvalidRegistryException,
 239                     com::sun::star::registry::InvalidValueException );
 240
 241     /** sets a binary value to the key.
 242
 243         <p>If the key already has a value, the value will be
 244         overridden.
 245
 246         @throws InvalidRegistryException
 247         if the registry is not open.
 248     */
 249     void setBinaryValue( [in] sequence<byte> value )
 250             raises( com::sun::star::registry::InvalidRegistryException );
 251
 252     /** opens a sub key of the key.
 253
 254         <p>If the sub key does not exist, the function returns a
 255         NULL-interface.
 256
 257         @param aKeyName
 258         the relative path from the current key to the key
 259         which will be created.
 260
 261         @returns
 262         a NULL interface if the key does not exist.
 263
 264         @throws InvalidRegistryException
 265         if the registry is not open.
 266     */
 267     com::sun::star::registry::XRegistryKey openKey( [in] string aKeyName )
 268             raises( com::sun::star::registry::InvalidRegistryException );
 269
 270     /** creates a new key in the registry.<p>
 271
 272         <p>If the key already exists, the function will open the key.
 273
 274         @param aKeyName
 275         specifies the relative path from the current key to
 276         the key which will be created.
 277
 278         @returns
 279         a NULL interface if the key could not be created.
 280
 281         @throws InvalidRegistryException
 282         if the registry is not open, the registry is readonly
 283         or if the key exists and is of type LINK.
 284     */
 285     com::sun::star::registry::XRegistryKey createKey( [in] string aKeyName )
 286             raises( com::sun::star::registry::InvalidRegistryException );
 287
 288     /** closes a key in the registry.
 289
 290         @throws InvalidRegistryException
 291         if the registry is not open.
 292     */
 293     void closeKey()
 294             raises( com::sun::star::registry::InvalidRegistryException );
 295
 296     /** deletes a key from the registry.
 297
 298         @param rKeyName
 299         specifies the relative path from the current key to
 300         the key which will be deleted.
 301
 302         @throws InvalidRegistryException
 303         if the registry is not open, the registry is readonly,
 304         the key does not exists or if the key is of type LINK.
 305     */
 306     void deleteKey( [in] string rKeyName )
 307             raises( com::sun::star::registry::InvalidRegistryException );
 308
 309     // DOCUMENTATION CHANGED FOR XRegistryKey::openKeys
 310     /** opens all subkeys of the key. If a subkey is a link, the link will be
 311         resolved and the appropriate key will be opened.
 312
 313            @returns
 314            an empty sequence if the key has no subkeys.
 315
 316            @throws InvalidRegistryException
 317            if the registry is not open.
 318     */
 319     sequence<com::sun::star::registry::XRegistryKey> openKeys()
 320             raises( com::sun::star::registry::InvalidRegistryException );
 321
 322     // DOCUMENTATION CHANGED FOR XRegistryKey::getKeyNames
 323     /** @returns a sequence with the names of all subkeys of the key.
 324           If the key has no subkeys, the function returns an empty sequence. If a subkey is
 325            a link, the name of the link will be returned.
 326
 327          @throws InvalidRegistryException
 328          if the registry is not open.
 329      */
 330     sequence<string> getKeyNames()
 331             raises( com::sun::star::registry::InvalidRegistryException );
 332
 333     /** creates a new link in the registry.
 334
 335         @returns
 336         `TRUE` if the link was created. If the link already
 337         exists or the link target does not exist, the
 338         function returns `FALSE`.
 339
 340         @param aLinkName
 341         specifies the relative path from the current key to
 342         the link which will be created.
 343
 344         @param aLinkTarget
 345         specifies the full path of the key which will be
 346         referenced by the link.
 347
 348         @throws InvalidRegistryException
 349         if the registry is not open or the registry is
 350         readonly.
 351
 352     */
 353     boolean createLink( [in] string aLinkName,
 354              [in] string aLinkTarget )
 355             raises( com::sun::star::registry::InvalidRegistryException );
 356
 357     /** deletes a link from the registry.
 358
 359         @param rLinkName
 360         specifies the relative path from the current key to
 361         the link which will be deleted.
 362
 363         @throws InvalidRegistryException
 364         if the registry is not open, the registry is readonly,
 365         or if the link does not exist.
 366     */
 367     void deleteLink( [in] string rLinkName )
 368             raises( com::sun::star::registry::InvalidRegistryException );
 369
 370     // DOCUMENTATION CHANGED FOR XRegistryKey::getLinkTarget
 371     /** @returns
 372         the target (complete path of a key) of the link specified by rLinkName.
 373
 374          @param rLinkName
 375         specifies the relative path from the current key to
 376         the link which target will be returned.
 377
 378          @throws InvalidRegistryException
 379          if the registry is not open or the link does not exists.
 380     */
 381     string getLinkTarget( [in] string rLinkName )
 382             raises( com::sun::star::registry::InvalidRegistryException );
 383
 384     // DOCUMENTATION CHANGED FOR XRegistryKey::getResolvedName
 385     /** @returns
 386         the resolved name of a key. The function resolve the complete name of the key.
 387         If a link could not be resolved, the linktarget concatenated with the unresolved rest
 388         of the name, will be returned.
 389
 390          @param aKeyName
 391          specifies a relative path from the current key which will be resolved from all links.
 392
 393          @throws InvalidRegistryException
 394          if the registry is not open or a recursion was detected.
 395     */
 396     string getResolvedName( [in] string aKeyName )
 397             raises( com::sun::star::registry::InvalidRegistryException );
 398
 399 };
 400
 401
 402 }; }; }; };
 403
 404 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */