Data Structures
struct	PREF_preference_context_values_t

struct	PREF_preference_definition_t

struct	PREF_preference_object_t

Typedefs
typedef enum PREF_import_actions_e	PREF_import_actions_t

typedef struct PREF_preference_context_values_t *	PREF_preference_context_values_p_t

typedef struct PREF_preference_definition_t *	PREF_preference_definition_p_t

typedef struct PREF_preference_object_t *	PREF_preference_object_p_t

typedef enum PREF_preference_type_e	PREF_preference_type_t

typedef enum TC_preference_search_scope_e	TC_preference_search_scope_t

Initialization of Preferences module
TC_API int	PREF_initialize (void)

TC_API int	PREF_reinitialize ()

Preferences Protection Scope
The protection scope defines the lowest-level of users allowed to provide a value (e.g. create an instance of the preference). This can be modified only by a system administrator. Possible values are: TC_preference_user: all users are allowed to provide a value. Instances can be created at the User, Role, Group and Site levels. TC_preference_role: only system and group administrators can provide a value. Instances can be created at the Role, Group and Site levels only. TC_preference_group: only system and group administrators can provide a value. Instances can be created at the Group and Site levels only. TC_preference_site: only system administrators can provide a value. Instances can be only created at the Site level. TC_preference_system: Same restrition as for TC_preference_site. However, the protection scope cannot be modified by a system administrator.
TC_API int	PREF_ask_protection_scope (const char preference_name, TC_preference_search_scope_t protection_scope)

TC_API int	PREF_ask_protection_scopes (int preference_count, const char preference_names, TC_preference_search_scope_t protection_scopes)

TC_API int	PREF_set_protection_scope (const char *preference_name, TC_preference_search_scope_t protection_scope)

TC_API int	PREF_set_protection_scopes (int preference_count, const char **preference_names, TC_preference_search_scope_t protection_scopes[])

Preferences Environment Enabled Information
The Environment Enabled flag determines if a preference value can be retrieved from a system environment value. If set to true, the existence of an environment variable with the name of the preference is checked. If it exists, the value is retrieved. Note Multi-valued preferences cannot be retrieved through environment variable.
TC_API int	PREF_ask_environment_set_flag (const char preference_name, logical flag)

TC_API int	PREF_ask_environment_set_flags (int preference_count, const char preference_names, logical flags)

TC_API int	PREF_set_environment_set_flag (const char *preference_name, logical flag)

TC_API int	PREF_set_environment_set_flags (int preference_count, const char **preference_names, const logical flag[])

Preferences Count
TC_API int	PREF_ask_value_count (const char preference_name, int value_count)

TC_API int	PREF_ask_value_count_at_location (const char preference_name, TC_preference_search_scope_t location, int value_count)

String Preferences
TC_API int	PREF_ask_char_value (const char preference_name, int index, char *value)

TC_API int	PREF_ask_char_values (const char preference_name, int count, char ***value)

TC_API int	PREF_set_char_values (const char preference_name, int value_count, char values[])

TC_API int	PREF_ask_char_value_at_location (const char preference_name, TC_preference_search_scope_t location, int index, char *value)

TC_API int	PREF_ask_char_values_at_location (const char preference_name, TC_preference_search_scope_t location, int count, char ***values)

TC_API int	PREF_set_char_values_at_location (const char preference_name, TC_preference_search_scope_t location, int value_count, char values[])

Integer Preferences
TC_API int	PREF_ask_int_value (const char preference_name, int index, int value)

TC_API int	PREF_ask_int_values (const char preference_name, int value_count, int **values)

TC_API int	PREF_set_int_values (const char *preference_name, int value_count, int values[])

TC_API int	PREF_ask_int_value_at_location (const char preference_name, TC_preference_search_scope_t location, int index, int value)

TC_API int	PREF_ask_int_values_at_location (const char preference_name, TC_preference_search_scope_t location, int value_count, int **values)

TC_API int	PREF_set_int_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int value_count, int values[])

Double Preferences
TC_API int	PREF_ask_double_value (const char preference_name, int index, double value)

TC_API int	PREF_ask_double_values (const char preference_name, int value_count, double **values)

TC_API int	PREF_set_double_values (const char *preference_name, int value_count, double values[])

TC_API int	PREF_ask_double_value_at_location (const char preference_name, TC_preference_search_scope_t location, int index, double value)

TC_API int	PREF_ask_double_values_at_location (const char preference_name, TC_preference_search_scope_t location, int value_count, double **values)

TC_API int	PREF_set_double_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int value_count, double values[])

Logical Preferences
TC_API int	PREF_ask_logical_value (const char preference_name, int index, logical value)

TC_API int	PREF_ask_logical_values (const char preference_name, int value_count, logical **values)

TC_API int	PREF_set_logical_value (const char *preference_name, logical value)

TC_API int	PREF_set_logical_values (const char *preference_name, int value_count, logical values[])

TC_API int	PREF_ask_logical_value_at_location (const char preference_name, TC_preference_search_scope_t location, int index, logical value)

TC_API int	PREF_ask_logical_values_at_location (const char preference_name, TC_preference_search_scope_t location, int value_count, logical **values)

TC_API int	PREF_set_logical_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int value_count, logical values[])

Preferences Definitions
TC_API int	PREF_set_definition (const char *preference_name, PREF_preference_object_t preference_object, logical env_variable_enabled)

TC_API int	PREF_delete_definition (int nb_of_preferences, const char **preference_names, logical delete_all_custom_definitions)

Preferences Import and Export
TC_API int	PREF_export_preference_list (int preference_count, char *preference_names, TC_preference_search_scope_t location, const char output_file_name)

TC_API int	PREF_export_preferences (TC_preference_search_scope_t location, const char *output_file_name)

