#include "api1/Cipres.idl"

module CipresIDL_api1
{
	/*
		Each user will be running his own properties service.  There is a system property
		file/store of properties that affect all users and a per user property store.  Values
		in the user property store override those in the system store.

		Errors:
	*/
	interface CipresProperties:  LifeCycle 
	{
		typedef string  NameValuePair[2];
		typedef sequence<NameValuePair> NameValuePairSeq;
		struct PropertyError 
		{
			string property;
			string value;
			string error;
		};
		typedef sequence<PropertyError> PropertyErrorSeq;

		PropertyErrorSeq checkError();
		
		/*
			Getters return true if property exists, false otherwise.  A value that has only
			whitespace is treated the same as property doesn't exist (i.e. false is returned). 
			If property exists but can't be converted to the requested type a BadArgException 
			will be thrown.   
		*/
		boolean getProperty(in string name, out string value);
		boolean getBoolProperty(in string name, out boolean value) raises(BadArgException);
		boolean getFloatProperty(in string name, out double value) raises(BadArgException);
		boolean getIntProperty(in string name, out long value) raises(BadArgException);

		/* Todo: do we need this method? Or just want a way to dump properties for debug output ? */ 
		NameValuePairSeq getProperties();


		/*
			Setters: 
				if system = true, the property will be stored in the appropriate
				file in CIPRES_ROOT/share/system resources and will therefore affect all users.
				A InsufficientPrivelege error will be thrown if the properties service is running
				w/o admin rights.

				if system = false, the property will be stored in the user's (i.e. the uid under
				which the property service is running) property file.  

				A BadArgException is thrown if the value can't be converted to the specified type or
				if the property is one that the properties service knows about and the value
				specified doesn't conform to the rules for that property.
		*/

		enum PropertySource {
			INSTALLATION_PROPERTIES,
			SYSTEM_PROPERTIES,
			USER_PROPERTIES
		};

		void setProperty( in boolean system, in string name, in string value)
			raises (InsufficientPrivilegeException, ApplicationException);
		void setBoolProperty(in boolean system, in string name, in boolean value)
			raises (BadArgException, InsufficientPrivilegeException, ApplicationException);
		void setFloatProperty(in boolean system, in string name, in double  value)
			raises (BadArgException, InsufficientPrivilegeException, ApplicationException);
		void setIntProperty(in boolean system, in string name, in long value)
			raises (BadArgException, InsufficientPrivilegeException, ApplicationException);

		/*
			 performs a postfix increment operation on the indicated property, storing the new value
			 and returning the old one. If the source argument isn't a value from the PropertySource
			 enumeration, or the property isn't an integer type, a BadArgumentException is thrown
		*/
		boolean incrementProperty(in short source, in string name, out long value)
			raises (BadArgException, InsufficientPrivilegeException, ApplicationException);
	};

};