kim_preferences_overview.html [plain text]
<!-- #bbinclude "header.txt"
#PAGETITLE#="Kerberos Identity Management: KIM Preferences Overview"
#ADDITIONALSTYLE#="@import url(doxygen.css);"
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<BASE HREF="http://web.mit.edu/macdev/KfM/KerberosFramework/KerberosIdentityManagement/Documentation/html/kim_preferences_overview.html">
<META NAME="keywords" CONTENT="#KEYWORDS#">
<META NAME="description" CONTENT="#DESCRIPTION#">
<TITLE>Kerberos Identity Management: KIM Preferences Overview</TITLE>
<STYLE TYPE="text/css">
@import url(../../../../Common/Documentation/templates/site.css);
</STYLE>
</HEAD>
<BODY>
<DIV ID="menu">
<IMG SRC="../../../../Common/Documentation/graphics/Kerberos.jpg" ALT="Kerberos for Macintosh Logo">
<HR>
<P><A HREF="../../../../Common/Documentation/index.html">Home</A></P>
<P><A HREF="http://web.mit.edu/kerberos/">MIT Kerberos</A></P>
<P><A HREF="http://web.mit.edu/ist/">MIT IS&T</A></P>
<HR>
<P><A HREF="../../../../Common/Documentation/news.html">News</A></P>
<P><A HREF="../../../../Common/Documentation/documentation.html">Documentation</A></P>
<P><A HREF="../../../../Common/Documentation/developer.html">Developer Resources</A></P>
<P><A HREF="../../../../Common/Documentation/license.html">License</A></P>
<HR>
<P><A HREF="../../../../Common/Documentation/download.html">Download</A></P>
<P><A HREF="../../../../Common/Documentation/support.html">Support</A></P>
<P><A HREF="../../../../Common/Documentation/contact.html">Contact Us</A></P>
</DIV>
<DIV ID="body">
<!-- end bbinclude -->
<!-- Generated by Doxygen 1.4.6 -->
<h1><a class="anchor" name="kim_preferences_overview">KIM Preferences Overview</a></h1><h2><a class="anchor" name="kim_preferences_introduction">
Introduction</a></h2>
In addition to the site preferences stored in the Kerberos configuration, users may also want to have their own personal preferences for controlling credential acquisition. As a result, KIM provides user preferences for initial credential options and user interface behavior such as the default client identity and the favorite realms list.<h2><a class="anchor" name="kim_preferences_edit">
Viewing and Editing the Preferences</a></h2>
In order to view and edit the user's preferences, call <a class="el" href="group__kim__preferences__reference.html#g88fba2fb35d73c5905eb21dcfad57578">kim_preferences_create()</a> to acquire a preferences object containing the user's preferences. You can examine preferences with the functions starting with "kim_preferences_get_" and change preferences with the functions starting with "kim_preferences_set_". Once you are done making changes, you can write changes back out to the user's preferences with <a class="el" href="group__kim__preferences__reference.html#gd4548bdc2cd52ad21d7a3e1bb60edba0">kim_preferences_synchronize()</a>.<p>
<dl compact><dt><b>Note:</b></dt><dd>The location of user preferences and the semantics of preference synchronization is platform-specific. Where possible KIM will use platform-specific preference mechanisms.</dd></dl>
<h2><a class="anchor" name="kim_preferences_options">
Initial Credential Options Preferences</a></h2>
KIM provides user preferences for initial credential options. These are the options <a class="el" href="group__kim__options__reference.html#g4d00f4d070409ea90aa69a8ac5cb47cf">kim_options_create()</a> will use when creating a new KIM options object. They are also the options specified by KIM_OPTIONS_DEFAULT. You can view and edit the initial credential options using <a class="el" href="group__kim__preferences__reference.html#g634a03cb1109362db8e4024b055afa71">kim_preferences_get_options()</a> and <a class="el" href="group__kim__preferences__reference.html#ge7f0f13dd6d50e7730205abddb1a0127">kim_preferences_set_options()</a>.<p>
<dl compact><dt><b>Note:</b></dt><dd>Not all credential options in the kim_options_t object have corresponding user preferences. For example, the prompt callback function is not stored in the user preferences since it has no meaning outside of the current application. Some options which are not currently stored in the preferences may be stored there in the future.</dd></dl>
If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the initial credential options preferences. If the user successfully acquires credentials with non-default options and <a class="el" href="group__kim__preferences__reference.html#g804eb8078e5b5a1c73e7e27b0efdb66d">kim_preferences_get_remember_options()</a> is set to TRUE, you should store the options used to get credentials with <a class="el" href="group__kim__preferences__reference.html#ge7f0f13dd6d50e7730205abddb1a0127">kim_preferences_set_options()</a>.<h2><a class="anchor" name="kim_preferences_client_identity">
Client Identity Preferences</a></h2>
KIM also provides user preferences for the default client identity. This identity is used whenever KIM needs to display a graphical dialog for credential acquisition but does not know what client identity to use. You can view and edit the default client identity using <a class="el" href="group__kim__preferences__reference.html#ga7bf4c87813bee177d2485d827c59943">kim_preferences_get_client_identity()</a> and <a class="el" href="group__kim__preferences__reference.html#g70806a8dfdde27746f8c161b4f845ecb">kim_preferences_set_client_identity()</a>.<p>
If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the client identity preferences. If the user successfully acquires credentials with non-default options and <a class="el" href="group__kim__preferences__reference.html#gd24a4831e3664ae2ec69b2de2ccfca50">kim_preferences_get_remember_client_identity()</a> is set to TRUE, you should store the client identity for which credentials were acquired using <a class="el" href="group__kim__preferences__reference.html#g70806a8dfdde27746f8c161b4f845ecb">kim_preferences_set_client_identity()</a>.<h2><a class="anchor" name="kim_preferences_favorite_realms">
Favorite Realms Preferences</a></h2>
When presenting a graphical interface for credential acquisition, KIM may need to display a list of realms for the user to select from. This list is generated by the user's favorite realms preference. You can view and edit the favorite realms preference using <a class="el" href="group__kim__preferences__reference.html#g8830e09ce0640497fa994bd0774c2083">kim_preferences_get_favorite_realms()</a> and <a class="el" href="group__kim__preferences__reference.html#gab23bf8c419a21a6fe5a006875eaa5a1">kim_preferences_set_favorite_realms()</a>. Please see the <a class="el" href="kim_favorite_realms_overview.html">KIM Favorite Realms Overview</a> for more information.<p>
See <a class="el" href="group__kim__preferences__reference.html">KIM Preferences Documentation</a> for information on specific APIs.
<!-- #bbinclude "footer.txt" -->
</DIV>
<DIV ID="footer">
<P>
Copyright 2006 Massachusetts Institute of Technology.<BR>
Last updated on $Date: 2006-01-06 20:23:52 -0500 (Fri, 06 Jan 2006) $ <BR>
Last modified by $Author: lxs $
</P>
</DIV>
<!-- Begin MIT-use only web reporting counter -->
<IMG SRC="http://counter.mit.edu/tally" WIDTH=1 HEIGHT=1 ALT="">
<!-- End MIT-use only web reporting counter -->
</BODY></HTML>
<!-- end bbinclude -->