TC_API int	PREF_export_preferences_with_category (TC_preference_search_scope_t location, int number_of_categories, char *categories, const char output_file_name)

TC_API int	PREF_import_preferences (TC_preference_search_scope_t location, const char *input_xml, PREF_import_actions_t action)

TC_API int	PREF_import_preferences_with_category (TC_preference_search_scope_t location, const char input_xml, int number_of_categories, char *category_names, PREF_import_actions_t action)

Deleting Preferences Instances
TC_API int	PREF_delete_preference (const char *preference_name)

TC_API int	PREF_delete_preference_at_location (const char *preference_name, TC_preference_search_scope_t location)

TC_API int	PREF_delete_non_session_preference (char *preference_name, tag_t object)

Preferences Refresh and Lock
TC_API int	PREF_refresh (const char *preference_name)

TC_API int	PREF_lock_site_preferences ()

TC_API int	PREF_unlock_site_preferences ()

Deprecated APIs
TC_API int	PREF_set_search_scope (TC_preference_search_scope_t scope)

TC_API int	PREF_ask_search_scope (TC_preference_search_scope_t *scope)

Detailed Description

Teamcenter has implemented preferences functions that allows users to customize the operating environment.

Detailed information is supplied for the following aspects of preferences functions:

The location of preference files, and the precedence rules employed in reading and writing to them.
The syntax of preference codes and values.
The Preference codes currently defined for preferences in Teamcenter.

Teamcenter makes use of this mechanism itself, and it also provides ITK level functions for programmers to make use of the same preference mechanism.
Programmers can define their own preference codes if they wish, or they can read and write to existing Teamcenter preferences.

If you intend to add new preference codes, we suggest that you prefix them with your company name, thus ensuring that they will not conflict with any preference codes that Teamcenter may implement in the future.

Note: Teamcenter may alter or obsolete preference codes as the product evolves. These changes will be documented in the Release Notes.

Typedef Documentation

typedef enum PREF_import_actions_e PREF_import_actions_t

Different actions that can be specified during an import operation, in case of conflict.

typedef struct PREF_preference_context_values_t * PREF_preference_context_values_p_t

typedef struct PREF_preference_definition_t * PREF_preference_definition_p_t

typedef struct PREF_preference_object_t * PREF_preference_object_p_t

typedef enum PREF_preference_type_e PREF_preference_type_t

Defines the supported preference types

typedef enum TC_preference_search_scope_e TC_preference_search_scope_t

Defines different values that can be used as protection scopes or value locations.

Enumeration Type Documentation

enum PREF_import_actions_e

Different actions that can be specified during an import operation, in case of conflict.

Enumerator
PREF_import_action_skip	Skip the operation for the preference
PREF_import_action_override	Override with the specified preference
PREF_import_action_merge	Merge the specified preference values with the existing ones

Definition at line 67 of file preferences.h.

enum PREF_preference_type_e

Defines the supported preference types

Enumerator
PREF_preference_string	Preference of type String
PREF_preference_logical	Preference of type Logical
PREF_preference_integer	Preference of type Integer
PREF_preference_double	Preference of type Double
PREF_preference_date	Preference of type Date

Definition at line 77 of file preferences.h.

enum TC_preference_search_scope_e

Defines different values that can be used as protection scopes or value locations.

Enumerator
TC_preference_all	All scope - Deprecated
TC_preference_user	User value
TC_preference_role	Role value
TC_preference_group	Group value
TC_preference_site	Site value
TC_preference_system	System value (for protection scope only)
TC_preference_cots_location	COTS value (for location only)
TC_preference_overlay_location	OVERLAY value (for location only)
TC_preference_env_variable_location	Environment value (for location only)

Definition at line 52 of file preferences.h.

Function Documentation

TC_API int PREF_ask_char_value	(	const char *	preference_name,
		int	index,
		char **	value
	)

Asks the value of a preference of data type is "String".

The value is returned as specified at the first possible location starting at the location equal to the protection scope of the preference.

The index is used to determine which value to retrieve if the preference has multiple values. The index starts at 0. If the preference is single-valued, use the value 0.

Note: No error is returned if the preference does not exist.

Returns

ITK_ok on success
PF_BOUNDS if index is negative, or if the preference has at least a value and the index goes beyond the existing number of values.

Parameters

preference_name	(I) The name of the preference
index	(I) The index of the value to retrieve
value	(OF) The returned value

TC_API int PREF_ask_char_value_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	index,
		char **	value
	)

Asks the value of a preference whose data type is "String" at a specific level.
The index is used to determine which value to retrieve if the preference has multiple values. The index starts at 0.

Valid values for the location are TC_preference_user , TC_preference_role , TC_preference_group , TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_ask_char_value instead.

Returns

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the value
index	(I) The index at which to retrieve the value
value	(OF) The returned value

TC_API int PREF_ask_char_values	(	const char *	preference_name,
		int *	count,
		char ***	value
	)

Asks all the values of the preference whose data type is "String".
The value is returned as specified at the first possible location starting at the location equal to the protection scope of the preference.

Returns

ITK_ok on success
PF_NOTFOUND if preference_name is null or does not refer to an existing preference

Parameters

preference_name	(I) Preference name
count	(O) Number of values in the value array
value	(OF) count Array of returned values. The array is packed, which means that the memory is to be deallocated using MEM_free only on the container.

TC_API int PREF_ask_char_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	count,
		char ***	values
	)

Asks all the values of the preference whose data type is "String".

Valid values for the location are TC_preference_user , TC_preference_role , TC_preference_group , and TC_preference_site.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_ask_char_values instead.

Returns

ITK_ok on success
PREF_value_cannot_be_asked_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the values
count	(O) The number of values in the value array
values	(OF) count The array of values The array is packed, which means that the memory is to be deallocated using MEM_free only on the container.

