System CATSettingRepository

Usage: you must use this class as is. You should never derive it.

public class CATSettingRepository

Class for managing the user's customization.

Role: CATSettingRepositories manage aggregates of setting attributes that are used to store and retrieve values and parameters set by the user. They are stored between working sessions in one setting file.

Each CATSettingRepository has a unique name used by the application to access it. Each attribute within one CATSettingRepository is identified by its name and type.

Setting attributes can store the values of simple types such as integers or floats. In addition, a marshallable object should be saved as a setting attribute with less or no impact on the application.

A CATSettingRepository instance can be saved in memory for temporary storage using a commit/rollback mechanism, and in a file for persistent storage.

Method Index

o Commit(int)

Makes a persistent copy of the CATsettingRepository in Memory.

o GetInfo(char*,CATSettingInfo*,int)

Retrieves the infos for a given attribute within the CATSettingRepository.

o GetLock(char*,char&)

Retrieves the lock's state of a given attribute within the CATSettingRepository.

o GetRepository(char*,int,AccessType,CATISysSettingController*)

Creates a CATSettingRepository.

o IsPresent(char*,char*)

Indicates the existence of a given attribute.

o IsProtected()

Gives the state of a CATSettingRepository.

o Lock(char*)

Locks a given attribute within the CATSettingRepository.

o NextAttribute(char*,char*,long*,short)

Browses the CATSettingRepository.

o OrigineValue(char*,CATString**)

Retrieves the origine of an attribute's value.

o ReadSetting(char*,int*,long)

Retrieves the value of a setting attribute which is an array of ints.

o ReadSetting(char*,CATString*)

Retrieves the value of a setting attribute.

o ReadSetting(char*,char*,long)

Retrieves the value of a setting attribute which is an array of char.

o ReadSetting(char*,float*,long)

Retrieves the value of a setting attribute which is an array of floats.

o ReadSetting(char*,short*,long)

Retrieves the value of a setting attribute which is an array of shorts.

o ReadSetting(char*,double*,long)

Retrieves the value of a setting attribute which is an array of doubles.

o ReadSetting(char*,CATBaseUnknown*)

Retrieves the value of a setting attribute.

o ReadSetting(char*,CATString**,long)

Retrieves the value of a setting attribute which is an array of CATString.

o ReadSetting(char*,CATUnicodeString*)

Retrieves the value of a setting attribute.

o ReadSetting(char*,unsigned int*,long)

Retrieves the value of a setting attribute which is an array of unsigned ints.

o ReadSetting(char*,CATBaseUnknown**,long)

Retrieves the value of a setting attribute which is an array of CATBaseUnknown.

o ReadSetting(char*,CATUnicodeString**,long)

Retrieves the value of a setting attribute which is an array of CATUnicodeString.

o ResetToAdminValues()

Restores the administrated values of the attributes.

o Rollback()

Restores a previous persistent copy of the CATsettingRepository in Memory.

o SaveRepository(char*)

Makes a persistent copy of the CATsettingRepository on file.

o Unlock(char*)

Unlocks a given attribute within the CATSettingRepository.

o WriteSetting(char*,int*,long,int)

Sets the value of a setting attribute which is an array of ints.

o WriteSetting(char*,CATString*,int)

Sets the value of a setting attribute.

o WriteSetting(char*,char*,long,int)

Sets the value of a setting attribute which is an array of chars.

o WriteSetting(char*,float*,long,int)

Sets the value of a setting attribute which is an array of floats.

o WriteSetting(char*,short*,long,int)

Sets the value of a setting attribute which is an array of shorts.

o WriteSetting(char*,double*,long,int)

Sets the value of a setting attribute which is an array of doubles.

o WriteSetting(char*,CATBaseUnknown*,int)

Sets the value of a setting attribute.

o WriteSetting(char*,CATString**,long,int)

Sets the value of a setting attribute which is an array of CATString.

o WriteSetting(char*,CATUnicodeString*,int)

Sets the value of a setting attribute.

o WriteSetting(char*,unsigned int*,long,int)

Sets the value of a setting attribute which is an array of unsigned ints.

o WriteSetting(char*,CATBaseUnknown**,long,int)

Sets the value of a setting attribute which is an array of CATBaseUnknown.

