xref: /trunk/main/udkapi/com/sun/star/registry/XRegistryKey.idl (revision 408a4873)

/**************************************************************
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/


#ifndef __com_sun_star_registry_XRegistryKey_idl__
#define __com_sun_star_registry_XRegistryKey_idl__

#ifndef __com_sun_star_uno_XInterface_idl__
#include <com/sun/star/uno/XInterface.idl>
#endif

#ifndef __com_sun_star_registry_InvalidRegistryException_idl__
#include <com/sun/star/registry/InvalidRegistryException.idl>
#endif

#ifndef __com_sun_star_registry_RegistryKeyType_idl__
#include <com/sun/star/registry/RegistryKeyType.idl>
#endif

#ifndef __com_sun_star_registry_RegistryValueType_idl__
#include <com/sun/star/registry/RegistryValueType.idl>
#endif

#ifndef __com_sun_star_registry_InvalidValueException_idl__
#include <com/sun/star/registry/InvalidValueException.idl>
#endif


//=============================================================================

module com { module sun { module star { module registry {

//=============================================================================
/** makes structural information (except regarding tree structures)
	of a single registry key accessible.

	<p>This is the main interface for registry keys.<p>

	@see XSimpleRegistry
*/
published interface XRegistryKey: com::sun::star::uno::XInterface
{
	//---------------------------------------------------------------------
	/** This is the key of the entry relative to its parent.<p>

		<p>The access path starts with the root "/" and all parent
		entry names are delimited with slashes "/" too, like in a
		UNIX (R) file system. Slashes which are part of single names
		are represented as hexadecimals preceded with a "%" like in
		URL syntax.
	 */
	[readonly, attribute] string	KeyName;

	//-------------------------------------------------------------------------
	/** checks if the key can be overwritten.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	boolean isReadOnly()
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	/** checks if the key points to an open valid key in the data-source.
	*/
	boolean isValid();

	//-------------------------------------------------------------------------
	/** @returns
		the type of the specified key.

		@param rKeyName
		specifies the relative path from the current key to
		the key of the type which will be returned.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	com::sun::star::registry::RegistryKeyType getKeyType( [in] string rKeyName )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	/** @returns
		the type of the key value or NOT_DEFINED if the key has no value.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	com::sun::star::registry::RegistryValueType getValueType()
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	/** @returns
		a long value if the key contains one.

		@throws InvalidRegistryException
		if the registry is not open.

		@throws InvalidValueException
		if the value is not of type long.
	*/
	long getLongValue()
			raises( com::sun::star::registry::InvalidRegistryException,
					com::sun::star::registry::InvalidValueException );

	//-------------------------------------------------------------------------
	/** sets a long value to the key.

		<p>If the key already has a value, the value will be
		overridden.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	void setLongValue( [in] long value )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::getLongListValue
	/** @returns
		a sequence of longs if the key contains a long list value.

	 	@throws InvalidRegistryException
	 	if the registry is not open.

	 	@throws InvalidValueException
	 	if the actual value is not of type long list.
	*/
	sequence<long> getLongListValue()
			raises( com::sun::star::registry::InvalidRegistryException,
					com::sun::star::registry::InvalidValueException );

	//-------------------------------------------------------------------------
	/** sets a long list value to the key.

		<p>If the key already has a value, the value will be
		overridden.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	void setLongListValue( [in] sequence<long> seqValue )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::getAsciiValue
	/** @returns
		an ascii string value if the key contains one.

	 	@throws InvalidRegistryException
	 	if the registry is not open.

	 	@throws InvalidValueException
	 	if the actual value is not of type ascii.
	*/
	string getAsciiValue()
			raises( com::sun::star::registry::InvalidRegistryException,
					com::sun::star::registry::InvalidValueException );

	//-------------------------------------------------------------------------
	/** sets an ASCII string value to the key.

		<p>The high byte of the string should be NULL.  If not, there
		is no guarantee that the string will be correctly transported.
		If the key already has a value, the value will be overridden.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	void setAsciiValue( [in] string value )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::getAsciiListValue
	/** @returns
		a sequence of ascii strings if the key contains an asci list value.

	 	@throws InvalidRegistryException
	 	if the registry is not open.

	 	@throws InvalidValueException
	 	if the actual value is not of type ascii list.
	*/
	sequence<string> getAsciiListValue()
			raises( com::sun::star::registry::InvalidRegistryException,
					com::sun::star::registry::InvalidValueException );

	//-------------------------------------------------------------------------
	/** sets an ASCII string list value to the key.

		<p>The high byte of the string should be NULL. If not, there
		is no guarantee that the string will be correctly transported.
		If the key already has a value, the value will be overridden.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	void setAsciiListValue( [in] sequence<string> seqValue )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::getStringValue
	/** @returns
		a unicode string value if the key contains one.

	 	@throws InvalidRegistryException
	 	if the registry is not open.

	 	@throws InvalidValueException
	 	if the actual value is not of type string.
	*/
	string getStringValue()
			raises( com::sun::star::registry::InvalidRegistryException,
					com::sun::star::registry::InvalidValueException );

	//-------------------------------------------------------------------------
	/** sets a unicode string value to the key.

		<p> If the key already has a value, the value will be
		overridden.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	void setStringValue( [in] string value )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::getStringListValue
	/** @returns
		a sequence of unicode strings if the key contains an unicode string list value.

	 	@throws InvalidRegistryException
	 	if the registry is not open.

	 	@throws InvalidValueException
	 	if the actual value is not of type string list.
	*/
	sequence<string> getStringListValue()
			raises( com::sun::star::registry::InvalidRegistryException,
					com::sun::star::registry::InvalidValueException );

	//-------------------------------------------------------------------------
	/** sets a unicode string value to the key.

		<p>If the key already has a value, the value will be overridden.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	void setStringListValue( [in] sequence<string> seqValue )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::getBinaryValue
	/** @returns
		a binary value if the key contains one.

	 	@throws InvalidRegistryException
	 	if the registry is not open.

	 	@throws InvalidValueException
	 	if the actual value is not of type binary.
	*/
	sequence<byte> getBinaryValue()
			raises( com::sun::star::registry::InvalidRegistryException,
					com::sun::star::registry::InvalidValueException );

	//-------------------------------------------------------------------------
	/** sets a binary value to the key.

		<p>If the key already has a value, the value will be
		overridden.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	void setBinaryValue( [in] sequence<byte> value )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	/** opens a sub key of the key.

		<p>If the sub key does not exist, the function returns a
		NULL-interface.

		@param aKeyName
		the relative path from the current key to the key
		which will be created.

		@returns
		a NULL interface if the key does not exist.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	com::sun::star::registry::XRegistryKey openKey( [in] string aKeyName )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	/** creates a new key in the registry.<p>

		<p>If the key already exists, the function will open the key.

		@param aKeyName
		specifies the relative path from the current key to
		the key which will be created.

		@returns
		a NULL interface if the key could not be created.

		@throws InvalidRegistryException
		if the registry is not open, the registry is readonly
		or if the key exists and is of type LINK.
	*/
	com::sun::star::registry::XRegistryKey createKey( [in] string aKeyName )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	/** closes a key in the registry.

		@throws InvalidRegistryException
		if the registry is not open.
	*/
	void closeKey()
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	/** deletes a key from the registry.

		@param aKeyName
		specifies the relative path from the current key to
		the key which will be deleted.

		@throws InvalidRegistryException
		if the registry is not open, the registry is readonly,
		the key does not exists or if the key is of type LINK.
	*/
	void deleteKey( [in] string rKeyName )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::openKeys
	/** opens all subkeys of the key. If a subkey is a link, the link will be
		resolved and the appropriate key will be opened.

	   	@returns
	   	an empty sequence if the key has no subkeys.

	   	@throws InvalidRegistryException
	   	if the registry is not open.
	*/
	sequence<com::sun::star::registry::XRegistryKey> openKeys()
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::getKeyNames
	/** @returns a sequence with the names of all subkeys of the key.
	  	If the key has no subkeys, the function returns an empty sequence. If a subkey is
	   	a link, the name of the link will be returned.

	 	@throws InvalidRegistryException
	 	if the registry is not open.
	 */
	sequence<string> getKeyNames()
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	/** creates a new link in the registry.

		@returns
		<TRUE/> if the link was created. If the link already
		exists or the link target does not exist, the
		function returns <FALSE/>.

		@param aLinkName
		specifies the relative path from the current key to
		the link which will be created.

		@param aLinkTarget
		specifies the full path of the key which will be
		referenced by the link.

		@throws InvalidRegistryException
		if the registry is not open or the registry is
		readonly.

	*/
	boolean createLink( [in] string aLinkName,
			 [in] string aLinkTarget )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	/** deletes a link from the registry.

		@param aLinkName
		specifies the relative path from the current key to
		the link which will be deleted.

		@throws InvalidRegistryException
		if the registry is not open, the registry is readonly,
		or if the link does not exist.
	*/
	void deleteLink( [in] string rLinkName )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::getLinkTarget
	/** @returns
		the target (complete path of a key) of the link specified by rLinkName.

	 	@param rLinKName
		specifies the relative path from the current key to
		the link which target will be returned.

	 	@throws InvalidRegistryException
	 	if the registry is not open or the link does not exists.
	*/
	string getLinkTarget( [in] string rLinkName )
			raises( com::sun::star::registry::InvalidRegistryException );

	//-------------------------------------------------------------------------
	// DOCUMENTATION CHANGED FOR XRegistryKey::getResolvedName
	/** @returns
		the resolved name of a key. The function resolve the complete name of the key.
		If a link could not be resolved, the linktarget concatenated with the unresolved rest
		of the name, will be returned.

	 	@param rKeyName
	 	specifies a relative path from the current key which will be resolved from all links.

	 	@throws InvalidRegistryException
	 	if the registry is not open or a recursion was detected.
	*/
	string getResolvedName( [in] string aKeyName )
			raises( com::sun::star::registry::InvalidRegistryException );

};

//=============================================================================

}; }; }; };

#endif