TC_API int PREF_ask_double_value	(	const char *	preference_name,
		int	index,
		double *	value
	)

Asks the value of a preference whose data type is "Double".

The value is returned as specified at the first possible location starting at the location equal to the protection scope of the preference.

The index is used to determine which value to retrieve if the preference has multiple values. The index starts at 0. If the preference is single-valued, use the value 0.

Warning: If the preference is not of type "Double", no error is returned and the retrieved value is 0.

Returns

ITK_ok on success
PREF_invalid_preference_name if the string is invalid ('*', empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.
PF_BOUNDS if index is negative, or if the preference has at least a value and the index goes beyond the existing number of values.

Parameters

preference_name	(I) The name of the preference
index	(I) The index of the value to retrieve
value	(O)

TC_API int PREF_ask_double_value_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	index,
		double *	value
	)

Asks the value of a preference whose data type is "Double" at a given location.

Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_ask_double_value instead.

Warning: If the preference is not of type "Double", no error is returned and the retrieved value is 0.

Returns

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist or does not have any value at this location.

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the value
index	(I) The index of the value to retrieve
value	(O) The returned value

TC_API int PREF_ask_double_values	(	const char *	preference_name,
		int *	value_count,
		double **	values
	)

Asks all the values of the preference whose data type is "Double".
The value is returned as specified at the first possible location starting at the location equal to the protection scope of the preference.

Warning: If the preference is not of type "Double", no error is returned, value_count is provided accurately but the retrieved values are 0.

Returns

ITK_ok on success
PF_NOTFOUND if preference_name is null or does not refer to an existing preference

Parameters

preference_name	(I) Preference name
value_count	(O) Number of values in the value array
values	(OF) value_count Array of returned values

TC_API int PREF_ask_double_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	value_count,
		double **	values
	)

Asks all the values of the preference whose data type is "Double" at the specified location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_ask_double_values instead.

Warning: If the preference is not of type "Double", no error is returned, value_count is provided accurately but the retrieved values are 0.

Returns

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the values
value_count	(O) The number of values in the value array
values	(OF) value_count The array of values

TC_API int PREF_ask_environment_set_flag	(	const char *	preference_name,
		logical *	flag
	)

Asks the flag that authorizes a preference value to come from an environment variable.

Returns

ITK_ok on success
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) The name of the preference
flag	(O) The status for the environment set

TC_API int PREF_ask_environment_set_flags	(	int	preference_count,
		const char **	preference_names,
		logical **	flags
	)

Asks the flags that authorize preference values to come from an environment variable.

Returns

ITK_ok on success
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PREF_preferences_not_existing (error) if one of the preferences does not exist.

Parameters

preference_count	(I) The number of preferences
preference_names	(I) The array of preference names
flags	(OF) preference_count The array of statuses for the environment set

TC_API int PREF_ask_int_value	(	const char *	preference_name,
		int	index,
		int *	value
	)

Asks the value of a preference whose data type is "Integer".

The value is returned as specified at the first possible location starting at the location equal to the protection scope of the preference.

The index is used to determine which value to retrieve if the preference has multiple values. The index starts at 0. If the preference is single-valued, use the value 0.

Warning: If the preference is not of type "Integer", no error is returned and the retrieved value is 0.

Returns

ITK_ok on success
PREF_invalid_preference_name if the string is invalid ('*', empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.
PF_BOUNDS if index is negative, or if the preference has at least a value and the index goes beyond the existing number of values.

Parameters

preference_name	(I) The name of the preference
index	(I) The index of the value to retrieve
value	(O) The value

TC_API int PREF_ask_int_value_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	index,
		int *	value
	)

Asks the value of a preference whose data type is "Integer" at a given location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

The index is used to determine which value to retrieve if the preference has multiple values. The index starts at 0.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_ask_int_value instead.

Warning: If the preference is not of type "Integer", no error is returned and the retrieved value is 0.

Returns

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist or does not have any value at this location.

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the value
index	(I) The index of the value requested
value	(O) The returned value

TC_API int PREF_ask_int_values	(	const char *	preference_name,
		int *	value_count,
		int **	values
	)

Asks all the values of the preference whose data type is "Integer".
The value is returned as specified at the first possible location starting at the location equal to the protection scope of the preference.

Warning: If the preference is not of type "Double", no error is returned, value_count is provided accurately but the retrieved values are 0.

Returns

ITK_ok on success
PF_NOTFOUND if preference_name is null or does not refer to an existing preference

Parameters

preference_name	(I) Preference name
value_count	(O) Number of values in the value array
values	(OF) value_count Array of returned values

TC_API int PREF_ask_int_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	value_count,
		int **	values
	)

Asks all the values of the preference whose data type is "Integer" at the specified location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_ask_int_values instead.

Warning: If the preference is not of type "Double", no error is returned, value_count is provided accurately but the retrieved values are 0.

Returns

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the values
value_count	(O) The number of values in the value array
values	(OF) value_count The array of values

TC_API int PREF_ask_logical_value	(	const char *	preference_name,
		int	index,
		logical *	value
	)

Asks the value of a preference whose data type is "Logical".

The value is returned as specified at the first possible location starting at the location equal to the protection scope of the preference.

The index is used to determine which value to retrieve if the preference has multiple values. The index starts at 0. If the preference is single-valued, use the value 0.

Note: If using an invalid index or if the preference name refers to a preference that does not exist, no error will be returned and the value "false" will be retrieved.

Warning: If the preference is not of type "Logical", no error is returned and the retrieved value is "false".

Returns: ITK_ok always

Parameters

preference_name	(I) The name of the preference
index	(I) The index of the value to retrieve
value	(O) The value