o WriteSetting(char*,CATUnicodeString**,long,int)

Sets the value of a setting attribute which is an array of CATUnicodeString.

Enumerated Type Index

o AccessType

Methods

Makes a persistent copy of the CATsettingRepository in Memory.
Role: Makes a persistent copy of the CATsettingRepository in Memory The values of the attributes could be restore after that by doing a call to .

Parameters:

iNoEvent

In order to emit the commit event
Legal values: 0 to emit the event (the default) and 1 for no emission

Returns:

Legal values 1 on Success, otherwise -1.

Retrieves the infos for a given attribute within the CATSettingRepository.
Role:Retrieves the infos for a given attribute within the CATSettingRepository.

Parameters:

iAttributeName

The name of the attribute.
Legal values: The length of the string must be less than or equal to

.

oInfo

the info Structure.

Returns:

Legal values 0 OK or -1 no iAttributeName was found.

Retrieves the lock's state of a given attribute within the CATSettingRepository.
Role:Retrieves the state of the lock of a given attribute, in order to give it to the method. An attribute can have been lock by an CATIA administrator, using the Tools Options UI. This methods and and should be used when coding a Tools Option Dialog.

Parameters:

iAttributeName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

oLock

the state of the lock.

Returns:

Legal values 0 OK or -1 no iAttributeName was found.

Creates a CATSettingRepository.
Role: Creates the unique instance of the class CATSettingRepository named with the given argument. If a setting file exists, it is read.
Lifecycle rules deviation: The Applications must not call release on the returned pointer.

Parameters:

iRepositoryName

The name of the CATSettingRepository used by the applications to retrieve it.

iMode

Reserved for internal use. Must always be set to 0. Legal values: The length of the string must be less than or equal to

.

iType

Defines the type of the setting.

iCtrl

pointer to the controler Interfaces.

Indicates the existence of a given attribute.
Role: Searches within the CATSettingRepository for an attribute named iAttributeName and of type iAttributeClass.

Parameters:

iAttributeName

The name of the attribute to be set. Legal values: The length of the string must be less than or equal to

.

iAttributeClass

The type of the requested attribute, that could be "int", "float",...

Returns:

the number of elements constituting the attribute, otherwise negative.

Gives the state of a CATSettingRepository.
Role: Returns the global state of the CATSettingRepository, which is said protected if all its attributes are locked and thus could not be modified.

Returns:

Legal values 1 if all attributes are currently locked, otherwise 0.

Locks a given attribute within the CATSettingRepository.
Role: Locks a given attribute, in order to prevent any further modifications of its value. This methods is only applicable in Administrator's mode, otherwise it does nothing. This methods and and should be used when coding a Tools Option Dialog.

Parameters:

iAttributeName

The name of the attribute to be locked.
Legal values: The length of the string must be less than or equal to

.

Returns:

Legal values 0 if the attribute was successfully locked, otherwise -1.

Browses the CATSettingRepository.
Role: Returns the Name, the type and the number of constituting elements of an attribute. The strings are copied but their allocation must be done by the caller.

Parameters:

oAttributeName

a pointer to an allocated buffer where the attribute's name will be copied

oAttributeClass

a pointer to an allocated buffer where the attribute's type will be copied

oAttributeSize

a pointer to a long int to put the number of constituting elements

iReset

iReset = 1 forces to begin with the first Attribute,reseting the state reached with the last call to this method, otherwise 0

Returns:

Legal values 0 until reaching the last Attribute and returning -1 when the last attribute is reached

Retrieves the origine of an attribute's value.
Role: Retrieves the level of administration where the given attribute has been locked or if the attribute is not locked the level that will give its value to the attribute during the reset process.

Parameters:

iAttributeName

The name of the attribute.

oOrigineLevel

the Path of the level of administration

Returns:

Legal values 0 on success -1 in cas of failure.

Retrieves the value of a setting attribute which is an array of ints.
Role: Retrieves using its name, the values of each element of the array constituting an attribute. The array is defined as an array of initialized ints because it is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized ints. If the attribute has not been yet created, then the elements of ioSetting are used as default values, otherwise the elements of ioSetting are overwritten by the retrieved values.

iLength

The number of elements to read.

Returns:

