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