TC_API int PREF_ask_logical_value_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	index,
		logical *	value
	)

Asks the value of a preference whose data type is "Logical" at the specified location.

Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_ask_logical_value instead.

Warning: If the preference is not of type "Logical", no error is returned and the retrieved value is "false".

Returns

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist or does not have any value at this location.

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the value
index	(I) The index of the value to retrieve
value	(O) The returned value

TC_API int PREF_ask_logical_values	(	const char *	preference_name,
		int *	value_count,
		logical **	values
	)

Asks all the values of the preference whose data type is "Logical".

The value is returned as specified at the first possible location starting at the location equal to the protection scope of the preference.

Note: If the preference name refers to a preference that does not exist, no error will be returned and the value "false" will be retrieved.

Warning: If the preference is not of type "Logical", no error is returned, value_count is provided accurately but the retrieved values are "false".

Returns

ITK_ok on success
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) Preference name
value_count	(O) Number of values in the value array
values	(OF) value_count Array of returned values

TC_API int PREF_ask_logical_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	value_count,
		logical **	values
	)

Asks the value of a preference whose data type is "Logical" at the specified location.

Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_ask_logical_values instead.

Warning: If the preference is not of type "Logical", no error is returned, value_count is provided accurately but the retrieved values are "false".

Returns

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the values
value_count	(O) The number of values in the array
values	(OF) value_count The array of values

TC_API int PREF_ask_protection_scope	(	const char *	preference_name,
		TC_preference_search_scope_t *	protection_scope
	)

Asks the protection scope for a given preference.
Possible returned values are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_system.

Returns

ITK_ok on success
PREF_invalid_protection_scope if the protection scope is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) The name of the preference
protection_scope	(O) The protection scope of the preference

TC_API int PREF_ask_protection_scopes	(	int	preference_count,
		const char **	preference_names,
		TC_preference_search_scope_t **	protection_scopes
	)

Asks the protection scope for several given preferences.
Possible returned values are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_system.

Returns

ITK_ok on success
PREF_invalid_protection_scope if the protection scope is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PREF_preferences_not_existing (error) if one of the preferences does not exist.

Parameters

preference_count	(I) The number of preferences
preference_names	(I) The array of preference names
protection_scopes	(OF) preference_count The array of protection scopes for the preferences

TC_API int PREF_ask_search_scope ( TC_preference_search_scope_t * scope )

Asks which preferences the system is considering when you ask for values.

Deprecated:: This function is deprecated and will be removed from Tc12. Please refer to the documentation on PREF_set_search_scope for more information.

Parameters

scope (O)

TC_API int PREF_ask_value_count	(	const char *	preference_name,
		int *	value_count
	)

Retrieves the number of values that exist for a particular preference name.

Note: If the preference is not defined at all, value_count will be 0.

Returns: ITK_ok always

Parameters

preference_name	(I) The name of the preference
value_count	(O) The number of values

TC_API int PREF_ask_value_count_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	value_count
	)

Retrieves the number of values that exist for a particular preference name at a specific level.
If the preference does not have an instance at the given location, the returned value count is 0.

Valid values for the location are TC_preference_user , TC_preference_role , TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

Returns

ITK_ok on success
PREF_value_cannot_be_asked_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) The number of preferences
location	(I) The location where to look for the preference
value_count	(O) The number of values at the location

TC_API int PREF_delete_definition	(	int	nb_of_preferences,
		const char **	preference_names,
		logical	delete_all_custom_definitions
	)

Deletes the customization made to the definition of the specified preferences.
If the intent is to delete the value, use PREF_delete_preference or PREF_delete_preference_at_location ITKs instead.

If the call is made with the deleteAllCustomDefinition flag set to true, then it is assumed that all custom definitions will be removed.
A custom definition is:

Any change made to the definition of a foundation preference (for instance a change in the protection scope).
Any preference (not part of the foundation preference list) that was imported.
Any preference that was created through the GUI or code API.

The preference definition will be removed, but the preference instances will not. Use the preferences_manager utility in "cleanup" mode in order to do that.

Returns

ITK_ok on success
PREF_delete_definitions_incorrect_arguments if the deleteAllCustomDefinitions flag is set to true, and the nbOfPreferences argument is not 0 or the preference_names is not a null pointer.
SA_not_a_system_administrator if the logged-in user does not have system administrator privileges.
PREF_preferences_not_existing (warning) if one or more preferences do not exist. The call will proceed with the removal of the other preference definitions though.
PREF_cannot_delete_preference_definition if one or more preferences are coming from the list of Teamcenter foundation preferences and their preference definitions have not been changed. The call will proceed with the removal of the other preference definitions though.

Parameters

nb_of_preferences	(I) The number of preference definition to delete.
preference_names	(I) The name of the preferences.
delete_all_custom_definitions	(I) If set to true, indicates to delete all the custom definitions. The nbOfPreferences will need to be set to 0, and the pointer preference_names will need to be a null pointer.

TC_API int PREF_delete_non_session_preference	(	char *	preference_name,
		tag_t	object
	)

Deletes the specified preference instance from the specified location.

The location can be any location for which the logged-in user has privileges.

If an error is encountered during the deletion of any preference, the rest of the list will be skipped.

Parameters

preference_name	(I) Name of the preference which instance is to be deleted
object	(I) User, Role or Group tag

TC_API int PREF_delete_preference ( const char * preference_name )

Deletes the specified preference instance from the location that matches the preference protection scope.

Restrictions:
If the preference being deleted is a site-protected preference, the logged-in user must have system administrative privileges.
If the preference being deleted is a group/role-protected preference, the logged-in user must have at least group administrative privileges.

Parameters

preference_name (I) Name of the preference which instance is to be deleted.