Legal values:
>0: on Success returns the number of elements really read
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute.
Role: Retrieves using its name, the value of an attribute constituted by one CATString. A pointer on a intialized and constructed object of type CATString must be given as argument, because this object is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the settings attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

A pointer on a construted CATString. If the attribute has not been yet created, then ioSetting is used as default values, otherwise ioSetting is overwritten by the retrieved value.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute which is an array of char.
Role: Retrieves using its name, the values of each element of the array constituting an attribute. The array is defined as an array of initialized char because it is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized char. If the attribute has not been yet created, then the elements of ioSetting are used as default values, otherwise the elements of ioSetting are overwritten by the retrieved values.

iLength

The number of elements to read.

Returns:

Legal values:
>0: on Success returns the number of elements really read
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute which is an array of floats.
Role: Retrieves using its name, the values of each element of the array constituting an attribute. The array is defined as an array of initialized floats because it is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized floats. If the attribute has not been yet created, then the elements of ioSetting are used as default values, otherwise the elements of ioSetting are overwritten by the retrieved values.

iLength

The number of elements to read.

Returns:

Legal values:
>0: on Success returns the number of elements really read
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute which is an array of shorts.
Role: Retrieves using its name, the values of each element of the array constituting an attribute. The array is defined as an array of initialized shorts because it is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized shorts. If the attribute has not been yet created, then the elements of ioSetting are used as default values, otherwise the elements of ioSetting are overwritten by the retrieved values.

iLength

The number of elements to read.

Returns:

Legal values:
>0: on Success returns the number of elements really read
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute which is an array of doubles.
Role: Retrieves using its name, the values of each element of the array constituting an attribute. The array is defined as an array of initialized doubles because it is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized doubles. If the attribute has not been yet created, then the elements of ioSetting are used as default values, otherwise the elements of ioSetting are overwritten by the retrieved values.

iLength

The number of elements to read.

Returns:

Legal values:
>0: on Success returns the number of elements really read
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute.
Role: Retrieves using its name, the value of an attribute constituted by one CATBaseUnknown. A pointer on a intialized and constructed object of type CATBaseUnknown must be given as argument, because this object is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be retrieved or created.
Legal values: The length of the string must be less than or equal to

.

ioSetting

A pointer on an initialized CATBaseUnknow. If the attribute has not been yet created, then ioSetting is used as default, otherwise ioSetting is overwritten by the retrieved value.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute which is an array of CATString.
Role: Retrieves using its name, the values of each element of the array constituting an attribute. The array is defined as an array of pointers on constructed CATString, because it is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of pointeur on constructed CATString. If the attribute has not been yet created, then the elements of ioSetting are used as default values, otherwise the elements of ioSetting are overwritten by the retrieved values.

iSize

The number of elements to read

Returns:

Legal values:
>0: on Success returns the number of elements really read
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute.
Role: Retrieves using its name, the value of an attribute constituted by one CATUnicodeString. A pointer on a intialized and constructed object of type CATUnicodeString must be given as argument, because this object is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

A pointer on a construted CATString. If the attribute has not been yet created, then ioSetting is used as default value, otherwise ioSetting is overwritten by the retrieved value.

Returns:

Legal values:
1 : on Succes
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute which is an array of unsigned ints.
Role: Retrieves using its name, the values of each element of the array constituting an attribute. The array is defined as an array of initialized unsigned ints because it is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized unsigned ints. If the attribute has not been yet created, then the elements of ioSetting are used as default values, otherwise the elements of ioSetting are overwritten by the retrieved values.

iLength

The number of elements to read.

Returns:

Legal values:
>0: on Success returns the number of elements really read
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute which is an array of CATBaseUnknown.
Role: Retrieves using its name, the values of each element of the array constituting an attribute. The array is defined as an array of pointers on constructed CATBaseUnknown, because it is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of pointers on initialized CATBaseUnknow. If the attribute has not been yet created, then the elements of ioSetting are used as default values, otherwise the elements of ioSetting are overwritten by the retrieved values.

iSize

The number of elements to read.

Returns:

Legal values:
>0: on Success returns the number of elements really read
0 : if a class conflict on the attribute has occured.
-1: on failure

