On platforms which use a GUI to acquire credentials, the KIM would like to to display a list of realms for the user to select from. Depending on what is appropriate for the platform, realms may be displayed in a popup menu or other list. Incredibly long lists of realms are undesirable since they may force the user to scroll excessively to get to their desired realm. And if the list does not contain realms available via DNS SRV records, the user would be forced to type their realm every time they acquire initial credentials.
To solve this problem, the KIM maintains a list of favorite realms specifically for graphical realm selection. This list is a set of unique realm names in alphabetical order (as appropriate for the user's language localization) and is never used for realm configuration.
On most platforms the list of favorite realms has both an administrator preference and a user preference which overrides it. The administrator preference exists only to initialize the Favorite Realms for new user accounts. Once the user modifies the list their favorite realms may diverge from the site favorite realms preference.
Then use kim_favorite_realms_get_number_of_realms() and kim_favorite_realms_get_realm_at_index() to display the realms list. Use kim_favorite_realms_add_realm() and kim_favorite_realms_remove_realm() to change which realms are in the realms list. Realms are always stored in alphabetical order and duplicate realms are not permitted, so when you add or remove a realm you should redisplay the entire list.
Once you are done editing the realms list, store changes in the user's preference file using kim_preferences_set_favorite_realms() and kim_preferences_synchronize().
See KIM Favorite Realms Documentation for information on specific APIs.