TC_API int PREF_delete_preference_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location
	)

Deletes the specified preference instance from the specified location.

The location are the ones as seen from the logged-in user.
Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
If the preference being deleted is a site-protected preference, the logged-in user must have system administrative privileges.
If the preference being deleted is a group/role-protected preference, the logged-in user must have at least group administrative privileges.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_delete_preference instead.

Returns

ITK_ok on success
PREF_insufficient_privileges if the logged-in user does not have the privilege to remove instances at the provided location.
PREF_invalid_location if the location is invalid.
PREF_instance_not_found_at_location if the location is invalid.

Parameters

preference_name	(I) Name of the preference which instance is to be deleted
location	(I) The location where to delete the preference instance

TC_API int PREF_export_preference_list	(	int	preference_count,
		char **	preference_names,
		TC_preference_search_scope_t	location,
		const char *	output_file_name
	)

Exports the specified preferences from the specified location to the specified output file.
Nothing will be exported if the named preferences are not found under the specified location.

The possible values for the location parameter are:

TC_preference_user	Exports the specified preferences from the user location.
TC_preference_role	Exports the specified preferences from the user location.
TC_preference_group	Exports the specified preferences from the group location.
TC_preference_site	Exports the specified preferences from the site location.

The user/role/group are the ones for the current logged-in user.

Parameters

preference_count	(I) Number of preferences to export
preference_names	(I) Name of the preferences to export
location	(I) Location of the preferences to export
output_file_name	(I) Output export file name

TC_API int PREF_export_preferences	(	TC_preference_search_scope_t	location,
		const char *	output_file_name
	)

Exports all the preferences at the specified location to the specified output file.
Nothing will be exported if there are no preferences under the specified scope.
(For e.x. if the scope is specified as TC_preference_user, all the user preferences for the current logged in user would be exported.)

The possible values for the location parameter are:

TC_preference_user	Exports all the preferences at the user location.
TC_preference_role	Exports all the preferences at the user location.
TC_preference_group	Exports all the preferences at the group location.
TC_preference_site	Exports all the preferences at the site location.

The user/role/group are the ones for the current logged-in user.

Parameters

location	(I) Location to be considered for export
output_file_name	(I) Output export file name

TC_API int PREF_export_preferences_with_category	(	TC_preference_search_scope_t	location,
		int	number_of_categories,
		char **	categories,
		const char *	output_file_name
	)

Exports all the preferences belonging to the specified categories from the specified location scope to the specified output file.
Nothing will be exported if there are no preferences matching the criteria at the specified location.
E.g. if the specified location is TC_preference_user, all the user preferences for the current logged-in user will be exported.

The possible values for the location parameter are:

TC_preference_user	Exports all the preferences at the user location.
TC_preference_role	Exports all the preferences at the role location.
TC_preference_group	Exports all the preferences at the group location.
TC_preference_site	Exports all the preferences at the site location.

The user/role/group are the ones for the current logged-in user.

Parameters

location	(I) Location to be considered for export
number_of_categories	(I) Number of categories
categories	(I) Categories to be considered for export
output_file_name	(I) Output export file name

TC_API int PREF_import_preferences	(	TC_preference_search_scope_t	location,
		const char *	input_xml,
		PREF_import_actions_t	action
	)

Imports all the preferences in the specified xml file at the specified location.

The possible values for the location parameter are:

TC_preference_user	Imports the preferences in the xml file at the user location.
TC_preference_role	Imports the preferences in the xml file at the role location.
TC_preference_group	Imports the preferences in the xml file at the group location.
TC_preference_site	Imports the preferences in the xml file at the site location.

The user/role/group are the ones for the current logged-in user.

The action parameter specifies the action to be taken in the event of a preference existing in the database. The possible values for the action parameter are:

PREF_import_action_skip	Skips the preference and does not do any further processing for this preference.
PREF_import_action_override	Overrides the values of the preference in the database with the values in the specified xml file.
PREF_import_action_merge	Merges the values for the preference in the database with the values in the specified xml file. This merge is a simple union of the values in the database and the xml file.

Restrictions:
If the specified location TC_preference_site, the logged-in user must have system administrative privileges.
If the specified location is TC_preference_group or TC_preference_role, the logged-in user must have at least group administrative privileges.

Parameters

location	(I) Location where to import the preferences
input_xml	(I) Path to the input XML file name
action	(I) Action to be considered in the event of conflict with the information already present in the database

TC_API int PREF_import_preferences_with_category	(	TC_preference_search_scope_t	location,
		const char *	input_xml,
		int	number_of_categories,
		char **	category_names,
		PREF_import_actions_t	action
	)

Imports the preferences in the specified xml file, only from the specified categories, and into the specified location.

The possible values for the location parameter are:

TC_preference_user	Imports the preferences in the xml file at the user location.
TC_preference_role	Imports the preferences in the xml file at the role location.
TC_preference_group	Imports the preferences in the xml file at the group location.
TC_preference_site	Imports the preferences in the xml file at the site location.

The action parameter specifies the action to be taken in the event of a preference existing in the database. The possible values for the action parameter are:

PREF_import_action_skip	Skips the preference and does not do any further processing for this preference.
PREF_import_action_override	Overrides the values of the preference in the database with the values in the specified xml file.
PREF_import_action_merge	Merges the values for the preference in the database with the values in the specified xml file. This merge is a simple union of the values in the database and the xml file.

Restrictions:
If the specified location is TC_preference_site, the logged-in user must have system administrative privileges.
If the specified location is TC_preference_group or TC_preference_role, the logged-in user must have at least group administrative privileges.

Parameters

location	(I) Location where to import the preferences
input_xml	(I) Path to the input XML file name
number_of_categories	(I) Number of categories given as input
category_names	(I) Categories to be considered for import
action	(I) Action to be considered in the event of conflict with the information already present in the database