Retrieves the value of a setting attribute which is an array of CATUnicodeString.
Role: Retrieves using its name, the values of each element of the array constituting an attribute. The array is defined as an array of pointers on constructed CATUnicodeString, because it is used to set the default value of the attribute, if it does not yet exist. In this last case the method calls WriteSetting () to initialize the setting attribute.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of pointeur on constructed CATUnicodeString. If the attribute has not been yet created, then the elements of ioSetting are used as default values, otherwise the elements of ioSetting are overwritten by the retrieved values.

iSize

The number of elements to read.

Returns:

Legal values:
>0: on Success returns the number of elements really read
0 : if a class conflict on the attribute has occured.
-1: on failure

Restores the administrated values of the attributes.
Role: Restores the administrated values of all the attributes of the CATSettingRepository.

Returns:

Legal values 1 on Success, otherwise negative.

Restores a previous persistent copy of the CATsettingRepository in Memory.
Role: Restores the persistent memory copy of the CATsettingRepository, done by the lastest call to . All modifications that have occured on any attributes of the CATSettingRepository, since the lastest call to Commit, are discarded.

Returns:

Legal values 0 on Success, otherwise -1.

Makes a persistent copy of the CATsettingRepository on file.
Role: Makes first a persistent copy of the CATsettingRepository in Memory by calling , then writes on file the persistent representation

Parameters:

iReserved

reserved for internal use. Not to be used.

Returns:

Legal values 0 on Success, otherwise negative.

Unlocks a given attribute within the CATSettingRepository.
Role: Unlocks a given attribute, in order to authorize further modifications of its value. This methods is only applicable in Administrator's mode, otherwise it does nothing, especially if the attribute is locked. This methods and Lock() and GetLock should be used when coding a Tools Option Dialog

Parameters:

iAttributeName

The name of the attribute to unlocked.
Legal values: The length of the string must be less than or equal to

.

Returns:

Legal values 0 if the attribute was successfully unlocked, otherwise -1.

Sets the value of a setting attribute which is an array of ints.
Role: Sets the values of each element of the array constituting the attribute. The array is defined as an array of initialized ints.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized ints.

iLength

The size of the array.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute.
Role: Sets the value of an attribute of type CATString

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

pointer on a constructed CATString.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute which is an array of chars.
Role: Sets the values of each element of the array constituting the attribute. The array is defined as an array of initialized char.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized chars.

iLength

The size of the array.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute which is an array of floats.
Role: Sets the values of each element of the array constituting the attribute. The array is defined as an array of initialized floats.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized floats.

iLength

The size of the array.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute which is an array of shorts.
Role: Sets the values of each element of the array constituting the attribute. The array is defined as an array of initialized shorts.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized shorts.

iLength

The size of the array.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute which is an array of doubles.
Role: Sets the values of each element of the array constituting the attribute. The array is defined as an array of initialized doubles.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized doubles.

iLength

The size of the array.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute.
Role: Sets the value of an attribute of type CATBaseUnknown

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

An initialized CATBaseUnknow.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute which is an array of CATString.
Role: Sets the values of each element of the array constituting the attribute. The array is defined as an array of pointers on constructed CATString.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of pointeur on initialized CATString.

iSize

The size of the array.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute.
Role: Sets the value of an attribute of type CATUnicodeString

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

pointer on a constructed CATUnicodeString.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute which is an array of unsigned ints.
Role: Sets the values of each element of the array constituting the attribute. The array is defined as an array of initialized unsigned ints.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of initialized unsigned ints.

iLength

The size of the array.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute which is an array of CATBaseUnknown.
Role: Sets the values of each element of the array constituting the attribute. The array is defined as an array of pointers on constructed CATBaseUnknown.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of pointeur on initialized CATBaseUnknow.

iSize

The size of the array.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Sets the value of a setting attribute which is an array of CATUnicodeString.
Role: Sets the values of each element of the array constituting the attribute. The array is defined as an array of pointers on constructed CATUnicodeString.

Parameters:

iSettingName

The name of the attribute to be set.
Legal values: The length of the string must be less than or equal to

.

ioSetting

an array of pointeur on initialized CATUnicodeString.

iSize

The size of the array.

iFlag

reserved for internal use. do not use other values than the default one.

Returns:

Legal values:
1 : on Success
0 : if a class conflict on the attribute has occured.
-1: on failure

Enumerated Types