On platforms which use a GUI to acquire credentials, the KIM would like to to display a list of identities for the user to select from. Depending on what is appropriate for the platform, identities may be displayed in a popup menu or other list.
To solve this problem, the KIM maintains a list of favorite identities specifically for identity selection. This list is a set of unique identities in alphabetical order (as appropriate for the user's language localization).
On most platforms the list of favorite identities has both an administrator preference and a user preference which overrides it. The administrator preference exists only to initialize the favorite identities for new user accounts. Once the user modifies the list their favorite identities may diverge from the site favorite identities preference.
Then use kim_favorite_identities_get_number_of_identities() and kim_favorite_identities_get_identity_at_index() to display the identities list. Use kim_favorite_identities_add_identity() and kim_favorite_identities_remove_identity() to change which identities are in the identities list. Identities are always stored in alphabetical order and duplicate identities are not permitted, so when you add or remove a identity you should redisplay the entire list.
Once you are done editing the identities list, store changes in the user's preference file using kim_preferences_set_favorite_identities() and kim_preferences_synchronize().
See KIM Favorite Identities Documentation for information on specific APIs.