TC_API int PREF_initialize ( void )

Loads all of the values from the preference files.

TC_API int PREF_lock_site_preferences ( )

Locks site preferences.
Use this to have exclusive modification privileges to site preferences.
Once the modifications are done, use PREF_unlock_site_preferences to unlock.

Restrictions: The logged-in user must have site administrative privileges.

Returns

ITK_ok on success
PREF_insufficient_privileges if the user is not a system administrator.
PF_LOCKED_BY_SAME_USER if the current user has already locked the site preferences.
PF_LOCKED_BY_ANOTHER_USER if another user has already locked the site preferences.

TC_API int PREF_refresh ( const char * preference_name )

Refreshes those parts of the current Teamcenter session (if there is one) whose state depends on the value of the named preference.
Use of PREF_set_xxx functions alone affects only future sessions. Subsequent use of this function affects the current session also.

Restrictions: This function is currently only supported for the following preferences: WS_Menu_Entry_Suppression ,PSE_Menu_Entry_Suppression

Parameters

preference_name (I) Name of preference to refresh

TC_API int PREF_reinitialize ( )

Re-reads any appropriate preference files to reflect updates from outside the session

TC_API int PREF_set_char_values	(	const char *	preference_name,
		int	value_count,
		char *	values[]
	)

Sets the values of a preference whose data type is "String".
This ITK can be used to set preferences of type other than "String" (i.e. "Integer", "Double", "Logical"). However, using the other flavors ITKs (PREF_set_int_values, PREF_set_double_values, PREF_set_logical_values) is encouraged.

Note: If the preference does not defined, its definition will be created and an instance with the provided values will be created at the User location.

Returns

ITK_ok on success
PREF_value_cannot_be_set_at_location if the user does not have privileges to set the preference value (e.g. a site-protected preference)
PF_NULL_VALUE if value_count is stricly positive and values is a null pointer.
PF_NULL_VALUE if any value in values is a null string
PREF_not_a_int_value if the preference data type is "Integer" and one of the values is not an integer.
PREF_not_a_double_value if he preference data type is "Double" and one of the values is not a double.
PREF_not_a_logical_value if the value is not a logical.

Parameters

preference_name	(I) The name of the preference
value_count	(I) The number of values
values	(I) value_count The array of values

TC_API int PREF_set_char_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	value_count,
		char *	values[]
	)

Sets the value(s) of a preference whose data type is "String" at a specific level.

Valid values for the locations are TC_preference_user , TC_preference_role , TC_preference_group , and TC_preference_site.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_set_char_values instead.

Returns

ITK_ok on success
PREF_value_cannot_be_set_at_location if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location if the location is invalid.
PREF_insufficient_privileges if the logged-in user does not have the privilege to write at the given location:
1. Only system administrators can write at the site location
2. Only group administrators can write at the group or role location
3. Normal users can only write at the user location
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PREF_not_a_int_value if the preference data type is "Integer" and one of the values is not an integer.
PREF_not_a_double_value if he preference data type is "Double" and one of the values is not a double.
PREF_not_a_logical_value if the value is not a logical.

Warning

If the preference does not exist, no error is returned. Instead the preference will be created.
The value of the "location" argument will also become the protection scope.
However, the system will match what is possible:

if the logged-in user is a site administrator, any value can be given to the protection scope. The preference value will be set at the location.
if the logged-in user is a group administrator, the location can be anything but "TC_preference_site". If the value is "TC_preference_site", the protection scope of the preference and the location of the value will be set as "TC_preference_user".
if the logged-in user is a regular user, the protection scope of the preference and the location of the value will be set as "TC_preference_user".

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to set the values
value_count	(I) The number of values in the value array
values	(I) The array of values

TC_API int PREF_set_definition	(	const char *	preference_name,
		PREF_preference_object_t	preference_object,
		logical	env_variable_enabled
	)

Creates or changes a preference according to a PREF_preference_object_t structure.

If the preference does not already exist in the database, all the declaration data will be needed, otherwise an error (as explained below) will be returned.

In the input structure:

preferenceName
- PREF_missing_preference_name, if the string is empty.
- PREF_invalid_preference_name, if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
preferenceCategory
The name of the category where the preference is sorted.
This can be changed only for non-OOTB preferences.
If the string is empty, the parameter will not be taken into account. However, in case the preference has not been created yet, it will be assumed that the preference will go under the General category.
If the string is not empty, the code will consider this to be a category modification. Therefore:
- PREF_parameter_value_not_applicable_to_ootb_preferences, in case the value is different from the current value and the preference is an OOTB preference.
- PREF_invalid_definition_value will also be returned if the category does not exist yet in the system.
preferenceDescription
The description associated with the preference.
- If the string is empty, the parameter will not be taken into account.
  However, in case the preference has not been created yet, this parameter is mandatory otherwise the error PREF_missing_definition_parameter is returned.
- If the string is not empty, the code will consider this to be a description modification.
  Therefore, an error PREF_parameter_value_not_applicable_to_ootb_preferences, in case the value is different from the current value and the preference is an OOTB preference.
preferenceScope
The protection scope: valid values are User, Role, Group, Site and System.
- If the preference does not exist, this information is mandatory.
  PREF_invalid_definition_value will be returned if the protection scope is invalid.
- If the preference exists:
  If the string is empty, the parameter will not be taken into account.
  If the string is not empty, the code will consider this to be a modification. Therefore:
  - PREF_invalid_definition_value, if the protection scope is invalid.
  - PREF_no_protection_scope_change_on_ootb_system_preference will also be returned in case the value is different from the current value and the preference is an OOTB preference with protection scope of System.
