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