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