preferenceType
Defines the type of the preference: PREF_preference_string, PREF_preference_logical, PREF_preference_integer, PREF_preference_double, PREF_preference_date.
If the preference does not exist, this piece of information will be needed.
If the preference exists and is an OOTB preference, this argument is discarded.
If the preference exists and is not an OOTB preference, the change will be taken into consideration. If the conversion from the old type to the new one is not possible, any further call to a "getPreferences" operation will revert to giving the value at the higher level instead of returning an error.
contextValues
The context information is discarded.

Returns

ITK_ok on success
PREF_user_not_system_admin if the logged-in user does not have the system privilege.

Parameters

preference_name	(I) The name of the preference
preference_object	(I) The preference object describing the preference to add
env_variable_enabled	(I) Defines if the value for the given preference can come from the environment variable.

TC_API int PREF_set_double_values	(	const char *	preference_name,
		int	value_count,
		double	values[]
	)

Sets the value(s) of a preference whose data type is "Double".

Note: If the preference does not defined, its definition will be created and an instance with the provided values will be created at the User location.

Returns

ITK_ok on success
PREF_value_cannot_be_set_at_location if the user does not have privileges to set the preference value (e.g. a site-protected preference)

Parameters

preference_name	(I) The name of the preference
value_count	(I) The number of values
values	(I) value_count The array of values

TC_API int PREF_set_double_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	value_count,
		double	values[]
	)

Sets the value(s) of a preference whose data type is "Double" at a specific location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_set_double_values instead.

Returns

ITK_ok on success
PREF_invalid_location if the location is invalid.
PREF_value_cannot_be_set_at_location if the specified level does not match the existing protection scope for the preference.
PREF_insufficient_privileges if the logged-in user does not have the privilege to write at the given location:
1. Only system administrators can write at the site location.
2. Only group administrators can write at the group or role location.
3. Normal users can only write at the user location.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).

Warning

If the preference does not exist, no error is returned. Instead the preference will be created.
The value of the "location" argument will also become the protection scope.
However, the system will match what is possible:

if the logged-in user is a site administrator, any value can be given to the protection scope. The preference value will be set at the location.
if the logged-in user is a group administrator, the location can be anything but "TC_preference_site". If the value is "TC_preference_site", the protection scope of the preference and the location of the value will be set as "TC_preference_user".
if the logged-in user is a regular user, the protection scope of the preference and the location of the value will be set as "TC_preference_user".

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to set the value
value_count	(I) The number of values in the value array
values	(I) The array of values

TC_API int PREF_set_environment_set_flag	(	const char *	preference_name,
		logical	flag
	)

Sets the flag that authorizes a preference value to come from an environment variable.
Valid values are true (allow) or false.

Returns

ITK_ok on success
PREF_user_not_system_admin if the user of is not a system administrator.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND if the preference does not exist.

Parameters

preference_name	(I) The name of the preference
flag	(I) The status for the environment set

TC_API int PREF_set_environment_set_flags	(	int	preference_count,
		const char **	preference_names,
		const logical	flag[]
	)

Sets the flag that authorizes preference values to come from an environment variable.
Valid values are true (allow) or false.

Returns

ITK_ok on success
PREF_user_not_system_admin if the user of is not a system administrator.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PREF_preferences_not_existing (warning) if one of the preferences does not exist.

Parameters

preference_count	(I) The number of preferences
preference_names	(I) The array of preference names
flag	(I) The array of statuses for the environment set

TC_API int PREF_set_int_values	(	const char *	preference_name,
		int	value_count,
		int	values[]
	)

Sets the value(s) of a preference whose data type is "Integer".

Note: If the preference does not defined, its definition will be created and an instance with the provided values will be created at the User location.

Returns

ITK_ok on success
PREF_value_cannot_be_set_at_location if the user does not have privileges to set the preference value (e.g. a site-protected preference)

Parameters

preference_name	(I) The name of the preference
value_count	(I) The number of values
values	(I) value_count The array of values

TC_API int PREF_set_int_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	value_count,
		int	values[]
	)

Sets the value(s) of a preference whose data type is "Integer" at a specific location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_set_int_values instead.

Returns

ITK_ok on success
PREF_invalid_location if the location is invalid.
PREF_value_cannot_be_set_at_location if the specified level does not match the existing protection scope for the preference.
PREF_insufficient_privileges if the logged-in user does not have the privilege to write at the given location:
1. Only system administrators can write at the site location
2. Only group administrators can write at the group or role location
3. Normal users can only write at the user location
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PREF_not_a_int_value if one of the values is not an integer.

Warning

If the preference does not exist, no error is returned. Instead the preference will be created.
The value of the "location" argument will also become the protection scope.
However, the system will match what is possible:

if the logged-in user is a site administrator, any value can be given to the protection scope. The preference value will be set at the location.
if the logged-in user is a group administrator, the location can be anything but "TC_preference_site". If the value is "TC_preference_site", the protection scope of the preference and the location of the value will be set as "TC_preference_user".
if the logged-in user is a regular user, the protection scope of the preference and the location of the value will be set as "TC_preference_user".

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to set the value
value_count	(I) The number of values in the value array
values	(I) The array of values

TC_API int PREF_set_logical_value	(	const char *	preference_name,
		logical	value
	)

Sets the value of a preference whose data type is "Logical".

Note: If the preference does not defined, its definition will be created and an instance with the provided values will be created at the User location.; The value will be "false" if an invalid preference name is provided.

Returns

ITK_ok always

Parameters

preference_name	(I) The name of the preference
value	(I) The value

TC_API int PREF_set_logical_values	(	const char *	preference_name,
		int	value_count,
		logical	values[]
	)

Sets the values of a preference whose data type is "Logical".

Returns

