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