Delta Block Function Arguments and Accessor/Mutator Functions

The transformation function is defined by PrgT_Preference_Transform_Function.

Several accessor and mutator functions are provided. The two mutators prg_preference_transform_destination_value_set() and prg_preference_transform_destination_value_set() can be used to specify a new tag and a new value for the transformed preference.

Note that clients of this interface should allocate memory for any data that is passed to the mutators using the prg_* family of memory allocation functions. In addition, they should relinquish ownership of the allocated data, i.e., the data should be destroyed by the migration framework.

Note that if a delta block does not specify a source version field, the prg_preference_transform_source_version_get() function returns the version of the preferences file from which preferences are being migrated, but the prg_preference_transform_destination_version_get() function returns the currently installed version number.

The following are the preference migration functions:

Accessor

  • prg_preference_transform_tag_get() – Returns the preference's tag, which is the low level name of the preference provided in a Delta block in a .pref file.
  • prg_preference_transform_source_version_get() – Returns the version of the source preferences file from which this preference is being migrated.
  • prg_preference_transform_destination_version_get() – Returns the version to which this preference is being migrated.
  • prg_preference_transform_arguments_get() – Returns the arguments that were specified as part of the transformation in the Delta block as a list of strings.
  • prg_preference_transform_source_value_get() – Returns the value of the preference in the source preferences file as a list of strings. If the preference is scalar, a list with just one element will be returned.

Mutators

  • prg_preference_transform_destination_tag_set() – Sets the new tag for the preference. This new tag will be used to write out the preference in the new preferences file. If not set, the old tag will be used instead.
  • prg_preference_transform_destination_value_set() – Sets the new value for the preference. This new value will be used to write out the preference in the new preferences file.
  • prg_preference_transform_error_message_set() – Sets a message describing the cause of the failure, if your custom transformation function returns a failure. The message will appear next to the preference in “Preferences Migration” log.