ITK_ok on success
PREF_invalid_preference_name if the string is invalid ('*', empty string or a string only composed of any number of ' ' characters for instance).
PREF_insufficient_privileges if the logged-in user does not have the privileges:
1. Only system administrators can write at the site location.
2. Only group administrators can write at the group or role location.
3. Normal users can only write at the user location.
PREF_not_a_logical_value if one of the values is not a logical.

Warning: The value is set at the location which is the protection scope if the preference definition exist or else a runtime definition is created.

Parameters

preference_name	(I) The name of the preference
value_count	(I) The number of values in the array
values	(I) The array of values

TC_API int PREF_set_logical_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	value_count,
		logical	values[]
	)

Sets the values of a preference whose data type is "Logical" at the specified location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

Note: Do not use this API unless very knowledgeable about preferences. Otherwise, please use PREF_set_logical_values instead.

Returns

ITK_ok on success
PREF_invalid_location if the location is invalid.
PREF_value_cannot_be_set_at_location if the specified level does not match the existing protection scope for the preference.
PREF_insufficient_privileges if the logged-in user does not have the privilege to write at the given location:
1. Only system administrators can write at the site location.
2. Only group administrators can write at the group or role location.
3. Normal users can only write at the user location.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PREF_not_a_logical_value, if one of the values is not a logical.

Warning

If the preference does not exist, no error is returned. Instead the preference will be created. br>The value of the "location" argument will also become the protection scope.
However, the system will match what is possible:

if the logged-in user is a site administrator, any value can be given to the protection scope. The preference value will be set at the location.
if the logged-in user is a group administrator, the location can be anything but "TC_preference_site". If the value is "TC_preference_site", the protection scope of the preference and the location of the value will be set as "TC_preference_user".
if the logged-in user is a regular user, the protection scope of the preference and the location of the value will be set as "TC_preference_user".

Parameters

preference_name	(I) The name of the preference
location	(I) The location where to set the value
value_count	(I) The number of values in the array
values	(I) The array of values

TC_API int PREF_set_protection_scope	(	const char *	preference_name,
		TC_preference_search_scope_t	protection_scope
	)

Sets the protection scope for a given preference.
Valid values for the protection scope are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_system.
The TC_preference_system value is only to be used to convert a hierarchical preference to a System preference: this is only possible for non out-of-the-box preferences.

Returns

ITK_ok on success
PREF_invalid_protection_scope if the protection scope is invalid.
PREF_user_not_system_admin if the user of is not a system administrator.
PREF_cannot_change_protection_scope_of_system_pref if the preference is an out-of-the-box system preference.
PREF_cannot_convert_to_system_pref if the preference is an out-of-the-box hierarchical preference.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND will be returned if the preference does not exist.

Parameters

preference_name	(I) The name of the preference
protection_scope	(I) The new protection scope

TC_API int PREF_set_protection_scopes	(	int	preference_count,
		const char **	preference_names,
		TC_preference_search_scope_t	protection_scopes[]
	)

Sets the protection scope for several given preferences.
Valid values for the protection scopes are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_system.

Returns

ITK_ok on success
PREF_invalid_protection_scope if the protection scope is invalid.
PREF_user_not_system_admin if the user of is not a system administrator.
PREF_cannot_change_protection_scope_of_system_prefs if one of the preferences is an out-of-the-box system preference.
PREF_cannot_convert_to_system_prefs if the preference is an out-of-the-box hierarchical preference.
PREF_invalid_preference_name if the string is invalid ("*", empty string or a string only composed of any number of ' ' characters for instance).
PREF_preferences_not_existing (warning) if one of the preferences does not exist.

Parameters

preference_count	(I) The number of preferences
preference_names	(I) The array of preference names
protection_scopes	(I) The array of new protection scopes

TC_API int PREF_set_search_scope ( TC_preference_search_scope_t scope )

Specifies which preferences you want to consider when asking for values. The possible values for this are:

TC_preference_all	All preferences.
TC_preference_role	Role preferences.
TC_preference_user	User preferences.
TC_preference_group	Group preferences.
TC_preference_site	Site preferences.

Deprecated:: This function is deprecated and will be removed from Tc12. There is no replacement to this ITK, because the declared protection scope of the preference will enable the Preferences code layer to determine where to start looking for a preference value.
Therefore, starting Tc10.0, call the following:

to retrieve the preference value, simply call the PREF_ask_<type>_value or PREF_ask_<type>_values ITKs.
to set the preference value, simply call the PREF_set_<type>_values ITK.

If there is a need to obtain or set the preference value at a very specific location (and only then), use the PREF_ask/set_<type>_value/values_at_location ITKs.

Parameters

scope (I)

TC_API int PREF_unlock_site_preferences ( )

Unlocks site preferences.

Restrictions: The logged-in user must have site administrative privileges.

Returns

ITK_ok on success
PREF_insufficient_privileges if the user is not a system administrator.
PF_NOT_LOCKED if the site preference is not locked.

Enumerations
enum	PREF_import_actions_e { PREF_import_action_skip, PREF_import_action_override, PREF_import_action_merge }

enum	PREF_preference_type_e { PREF_preference_string, PREF_preference_logical, PREF_preference_integer, PREF_preference_double, PREF_preference_date }

enum	TC_preference_search_scope_e { TC_preference_all, TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site, TC_preference_system, TC_preference_cots_location, TC_preference_overlay_location, TC_preference_env_variable_location }

Data Structures

Typedefs

Enumerations

Initialization of Preferences module

Preferences Protection Scope

Preferences Environment Enabled Information

Preferences Count

String Preferences

Integer Preferences

Double Preferences

Logical Preferences

Preferences Definitions

Preferences Import and Export

Deleting Preferences Instances

Preferences Refresh and Lock

Deprecated APIs

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation