KIM Preferences Documentation

Functions

Function Documentation

kim_error_t kim_preferences_create (  kim_preferences_t *  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 object representing the failure.

kim_error_t kim_preferences_copy (  kim_preferences_t *  out_preferences,
kim_preferences_t  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_favorite_realms_free().
in_preferences a preferences object.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_preferences_set_options (  kim_preferences_t  io_preferences,
kim_options_t  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 object representing the failure.
See also:
kim_preferences_get_options()

kim_error_t kim_preferences_get_options (  kim_preferences_t  in_preferences,
kim_options_t *  out_options
) 
 

Get the user's preferred options.

Parameters:
in_preferences a preferences object.
out_options on exit, the options specified in in_preferences. Must be freed with kim_options_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_preferences_set_options()

kim_error_t kim_preferences_set_remember_options (  kim_preferences_t  io_preferences,
kim_boolean_t  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 object representing the failure.
See also:
kim_preferences_get_remember_options()

kim_error_t kim_preferences_get_remember_options (  kim_preferences_t  in_preferences,
kim_boolean_t *  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 object representing the failure.
See also:
kim_preferences_set_remember_options()

kim_error_t kim_preferences_set_client_identity (  kim_preferences_t  io_preferences,
kim_identity_t  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 object representing the failure.
See also:
kim_preferences_get_client_identity()

kim_error_t kim_preferences_get_client_identity (  kim_preferences_t  in_preferences,
kim_identity_t *  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 object representing the failure.
See also:
kim_preferences_set_client_identity()

kim_error_t kim_preferences_set_remember_client_identity (  kim_preferences_t  io_preferences,
kim_boolean_t  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 object representing the failure.
See also:
kim_preferences_get_remember_client_identity()

kim_error_t kim_preferences_get_remember_client_identity (  kim_preferences_t  in_preferences,
kim_boolean_t *  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 object representing the failure.
See also:
kim_preferences_set_remember_client_identity()

kim_error_t kim_preferences_set_favorite_realms (  kim_preferences_t  io_preferences,
kim_favorite_realms_t  in_favorite_realms
) 
 

Set the user's preferred list of realms.

Parameters:
io_preferences a preferences object to modify.
in_favorite_realms a favorite realms object. See KIM Favorite Realms Overview for more information on KIM Favorite Realms.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_preferences_get_favorite_realms()

kim_error_t kim_preferences_get_favorite_realms (  kim_preferences_t  in_preferences,
kim_favorite_realms_t *  out_favorite_realms
) 
 

Get the user's preferred list of realms.

Parameters:
in_preferences a preferences object.
out_favorite_realms on exit, a copy of the favorite realms specified in in_preferences. See KIM Favorite Realms Overview for more information on KIM Favorite Realms. Must be freed with kim_favorite_realms_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_preferences_set_favorite_realms()

kim_error_t kim_preferences_synchronize (  kim_preferences_t  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 object representing the failure.

void kim_preferences_free (  kim_preferences_t *  io_preferences  ) 
 

Free memory associated with a preferences object.

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