# KIM Preferences Documentation

## Functions

- kim_error kim_preferences_create (kim_preferences *out_preferences)
    Create a new preferences object from the current user's preferences.
- kim_error kim_preferences_copy (kim_preferences *out_preferences, kim_preferences in_preferences)
    Copy a preferences object.
- kim_error kim_preferences_set_options (kim_preferences io_preferences, kim_options in_options)
    Set the user's preferred options.
- kim_error kim_preferences_get_options (kim_preferences in_preferences, kim_options *out_options)
    Get the user's preferred options.
- kim_error kim_preferences_set_remember_options (kim_preferences io_preferences, kim_boolean in_remember_options)
    Set whether or not to remember the last options the user used to acquire a credential.
- kim_error kim_preferences_get_remember_options (kim_preferences in_preferences, kim_boolean *out_remember_options)
    Get whether or not to remember the last options the user used to acquire a credential.
- kim_error kim_preferences_set_client_identity (kim_preferences io_preferences, kim_identity in_client_identity)
    Set the user's preferred client identity.
- kim_error kim_preferences_get_client_identity (kim_preferences in_preferences, kim_identity *out_client_identity)
    Get the user's preferred client identity.
- kim_error kim_preferences_set_remember_client_identity (kim_preferences io_preferences, kim_boolean in_remember_client_identity)
    Set whether or not to remember the last client identity the user acquired a credential for.
- kim_error kim_preferences_get_remember_client_identity (kim_preferences in_preferences, kim_boolean *out_remember_client_identity)
    Get whether or not to remember the last client identity the user acquired a credential for.
- kim_error kim_preferences_set_minimum_lifetime (kim_preferences io_preferences, kim_lifetime in_minimum_lifetime)
    Set the minimum credential lifetime for GUI credential lifetime controls.
- kim_error kim_preferences_get_minimum_lifetime (kim_preferences in_preferences, kim_lifetime *out_minimum_lifetime)
    Get the minimum credential lifetime for GUI credential lifetime controls.
- kim_error kim_preferences_set_maximum_lifetime (kim_preferences io_preferences, kim_lifetime in_maximum_lifetime)
    Set the maximum credential lifetime for GUI credential lifetime controls.
- kim_error kim_preferences_get_maximum_lifetime (kim_preferences in_preferences, kim_lifetime *out_maximum_lifetime)
    Get the maximum credential lifetime for GUI credential lifetime controls.
- kim_error kim_preferences_set_minimum_renewal_lifetime (kim_preferences io_preferences, kim_lifetime in_minimum_renewal_lifetime)
    Set the minimum credential renewal lifetime for GUI credential lifetime controls.
- kim_error kim_preferences_get_minimum_renewal_lifetime (kim_preferences in_preferences, kim_lifetime *out_minimum_renewal_lifetime)
    Get the minimum credential renewal lifetime for GUI credential lifetime controls.
- kim_error kim_preferences_set_maximum_renewal_lifetime (kim_preferences io_preferences, kim_lifetime in_maximum_renewal_lifetime)
    Set the maximum credential renewal lifetime for GUI credential lifetime controls.
- kim_error kim_preferences_get_maximum_renewal_lifetime (kim_preferences in_preferences, kim_lifetime *out_maximum_renewal_lifetime)
    Get the maximum credential renewal lifetime for GUI credential lifetime controls.
- kim_error kim_preferences_get_number_of_favorite_identities (kim_preferences in_preferences, kim_count *out_number_of_identities)
    Get the number of favorite identities in a preferences object.
- kim_error kim_preferences_get_favorite_identity_at_index (kim_preferences in_preferences, kim_count in_index, kim_identity *out_identity, kim_options *out_options)
    Get the Nth favorite identity in a preferences object.
- kim_error kim_preferences_add_favorite_identity (kim_preferences io_preferences, kim_identity in_identity, kim_options in_options)
    Add a favorite identity to a preferences object.
- kim_error kim_preferences_remove_favorite_identity (kim_preferences io_preferences, kim_identity in_identity)
    Remove a favorite identity from a preferences object.
- kim_error kim_preferences_remove_all_favorite_identities (kim_preferences io_preferences)
    Remove all favorite identities in a preferences object.
- kim_error kim_preferences_synchronize (kim_preferences in_preferences)
    Synchronize a preferences object with the user's preferences, writing pending changes and reading any changes applied by other processes.
- void kim_preferences_free (kim_preferences *io_preferences)
    Free memory associated with a preferences object.

## Function Documentation

kim_error kim_preferences_create | ( | kim_preferences * | out_preferences | ) |

Create a new preferences object from the current user's preferences.

Parameters:

  | out_preferences | on exit, a new preferences object. Must be freed with kim_preferences_free().

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_preferences_copy | ( | kim_preferences * | out_preferences,
|  | kim_preferences | in_preferences |
| ) |  |  |

Copy a preferences object.

Parameters:

  | out_preferences | on exit, a new preferences object which is a copy of in_preferences. Must be freed with kim_preferences_free().
  | in_preferences | a preferences object.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_preferences_set_options | ( | kim_preferences | io_preferences,
|  | kim_options | in_options |
| ) |  |  |

Set the user's preferred options.

Parameters:

  | io_preferences | a preferences object to modify.
  | in_options | an options object.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_get_options()

kim_error kim_preferences_get_options | ( | kim_preferences | in_preferences,
|  | kim_options * | out_options |
| ) |  |  |

Get the user's preferred options.

Parameters:

  | in_preferences | a preferences object.
  | out_options | on exit, the options specified in in_preferences. May be KIM_OPTIONS_DEFAULT. If not, must be freed with kim_options_free().

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_set_options()

kim_error kim_preferences_set_remember_options | ( | kim_preferences | io_preferences,
|  | kim_boolean | in_remember_options |
| ) |  |  |

Set whether or not to remember the last options the user used to acquire a credential.

Parameters:

  | io_preferences | a preferences object to modify.
  | in_remember_options | a boolean value indicating whether or not to remember the last options used to acquire a credential.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_get_remember_options()

kim_error kim_preferences_get_remember_options | ( | kim_preferences | in_preferences,
|  | kim_boolean * | out_remember_options |
| ) |  |  |

Get whether or not to remember the last options the user used to acquire a credential.

Parameters:

  | in_preferences | a preferences object.
  | out_remember_options | on exit, a boolean value indicating whether or in_preferences will remember the last options used to acquire a credential.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_set_remember_options()

kim_error kim_preferences_set_client_identity | ( | kim_preferences | io_preferences,
|  | kim_identity | in_client_identity |
| ) |  |  |

Set the user's preferred client identity.

Parameters:

  | io_preferences | a preferences object to modify.
  | in_client_identity | a client identity object.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_get_client_identity()

kim_error kim_preferences_get_client_identity | ( | kim_preferences | in_preferences,
|  | kim_identity * | out_client_identity |
| ) |  |  |

Get the user's preferred client identity.

Parameters:

  | in_preferences | a preferences object.
  | out_client_identity | on exit, the client identity specified in in_preferences. Must be freed with kim_identity_free().

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_set_client_identity()

kim_error kim_preferences_set_remember_client_identity | ( | kim_preferences | io_preferences,
|  | kim_boolean | in_remember_client_identity |
| ) |  |  |

Set whether or not to remember the last client identity the user acquired a credential for.

Parameters:

  | io_preferences | a preferences object to modify.
  | in_remember_client_identity | a boolean value indicating whether or not to remember the last client identity for which a credential was acquired.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_get_remember_client_identity()

kim_error kim_preferences_get_remember_client_identity | ( | kim_preferences | in_preferences,
|  | kim_boolean * | out_remember_client_identity |
| ) |  |  |

Get whether or not to remember the last client identity the user acquired a credential for.

Parameters:

  | in_preferences | a preferences object.
  | out_remember_client_identity | on exit, a boolean value indicating whether or in_preferences will remember the last client identity for which a credential was acquired.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_set_remember_client_identity()

kim_error kim_preferences_set_minimum_lifetime | ( | kim_preferences | io_preferences,
|  | kim_lifetime | in_minimum_lifetime |
| ) |  |  |

Set the minimum credential lifetime for GUI credential lifetime controls.

Parameters:

  | io_preferences | a preferences object to modify.
  | in_minimum_lifetime | a minimum lifetime indicating how small a lifetime the GUI tools should allow the user to specify for credentials.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_get_minimum_lifetime()

kim_error kim_preferences_get_minimum_lifetime | ( | kim_preferences | in_preferences,
|  | kim_lifetime * | out_minimum_lifetime |
| ) |  |  |

Get the minimum credential lifetime for GUI credential lifetime controls.

Parameters:

  | in_preferences | a preferences object.
  | out_minimum_lifetime | on exit, the minimum lifetime that GUI tools will allow the user to specify for credentials.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_set_minimum_lifetime()

kim_error kim_preferences_set_maximum_lifetime | ( | kim_preferences | io_preferences,
|  | kim_lifetime | in_maximum_lifetime |
| ) |  |  |

Set the maximum credential lifetime for GUI credential lifetime controls.

Parameters:

  | io_preferences | a preferences object to modify.
  | in_maximum_lifetime | a maximum lifetime indicating how large a lifetime the GUI tools should allow the user to specify for credentials.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_get_maximum_lifetime()

kim_error kim_preferences_get_maximum_lifetime | ( | kim_preferences | in_preferences,
|  | kim_lifetime * | out_maximum_lifetime |
| ) |  |  |

Get the maximum credential lifetime for GUI credential lifetime controls.

Parameters:

  | in_preferences | a preferences object.
  | out_maximum_lifetime | on exit, the maximum lifetime that GUI tools will allow the user to specify for credentials.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_set_maximum_lifetime()

kim_error kim_preferences_set_minimum_renewal_lifetime | ( | kim_preferences | io_preferences,
|  | kim_lifetime | in_minimum_renewal_lifetime |
| ) |  |  |

Set the minimum credential renewal lifetime for GUI credential lifetime controls.

Parameters:

  | io_preferences | a preferences object to modify.
  | in_minimum_renewal_lifetime | a minimum lifetime indicating how small a lifetime the GUI tools should allow the user to specify for credential renewal.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_get_minimum_renewal_lifetime()

kim_error kim_preferences_get_minimum_renewal_lifetime | ( | kim_preferences | in_preferences,
|  | kim_lifetime * | out_minimum_renewal_lifetime |
| ) |  |  |

Get the minimum credential renewal lifetime for GUI credential lifetime controls.

Parameters:

  | in_preferences | a preferences object.
  | out_minimum_renewal_lifetime | on exit, the minimum lifetime that GUI tools will allow the user to specify for credential renewal.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_set_minimum_renewal_lifetime()

kim_error kim_preferences_set_maximum_renewal_lifetime | ( | kim_preferences | io_preferences,
|  | kim_lifetime | in_maximum_renewal_lifetime |
| ) |  |  |

Set the maximum credential renewal lifetime for GUI credential lifetime controls.

Parameters:

  | io_preferences | a preferences object to modify.
  | in_maximum_renewal_lifetime | a maximum lifetime indicating how large a lifetime the GUI tools should allow the user to specify for credential renewal.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_get_minimum_renewal_lifetime()

kim_error kim_preferences_get_maximum_renewal_lifetime | ( | kim_preferences | in_preferences,
|  | kim_lifetime * | out_maximum_renewal_lifetime |
| ) |  |  |

Get the maximum credential renewal lifetime for GUI credential lifetime controls.

Parameters:

  | in_preferences | a preferences object.
  | out_maximum_renewal_lifetime | on exit, the maximum lifetime that GUI tools will allow the user to specify for credential renewal.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_preferences_set_minimum_renewal_lifetime()

kim_error kim_preferences_get_number_of_favorite_identities | ( | kim_preferences | in_preferences,
|  | kim_count * | out_number_of_identities |
| ) |  |  |

Get the number of favorite identities in a preferences object.

Parameters:

  | in_preferences | a preferences object.
  | out_number_of_identities | on exit, the number of identities in in_preferences.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_preferences_get_favorite_identity_at_index | ( | kim_preferences | in_preferences,
|  | kim_count | in_index,
|  | kim_identity * | out_identity,
|  | kim_options * | out_options |
| ) |  |  |

Get the Nth favorite identity in a preferences object.

Parameters:

  | in_preferences | a preferences object.
  | in_index | a index into the identities list (starting at 0).
  | out_identity | on exit, the identity at in_index in in_preferences. Must be freed with kim_string_free().
  | out_options | on exit, the options associated with identity at in_index in in_favorite_identities. May be KIM_OPTIONS_DEFAULT. Pass NULL if you do not want the options associated with the identity. Must be freed with kim_options_free().

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_preferences_add_favorite_identity | ( | kim_preferences | io_preferences,
|  | kim_identity | in_identity,
|  | kim_options | in_options |
| ) |  |  |

Add a favorite identity to a preferences object.

Parameters:

  | io_preferences | a preferences object.
  | in_identity | an identity to add to io_preferences.
  | in_options | options which will be associated with that identity. Use KIM_OPTIONS_DEFAULT if the identity should use the user's default options.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_preferences_remove_favorite_identity | ( | kim_preferences | io_preferences,
|  | kim_identity | in_identity |
| ) |  |  |

Remove a favorite identity from a preferences object.

Parameters:

  | io_preferences | a preferences object.
  | in_identity | an identity to remove from io_preferences.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_preferences_remove_all_favorite_identities | ( | kim_preferences | io_preferences | ) |

Remove all favorite identities in a preferences object.

Parameters:

  | io_preferences | a preferences object.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_preferences_synchronize | ( | kim_preferences | in_preferences | ) |

Synchronize a preferences object with the user's preferences, writing pending changes and reading any changes applied by other processes.

Parameters:

  | in_preferences | a preferences object.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

void kim_preferences_free | ( | kim_preferences * | io_preferences | ) |

Free memory associated with a preferences object.

Parameters:

  | io_preferences | the preferences object to be freed. Set to NULL on exit.