</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<dl class="el"><dd class="mdescRight">Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential. <a href="#g52fa72130f4ba6de8cce1224578102ce"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g6ecc14b94ffb57ca8008d0a407bb9c7d">kim_ccache_create_from_client_identity</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity)
<dl class="el"><dd class="mdescRight">Find a ccache for a client identity in the cache collection. <a href="#g6ecc14b94ffb57ca8008d0a407bb9c7d"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g15cb7e1b9069a610030211cecc5e6232">kim_ccache_create_from_keytab</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_keytab)
<dl class="el"><dd class="mdescRight">Acquire a new initial credential from a keytab and store it in a ccache. <a href="#g15cb7e1b9069a610030211cecc5e6232"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g137761ce872ca756c08e7c31e4101df5">kim_ccache_create_from_default</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache)
-<dl class="el"><dd class="mdescRight">Get the default ccache. <a href="#g137761ce872ca756c08e7c31e4101df5"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g4c532da378a5bc222eeaa8ecbabecb72">kim_ccache_create_from_type_and_name</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_type, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_name)
+<dl class="el"><dd class="mdescRight">Get the default ccache. <a href="#g137761ce872ca756c08e7c31e4101df5"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#geeb02fbd667cfb75455653cf9b8b4a5a">kim_ccache_create_from_display_name</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_display_name)
+<dl class="el"><dd class="mdescRight">Get a ccache for a ccache display name. <a href="#geeb02fbd667cfb75455653cf9b8b4a5a"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g4c532da378a5bc222eeaa8ecbabecb72">kim_ccache_create_from_type_and_name</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_type, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_name)
<dl class="el"><dd class="mdescRight">Get a ccache for a ccache type and name. <a href="#g4c532da378a5bc222eeaa8ecbabecb72"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g1d5c688dd5fae7e722ee7dd3e335fe34">kim_ccache_create_from_krb5_ccache</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, krb5_context in_krb5_context, krb5_ccache in_krb5_ccache)
<dl class="el"><dd class="mdescRight">Get a ccache for a krb5 ccache. <a href="#g1d5c688dd5fae7e722ee7dd3e335fe34"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#gc56dbcf51cddbe0e08b695e649c4a4de">kim_ccache_copy</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache)
-<dl class="el"><dd class="mdescRight">Copy a ccache. <a href="#gc56dbcf51cddbe0e08b695e649c4a4de"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g2c141d7d829dfcf4b761cd04f71a5443">kim_ccache_get_krb5_ccache</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, krb5_context in_krb5_context, krb5_ccache *out_krb5_ccache)
+<dl class="el"><dd class="mdescRight">Copy a ccache. <a href="#gc56dbcf51cddbe0e08b695e649c4a4de"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g7e855e7c8410154fb0aa9b755d97a0c3">kim_ccache_compare</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_compare_to_ccache, <a class="el" href="group__kim__types__reference.html#gae48569e847ff6af9d10add42a4338e7">kim_comparison</a> *out_comparison)
+<dl class="el"><dd class="mdescRight">Compare ccache objects. <a href="#g7e855e7c8410154fb0aa9b755d97a0c3"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g2c141d7d829dfcf4b761cd04f71a5443">kim_ccache_get_krb5_ccache</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, krb5_context in_krb5_context, krb5_ccache *out_krb5_ccache)
<dl class="el"><dd class="mdescRight">Get a krb5 ccache for a ccache. <a href="#g2c141d7d829dfcf4b761cd04f71a5443"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g18d612eddf05b4deb11e97071b5ad17b">kim_ccache_get_name</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_name)
<dl class="el"><dd class="mdescRight">Get the name of a ccache. <a href="#g18d612eddf05b4deb11e97071b5ad17b"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#ge49fc64af74ad437de6becdbee876117">kim_ccache_get_type</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_type)
<dl class="el"><dd class="mdescRight">Get the type of a ccache. <a href="#ge49fc64af74ad437de6becdbee876117"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#ga89f6bfa35c436621ff324b805a7c669">kim_ccache_get_display_name</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_display_name)
<dl class="el"><dd class="mdescRight">Check the state of the credentials in a ccache (valid, expired, postdated, etc). <a href="#gb838921f1d2db46468ea14d9e7572c03"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#gb2165acd652eddaeb61c8f6b8c3a16f7">kim_ccache_get_start_time</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a> *out_start_time)
<dl class="el"><dd class="mdescRight">Get the time when the credentials in the ccache become valid. <a href="#gb2165acd652eddaeb61c8f6b8c3a16f7"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g52693fc485cf2e3bd5cf0c0a3d414d8a">kim_ccache_get_expiration_time</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a> *out_expiration_time)
<dl class="el"><dd class="mdescRight">Get the time when the credentials in the ccache will expire. <a href="#g52693fc485cf2e3bd5cf0c0a3d414d8a"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g01b4cbb88abf6aafd2efdaad91d74f0f">kim_ccache_get_renewal_expiration_time</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a> *out_renewal_expiration_time)
-<dl class="el"><dd class="mdescRight">Get the time when the credentials in the ccache will no longer be renewable. <a href="#g01b4cbb88abf6aafd2efdaad91d74f0f"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#ga9f694b7c3dea5cc3422604571419f80">kim_ccache_set_default</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> io_ccache)
+<dl class="el"><dd class="mdescRight">Get the time when the credentials in the ccache will no longer be renewable. <a href="#g01b4cbb88abf6aafd2efdaad91d74f0f"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g9ad7a15bf94420675c17bc61e83e47da">kim_ccache_get_options</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> *out_options)
+<dl class="el"><dd class="mdescRight">Get a kim_options object based on a ccache's credential attributes. <a href="#g9ad7a15bf94420675c17bc61e83e47da"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#ga9f694b7c3dea5cc3422604571419f80">kim_ccache_set_default</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> io_ccache)
<dl class="el"><dd class="mdescRight">Set a ccache to the default ccache. <a href="#ga9f694b7c3dea5cc3422604571419f80"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g8836113dd86a0dc3cf60df0d76280de6">kim_ccache_verify</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_service_identity, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_keytab, <a class="el" href="group__kim__types__reference.html#g6f8afd4047c4fe420c05f940f89ffba0">kim_boolean</a> in_fail_if_no_service_key)
<dl class="el"><dd class="mdescRight">Verify the TGT in a ccache. <a href="#g8836113dd86a0dc3cf60df0d76280de6"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g574a0ef674116589dcf57460af81de39">kim_ccache_renew</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
<dl class="el"><dd class="mdescRight">Renew the TGT in a ccache. <a href="#g574a0ef674116589dcf57460af81de39"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g73f5b201d24a58936244fc4e43cd3d59">kim_ccache_validate</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> in_ccache, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+</div>
+</div><p>
+<a class="anchor" name="geeb02fbd667cfb75455653cf9b8b4a5a"></a><!-- doxytag: member="kim_ccache.h::kim_ccache_create_from_display_name" ref="geeb02fbd667cfb75455653cf9b8b4a5a" args="(kim_ccache *out_ccache, kim_string in_display_name)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_ccache_create_from_display_name </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> * </td>
+ <td class="paramname"> <em>out_ccache</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> </td>
+ <td class="paramname"> <em>in_display_name</em></td><td> </td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>)</td>
+ <td></td><td></td><td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Get a ccache for a ccache display name.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>out_ccache</em> </td><td>on exit, a ccache object for the ccache identified by <em>in_display_name</em>. Must be freed with <a class="el" href="group__kim__ccache__reference.html#g6c6be543e0ea2b518612be4255e15b9a" title="Free memory associated with a ccache.">kim_ccache_free()</a>. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_display_name</em> </td><td>a ccache display name string (ie: "TYPE:NAME"). </td></tr>
+ </table>
+</dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd>This API is used to obtain a kim_ccache for a ccache name entered by the user. </dd></dl>
+
</div>
</div><p>
<a class="anchor" name="g4c532da378a5bc222eeaa8ecbabecb72"></a><!-- doxytag: member="kim_ccache.h::kim_ccache_create_from_type_and_name" ref="g4c532da378a5bc222eeaa8ecbabecb72" args="(kim_ccache *out_ccache, kim_string in_type, kim_string in_name)" -->
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+</div>
+</div><p>
+<a class="anchor" name="g7e855e7c8410154fb0aa9b755d97a0c3"></a><!-- doxytag: member="kim_ccache.h::kim_ccache_compare" ref="g7e855e7c8410154fb0aa9b755d97a0c3" args="(kim_ccache in_ccache, kim_ccache in_compare_to_ccache, kim_comparison *out_comparison)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_ccache_compare </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> </td>
+ <td class="paramname"> <em>in_ccache</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> </td>
+ <td class="paramname"> <em>in_compare_to_ccache</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gae48569e847ff6af9d10add42a4338e7">kim_comparison</a> * </td>
+ <td class="paramname"> <em>out_comparison</em></td><td> </td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>)</td>
+ <td></td><td></td><td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Compare ccache objects.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>in_ccache</em> </td><td>a ccache object. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_compare_to_ccache</em> </td><td>a ccache object. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_comparison</em> </td><td>on exit, a comparison of <em>in_ccache</em> and <em>in_compare_to_ccache</em> which determines whether or not the two ccache objects refer to the same ccache. </td></tr>
+ </table>
+</dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+
</div>
</div><p>
<a class="anchor" name="g2c141d7d829dfcf4b761cd04f71a5443"></a><!-- doxytag: member="kim_ccache.h::kim_ccache_get_krb5_ccache" ref="g2c141d7d829dfcf4b761cd04f71a5443" args="(kim_ccache in_ccache, krb5_context in_krb5_context, krb5_ccache *out_krb5_ccache)" -->
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+</div>
+</div><p>
+<a class="anchor" name="g9ad7a15bf94420675c17bc61e83e47da"></a><!-- doxytag: member="kim_ccache.h::kim_ccache_get_options" ref="g9ad7a15bf94420675c17bc61e83e47da" args="(kim_ccache in_ccache, kim_options *out_options)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_ccache_get_options </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> </td>
+ <td class="paramname"> <em>in_ccache</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> * </td>
+ <td class="paramname"> <em>out_options</em></td><td> </td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>)</td>
+ <td></td><td></td><td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Get a kim_options object based on a ccache's credential attributes.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>in_ccache</em> </td><td>a ccache object. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_options</em> </td><td>on exit, an options object reflecting the ticket options of the credentials in <em>in_ccache</em>. </td></tr>
+ </table>
+</dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+
</div>
</div><p>
<a class="anchor" name="ga9f694b7c3dea5cc3422604571419f80"></a><!-- doxytag: member="kim_ccache.h::kim_ccache_set_default" ref="ga9f694b7c3dea5cc3422604571419f80" args="(kim_ccache io_ccache)" -->
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#ga02a96b9ad6fbc64007f741fa21c8814">kim_credential_create_new</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
<dl class="el"><dd class="mdescRight">Acquire a new initial credential. <a href="#ga02a96b9ad6fbc64007f741fa21c8814"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g42c9498e4e928fce495867a1d1835dc3">kim_credential_create_from_keytab</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_keytab)
<dl class="el"><dd class="mdescRight">Acquire a new initial credential from a keytab. <a href="#g42c9498e4e928fce495867a1d1835dc3"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g5a65ab2a4209ee727d2a08ba8481dd8f">kim_credential_create_from_krb5_creds</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, krb5_context in_krb5_context, krb5_creds *in_krb5_creds)
-<dl class="el"><dd class="mdescRight">Copy a credential from a krb5 credential object. <a href="#g5a65ab2a4209ee727d2a08ba8481dd8f"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g09c1cdf2b993ab881319a33074f5ef24">kim_credential_create_for_change_password</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_old_password)
-<dl class="el"><dd class="mdescRight">Obtain a credential for changing an identity's password. <a href="#g09c1cdf2b993ab881319a33074f5ef24"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#gecf207628b94739322344678486b45d2">kim_credential_copy</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential)
+<dl class="el"><dd class="mdescRight">Copy a credential from a krb5 credential object. <a href="#g5a65ab2a4209ee727d2a08ba8481dd8f"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#gecf207628b94739322344678486b45d2">kim_credential_copy</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential)
<dl class="el"><dd class="mdescRight">Copy a credential object. <a href="#gecf207628b94739322344678486b45d2"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g5ccc2fc794ea3bf3dc947c8a3ccd1077">kim_credential_get_krb5_creds</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, krb5_context in_krb5_context, krb5_creds **out_krb5_creds)
<dl class="el"><dd class="mdescRight">Get a krb5 credentials object for a credential object. <a href="#g5ccc2fc794ea3bf3dc947c8a3ccd1077"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g823f10b2a4db687fb555920808113392">kim_credential_get_client_identity</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> *out_client_identity)
<dl class="el"><dd class="mdescRight">Get the client identity of a credential object. <a href="#g823f10b2a4db687fb555920808113392"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g05208e303966c4c89371c18135de9cd7">kim_credential_get_service_identity</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> *out_service_identity)
<dl class="el"><dd class="mdescRight">Check the state of a credential (valid, expired, postdated, etc). <a href="#g214a9d5e947d7947132a2849826a93f4"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#gcae9e3e2b129e68215eedf588da60bea">kim_credential_get_start_time</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a> *out_start_time)
<dl class="el"><dd class="mdescRight">Get the time when the credentials become valid. <a href="#gcae9e3e2b129e68215eedf588da60bea"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#gba6367f04f832e086a8b0c01ebd3f77e">kim_credential_get_expiration_time</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a> *out_expiration_time)
<dl class="el"><dd class="mdescRight">Get the time when the credentials will expire. <a href="#gba6367f04f832e086a8b0c01ebd3f77e"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g4e50b4abf3efc36ed10c3049c9ff9a48">kim_credential_get_renewal_expiration_time</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a> *out_renewal_expiration_time)
-<dl class="el"><dd class="mdescRight">Get the time when the credentials will no longer be renewable. <a href="#g4e50b4abf3efc36ed10c3049c9ff9a48"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g52db69b8f2289a4b60a3eddb5cb6b671">kim_credential_store</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache)
+<dl class="el"><dd class="mdescRight">Get the time when the credentials will no longer be renewable. <a href="#g4e50b4abf3efc36ed10c3049c9ff9a48"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g6d0cb540926a4d95923709a5104fb298">kim_credential_get_options</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> *out_options)
+<dl class="el"><dd class="mdescRight">Get a kim_options object based on a credential's attributes. <a href="#g6d0cb540926a4d95923709a5104fb298"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g52db69b8f2289a4b60a3eddb5cb6b671">kim_credential_store</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache)
<dl class="el"><dd class="mdescRight">Store a credential in a ccache in the cache collection. <a href="#g52db69b8f2289a4b60a3eddb5cb6b671"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#gf10b622ed5ea209bf06ba708732b6c07">kim_credential_verify</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_service_identity, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_keytab, <a class="el" href="group__kim__types__reference.html#g6f8afd4047c4fe420c05f940f89ffba0">kim_boolean</a> in_fail_if_no_service_key)
<dl class="el"><dd class="mdescRight">Verify a TGT credential. <a href="#gf10b622ed5ea209bf06ba708732b6c07"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g18f43112f7ae046b2a5918b061a2072d">kim_credential_renew</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *io_credential, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
<dl class="el"><dd class="mdescRight">Renew a TGT credential. <a href="#g18f43112f7ae046b2a5918b061a2072d"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g63a591ef509219ae83d11b635065984d">kim_credential_validate</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *io_credential, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
-<dl class="el"><dd class="mdescRight">Validate a TGT credential. <a href="#g63a591ef509219ae83d11b635065984d"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#ge51af0e19abfcba108d8fd4ca3effea3">kim_credential_change_password</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_new_password, <a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> *out_rejected_err, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_rejected_message, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_rejected_description)
-<dl class="el"><dd class="mdescRight">Change an identity's password. <a href="#ge51af0e19abfcba108d8fd4ca3effea3"></a><br></dl><li>void <a class="el" href="group__kim__credential__reference.html#g5609d3883f82eb3938a2d80e06bd0845">kim_credential_free</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *io_credential)
+<dl class="el"><dd class="mdescRight">Validate a TGT credential. <a href="#g63a591ef509219ae83d11b635065984d"></a><br></dl><li>void <a class="el" href="group__kim__credential__reference.html#g5609d3883f82eb3938a2d80e06bd0845">kim_credential_free</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *io_credential)
<dl class="el"><dd class="mdescRight">Free memory associated with a credential object. <a href="#g5609d3883f82eb3938a2d80e06bd0845"></a><br></dl></ul>
<hr><h2>Function Documentation</h2>
<a class="anchor" name="ga02a96b9ad6fbc64007f741fa21c8814"></a><!-- doxytag: member="kim_credential.h::kim_credential_create_new" ref="ga02a96b9ad6fbc64007f741fa21c8814" args="(kim_credential *out_credential, kim_identity in_client_identity, kim_options in_options)" -->
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
-</div>
-</div><p>
-<a class="anchor" name="g09c1cdf2b993ab881319a33074f5ef24"></a><!-- doxytag: member="kim_credential.h::kim_credential_create_for_change_password" ref="g09c1cdf2b993ab881319a33074f5ef24" args="(kim_credential *out_credential, kim_identity in_identity, kim_string in_old_password)" -->
-<div class="memitem">
-<div class="memproto">
- <table class="memname">
- <tr>
- <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_credential_create_for_change_password </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> * </td>
- <td class="paramname"> <em>out_credential</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> </td>
- <td class="paramname"> <em>in_identity</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> </td>
- <td class="paramname"> <em>in_old_password</em></td><td> </td>
- </tr>
- <tr>
- <td></td>
- <td>)</td>
- <td></td><td></td><td width="100%"></td>
- </tr>
- </table>
-</div>
-<div class="memdoc">
-
-<p>
-Obtain a credential for changing an identity's password.
-<p>
-<dl compact><dt><b>Parameters:</b></dt><dd>
- <table border="0" cellspacing="2" cellpadding="0">
- <tr><td valign="top"></td><td valign="top"><em>out_credential</em> </td><td>on exit, a new credential object containing a change password credential for <em>in_identity</em>. Must be freed with <a class="el" href="group__kim__credential__reference.html#g5609d3883f82eb3938a2d80e06bd0845" title="Free memory associated with a credential object.">kim_credential_free()</a>. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_identity</em> </td><td>a client identity to obtain a change password credential for. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_old_password</em> </td><td>the current password for <em>in_identity</em>. May be an expired password. </td></tr>
- </table>
-</dl>
-<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
-<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__credential__reference.html#ge51af0e19abfcba108d8fd4ca3effea3" title="Change an identity's password.">kim_credential_change_password</a> </dd></dl>
-
</div>
</div><p>
<a class="anchor" name="gecf207628b94739322344678486b45d2"></a><!-- doxytag: member="kim_credential.h::kim_credential_copy" ref="gecf207628b94739322344678486b45d2" args="(kim_credential *out_credential, kim_credential in_credential)" -->
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>in_credential</em> </td><td>a credential object. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>out_renewal_expiration_time</em> </td><td>on exit, the time when <em>in_credential</em> will no longer be renewable. May be in the past or future. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_renewal_expiration_time</em> </td><td>on exit, the time when <em>in_credential</em> will no longer be renewable. May be in the past or future. If credentials are not renewable at all, returns 0. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__ccache__reference.html#g01b4cbb88abf6aafd2efdaad91d74f0f" title="Get the time when the credentials in the ccache will no longer be renewable.">kim_ccache_get_renewal_expiration_time</a> </dd></dl>
+</div>
+</div><p>
+<a class="anchor" name="g6d0cb540926a4d95923709a5104fb298"></a><!-- doxytag: member="kim_credential.h::kim_credential_get_options" ref="g6d0cb540926a4d95923709a5104fb298" args="(kim_credential in_credential, kim_options *out_options)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_credential_get_options </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> </td>
+ <td class="paramname"> <em>in_credential</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> * </td>
+ <td class="paramname"> <em>out_options</em></td><td> </td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>)</td>
+ <td></td><td></td><td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Get a kim_options object based on a credential's attributes.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>in_credential</em> </td><td>a credential object. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_options</em> </td><td>on exit, an options object reflecting the ticket options of <em>in_credential</em>. </td></tr>
+ </table>
+</dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+
</div>
</div><p>
<a class="anchor" name="g52db69b8f2289a4b60a3eddb5cb6b671"></a><!-- doxytag: member="kim_credential.h::kim_credential_store" ref="g52db69b8f2289a4b60a3eddb5cb6b671" args="(kim_credential in_credential, kim_identity in_client_identity, kim_ccache *out_ccache)" -->
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__ccache__reference.html#g73f5b201d24a58936244fc4e43cd3d59" title="Validate the TGT in a ccache.">kim_ccache_validate</a> </dd></dl>
-</div>
-</div><p>
-<a class="anchor" name="ge51af0e19abfcba108d8fd4ca3effea3"></a><!-- doxytag: member="kim_credential.h::kim_credential_change_password" ref="ge51af0e19abfcba108d8fd4ca3effea3" args="(kim_credential in_credential, kim_identity in_identity, kim_string in_new_password, kim_error *out_rejected_err, kim_string *out_rejected_message, kim_string *out_rejected_description)" -->
-<div class="memitem">
-<div class="memproto">
- <table class="memname">
- <tr>
- <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_credential_change_password </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> </td>
- <td class="paramname"> <em>in_credential</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> </td>
- <td class="paramname"> <em>in_identity</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> </td>
- <td class="paramname"> <em>in_new_password</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> * </td>
- <td class="paramname"> <em>out_rejected_err</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> * </td>
- <td class="paramname"> <em>out_rejected_message</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> * </td>
- <td class="paramname"> <em>out_rejected_description</em></td><td> </td>
- </tr>
- <tr>
- <td></td>
- <td>)</td>
- <td></td><td></td><td width="100%"></td>
- </tr>
- </table>
-</div>
-<div class="memdoc">
-
-<p>
-Change an identity's password.
-<p>
-<dl compact><dt><b>Parameters:</b></dt><dd>
- <table border="0" cellspacing="2" cellpadding="0">
- <tr><td valign="top"></td><td valign="top"><em>in_credential</em> </td><td>a credential object containing a change password credential. Use <a class="el" href="group__kim__credential__reference.html#ge51af0e19abfcba108d8fd4ca3effea3" title="Change an identity's password.">kim_credential_change_password</a> to obtain a change password credential. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_identity</em> </td><td>an identity to change the password for. May be different than the identity the credential is for. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_new_password</em> </td><td>the password to change the identity to. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>out_rejected_err</em> </td><td>on exit, 0 if the password change was successful or an error describing why the new password was rejected. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>out_rejected_message</em> </td><td>on exit, if <em>out_rejected_err</em> is non-zero this argument will contain an error message for <em>out_rejected_err</em>. Pass NULL if you do not want this error string. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>; </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>out_rejected_description</em> </td><td>on exit, if <em>out_rejected_err</em> is non-zero this argument will contain an string describing why <em>in_new_password</em> was rejected. Pass NULL if you do not want this error string. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>; </td></tr>
- </table>
-</dl>
-<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
-<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__credential__reference.html#g09c1cdf2b993ab881319a33074f5ef24" title="Obtain a credential for changing an identity's password.">kim_credential_create_for_change_password</a> </dd></dl>
-
</div>
</div><p>
<a class="anchor" name="g5609d3883f82eb3938a2d80e06bd0845"></a><!-- doxytag: member="kim_credential.h::kim_credential_free" ref="g5609d3883f82eb3938a2d80e06bd0845" args="(kim_credential *io_credential)" -->
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<dl class="el"><dd class="mdescRight">Get a human-readable string representation of an identity. <a href="#g59afb84675651930afebeb6fff788eba"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#gf102dfe4b89f6e87ac3059f01f174066">kim_identity_get_realm</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_realm_string)
<dl class="el"><dd class="mdescRight">Get the realm string of an identity. <a href="#gf102dfe4b89f6e87ac3059f01f174066"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#g96591cf92e03e823efcd4fc54085ca4d">kim_identity_get_number_of_components</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#g098e3611b2bc3af38b5f06838153165d">kim_count</a> *out_number_of_components)
<dl class="el"><dd class="mdescRight">Get the number of components of an identity. <a href="#g96591cf92e03e823efcd4fc54085ca4d"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#gec46c138cd20035a12586dba59680728">kim_identity_get_component_at_index</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#g098e3611b2bc3af38b5f06838153165d">kim_count</a> in_index, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_component_string)
-<dl class="el"><dd class="mdescRight">Get the Nth component of an identity. <a href="#gec46c138cd20035a12586dba59680728"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#gd293289334f024dedae5fa59856049d6">kim_identity_get_krb5_principal</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, krb5_context in_krb5_context, krb5_principal *out_krb5_principal)
+<dl class="el"><dd class="mdescRight">Get the Nth component of an identity. <a href="#gec46c138cd20035a12586dba59680728"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#gaf44da7019777b8b3cc78b7624e26d33">kim_identity_get_components_string</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_components)
+<dl class="el"><dd class="mdescRight">Get a display string of the non-realm components of an identity. <a href="#gaf44da7019777b8b3cc78b7624e26d33"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#gd293289334f024dedae5fa59856049d6">kim_identity_get_krb5_principal</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, krb5_context in_krb5_context, krb5_principal *out_krb5_principal)
<dl class="el"><dd class="mdescRight">Get the krb5_principal representation of an identity. <a href="#gd293289334f024dedae5fa59856049d6"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#g660c28e70656127c7c723d50414675e8">kim_identity_change_password</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity)
<dl class="el"><dd class="mdescRight">Change the password for an identity. <a href="#g660c28e70656127c7c723d50414675e8"></a><br></dl><li>void <a class="el" href="group__kim__identity__reference.html#g3ae8057f3eb0040330b598645d470411">kim_identity_free</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> *io_identity)
<dl class="el"><dd class="mdescRight">Free memory associated with an identity. <a href="#g3ae8057f3eb0040330b598645d470411"></a><br></dl></ul>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+</div>
+</div><p>
+<a class="anchor" name="gaf44da7019777b8b3cc78b7624e26d33"></a><!-- doxytag: member="kim_identity.h::kim_identity_get_components_string" ref="gaf44da7019777b8b3cc78b7624e26d33" args="(kim_identity in_identity, kim_string *out_components)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_identity_get_components_string </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> </td>
+ <td class="paramname"> <em>in_identity</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> * </td>
+ <td class="paramname"> <em>out_components</em></td><td> </td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>)</td>
+ <td></td><td></td><td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Get a display string of the non-realm components of an identity.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>in_identity</em> </td><td>an identity object. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_components</em> </td><td>on exit, a string of the non-realm components of <em>in_identity</em> separated by '/' characters. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>. </td></tr>
+ </table>
+</dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+
</div>
</div><p>
<a class="anchor" name="gd293289334f024dedae5fa59856049d6"></a><!-- doxytag: member="kim_identity.h::kim_identity_get_krb5_principal" ref="gd293289334f024dedae5fa59856049d6" args="(kim_identity in_identity, krb5_context in_krb5_context, krb5_principal *out_krb5_principal)" -->
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+<title>Kerberos Identity Management: KIM Library Documentation</title>
+<link href="doxygen.css" rel="stylesheet" type="text/css">
+<link href="tabs.css" rel="stylesheet" type="text/css">
+</head><body>
+<!-- Generated by Doxygen 1.5.3 -->
+<h1>KIM Library Documentation</h1>
+<p>
+<h2>Defines</h2>
+<ul>
+<li>#define <a class="el" href="group__kim__library__reference.html#gcd87f3f37afaec8574c8f7de57762638">KIM_UI_ENVIRONMENT_NONE</a> 0
+<li>#define <a class="el" href="group__kim__library__reference.html#gb58175e1f93b385d9018247c3808f4ef">KIM_UI_ENVIRONMENT_AUTO</a> 1
+<li>#define <a class="el" href="group__kim__library__reference.html#gcb8839fe96c7793c9047acbe20cc7504">KIM_UI_ENVIRONMENT_GUI</a> 2
+<li>#define <a class="el" href="group__kim__library__reference.html#g1da8a35778f8ad3dc34ecaa569fe9092">KIM_UI_ENVIRONMENT_CLI</a> 3
+</ul>
+<h2>Typedefs</h2>
+<ul>
+<li>typedef int <a class="el" href="group__kim__library__reference.html#ged9db775d80a0de4a34287e972360146">kim_ui_environment</a>
+</ul>
+<h2>Functions</h2>
+<ul>
+<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__library__reference.html#g88df8459520ff0406525caed6380efa2">kim_library_set_ui_environment</a> (<a class="el" href="group__kim__library__reference.html#ged9db775d80a0de4a34287e972360146">kim_ui_environment</a> in_ui_environment)
+<dl class="el"><dd class="mdescRight">Tell KIM how to present UI from your application. <a href="#g88df8459520ff0406525caed6380efa2"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__library__reference.html#ge35892fc42ab06b342b43e8610e0c900">kim_library_set_allow_home_directory_access</a> (<a class="el" href="group__kim__types__reference.html#g6f8afd4047c4fe420c05f940f89ffba0">kim_boolean</a> in_allow_access)
+<dl class="el"><dd class="mdescRight">Tells KIM whether or not it is allowed to touch the user's home directory. <a href="#ge35892fc42ab06b342b43e8610e0c900"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__library__reference.html#g1daf766839e32fdc02c4c37978642951">kim_library_set_allow_automatic_prompting</a> (<a class="el" href="group__kim__types__reference.html#g6f8afd4047c4fe420c05f940f89ffba0">kim_boolean</a> in_allow_automatic_prompting)
+<dl class="el"><dd class="mdescRight">Tells KIM whether or not it is allowed to automatically present user interface. <a href="#g1daf766839e32fdc02c4c37978642951"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__library__reference.html#gfdf50a60bc513497e47852e43a02c8a9">kim_library_set_application_name</a> (<a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_application_name)
+<dl class="el"><dd class="mdescRight">Set the name of your application for KIM to use for user interface. <a href="#gfdf50a60bc513497e47852e43a02c8a9"></a><br></dl></ul>
+<hr><h2>Define Documentation</h2>
+<a class="anchor" name="gcd87f3f37afaec8574c8f7de57762638"></a><!-- doxytag: member="kim_library.h::KIM_UI_ENVIRONMENT_NONE" ref="gcd87f3f37afaec8574c8f7de57762638" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define KIM_UI_ENVIRONMENT_NONE 0 </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Do not present user interface
+</div>
+</div><p>
+<a class="anchor" name="gb58175e1f93b385d9018247c3808f4ef"></a><!-- doxytag: member="kim_library.h::KIM_UI_ENVIRONMENT_AUTO" ref="gb58175e1f93b385d9018247c3808f4ef" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define KIM_UI_ENVIRONMENT_AUTO 1 </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Automatically determine what user interface is appropriate (default).
+</div>
+</div><p>
+<a class="anchor" name="gcb8839fe96c7793c9047acbe20cc7504"></a><!-- doxytag: member="kim_library.h::KIM_UI_ENVIRONMENT_GUI" ref="gcb8839fe96c7793c9047acbe20cc7504" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define KIM_UI_ENVIRONMENT_GUI 2 </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Present a graphical user interface
+</div>
+</div><p>
+<a class="anchor" name="g1da8a35778f8ad3dc34ecaa569fe9092"></a><!-- doxytag: member="kim_library.h::KIM_UI_ENVIRONMENT_CLI" ref="g1da8a35778f8ad3dc34ecaa569fe9092" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define KIM_UI_ENVIRONMENT_CLI 3 </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Present a command line user interface
+</div>
+</div><p>
+<hr><h2>Typedef Documentation</h2>
+<a class="anchor" name="ged9db775d80a0de4a34287e972360146"></a><!-- doxytag: member="kim_library.h::kim_ui_environment" ref="ged9db775d80a0de4a34287e972360146" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">typedef int <a class="el" href="group__kim__library__reference.html#ged9db775d80a0de4a34287e972360146">kim_ui_environment</a> </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+An integer describing the type of user interface to use.
+</div>
+</div><p>
+<hr><h2>Function Documentation</h2>
+<a class="anchor" name="g88df8459520ff0406525caed6380efa2"></a><!-- doxytag: member="kim_library.h::kim_library_set_ui_environment" ref="g88df8459520ff0406525caed6380efa2" args="(kim_ui_environment in_ui_environment)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_library_set_ui_environment </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__library__reference.html#ged9db775d80a0de4a34287e972360146">kim_ui_environment</a> </td>
+ <td class="paramname"> <em>in_ui_environment</em> </td>
+ <td> ) </td>
+ <td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Tell KIM how to present UI from your application.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>in_ui_environment</em> </td><td>an integer value describing the type of user interface to use. </td></tr>
+ </table>
+</dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd>Set to KIM_UI_ENVIRONMENT_AUTO by default. </dd></dl>
+
+</div>
+</div><p>
+<a class="anchor" name="ge35892fc42ab06b342b43e8610e0c900"></a><!-- doxytag: member="kim_library.h::kim_library_set_allow_home_directory_access" ref="ge35892fc42ab06b342b43e8610e0c900" args="(kim_boolean in_allow_access)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_library_set_allow_home_directory_access </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#g6f8afd4047c4fe420c05f940f89ffba0">kim_boolean</a> </td>
+ <td class="paramname"> <em>in_allow_access</em> </td>
+ <td> ) </td>
+ <td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Tells KIM whether or not it is allowed to touch the user's home directory.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>in_allow_access</em> </td><td>a boolean containing whether or not to touch the user's home directory. </td></tr>
+ </table>
+</dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd>This API is usually used for Kerberos authenticated home directories to prevent a deadlock. </dd></dl>
+
+</div>
+</div><p>
+<a class="anchor" name="g1daf766839e32fdc02c4c37978642951"></a><!-- doxytag: member="kim_library.h::kim_library_set_allow_automatic_prompting" ref="g1daf766839e32fdc02c4c37978642951" args="(kim_boolean in_allow_automatic_prompting)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_library_set_allow_automatic_prompting </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#g6f8afd4047c4fe420c05f940f89ffba0">kim_boolean</a> </td>
+ <td class="paramname"> <em>in_allow_automatic_prompting</em> </td>
+ <td> ) </td>
+ <td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Tells KIM whether or not it is allowed to automatically present user interface.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>in_allow_automatic_prompting</em> </td><td>a boolean containing whether or not to prompt automatically. </td></tr>
+ </table>
+</dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+
+</div>
+</div><p>
+<a class="anchor" name="gfdf50a60bc513497e47852e43a02c8a9"></a><!-- doxytag: member="kim_library.h::kim_library_set_application_name" ref="gfdf50a60bc513497e47852e43a02c8a9" args="(kim_string in_application_name)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_library_set_application_name </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> </td>
+ <td class="paramname"> <em>in_application_name</em> </td>
+ <td> ) </td>
+ <td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Set the name of your application for KIM to use for user interface.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>in_application_name</em> </td><td>a string containing the localized name of your application. </td></tr>
+ </table>
+</dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd>On many operating systems KIM can determine the caller's application name automatically. This call exists for applications to use when those mechanisms fail or do not exist. </dd></dl>
+
+</div>
+</div><p>
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<a href="http://www.doxygen.org/index.html">
+<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
+</body>
+</html>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
- <tr><td valign="top"></td><td valign="top"><em>kim_preferences</em> </td><td>a preferences object. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_preferences</em> </td><td>a preferences object. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>in_index</em> </td><td>a index into the identities list (starting at 0). </td></tr>
<tr><td valign="top"></td><td valign="top"><em>out_identity</em> </td><td>on exit, the identity at <em>in_index</em> in <em>in_preferences</em>. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>out_options</em> </td><td>on exit, the options associated with identity at <em>in_index</em> in <em>in_favorite_identities</em>. May be KIM_OPTIONS_DEFAULT. Pass NULL if you do not want the options associated with the identity. Must be freed with <a class="el" href="group__kim__options__reference.html#gd8de9ea0a4eb9e0ffb8e3056a3899f55" title="Free memory associated with an options object.">kim_options_free()</a>. </td></tr>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<p>
<h2>Defines</h2>
<ul>
-<li><a class="anchor" name="g56c0b2760fef0565b0fe955164171ea9"></a><!-- doxytag: member="kim_selection_hints_reference::kim_hint_key_client_realm" ref="g56c0b2760fef0565b0fe955164171ea9" args="" -->
-#define <b>kim_hint_key_client_realm</b> "kim_hint_key_client_realm"
-<li><a class="anchor" name="g41fb9619b728af091ef298e1d4a085ed"></a><!-- doxytag: member="kim_selection_hints_reference::kim_hint_key_user" ref="g41fb9619b728af091ef298e1d4a085ed" args="" -->
-#define <b>kim_hint_key_user</b> "kim_hint_key_user"
-<li><a class="anchor" name="g71c0a4d5ca46193689deda51878fc6a9"></a><!-- doxytag: member="kim_selection_hints_reference::kim_hint_key_service_realm" ref="g71c0a4d5ca46193689deda51878fc6a9" args="" -->
-#define <b>kim_hint_key_service_realm</b> "kim_hint_key_service_realm"
-<li><a class="anchor" name="g60bccf17408f6026cd07106b14bd8231"></a><!-- doxytag: member="kim_selection_hints_reference::kim_hint_key_service" ref="g60bccf17408f6026cd07106b14bd8231" args="" -->
-#define <b>kim_hint_key_service</b> "kim_hint_key_service"
-<li><a class="anchor" name="g6e2d527be39beced1739b092362a1e9b"></a><!-- doxytag: member="kim_selection_hints_reference::kim_hint_key_server" ref="g6e2d527be39beced1739b092362a1e9b" args="" -->
-#define <b>kim_hint_key_server</b> "kim_hint_key_server"
-<li><a class="anchor" name="g616972df29e427085479c0c94133916e"></a><!-- doxytag: member="kim_selection_hints_reference::kim_hint_key_service_identity" ref="g616972df29e427085479c0c94133916e" args="" -->
-#define <b>kim_hint_key_service_identity</b> "kim_hint_key_service_identity"
+<li>#define <a class="el" href="group__kim__selection__hints__reference.html#g56c0b2760fef0565b0fe955164171ea9">kim_hint_key_client_realm</a> "kim_hint_key_client_realm"
+<li>#define <a class="el" href="group__kim__selection__hints__reference.html#g41fb9619b728af091ef298e1d4a085ed">kim_hint_key_user</a> "kim_hint_key_user"
+<li>#define <a class="el" href="group__kim__selection__hints__reference.html#g71c0a4d5ca46193689deda51878fc6a9">kim_hint_key_service_realm</a> "kim_hint_key_service_realm"
+<li>#define <a class="el" href="group__kim__selection__hints__reference.html#g60bccf17408f6026cd07106b14bd8231">kim_hint_key_service</a> "kim_hint_key_service"
+<li>#define <a class="el" href="group__kim__selection__hints__reference.html#g6e2d527be39beced1739b092362a1e9b">kim_hint_key_server</a> "kim_hint_key_server"
+<li>#define <a class="el" href="group__kim__selection__hints__reference.html#g616972df29e427085479c0c94133916e">kim_hint_key_service_identity</a> "kim_hint_key_service_identity"
</ul>
<h2>Functions</h2>
<ul>
<dl class="el"><dd class="mdescRight">Create a new selection hints object. <a href="#g261c1e59de5576e3782e7d45bc9a8bac"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#g879d7f73cd4644a9f5a9693acea55e02">kim_selection_hints_copy</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> *out_selection_hints, <a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> in_selection_hints)
<dl class="el"><dd class="mdescRight">Copy a selection hints object. <a href="#g879d7f73cd4644a9f5a9693acea55e02"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#gf9b194c40cd569bfe6b37b7f54fc5ed8">kim_selection_hints_set_hint</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> io_selection_hints, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_hint_key, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_hint_string)
<dl class="el"><dd class="mdescRight">Set the string value of a hint used for identity selection. <a href="#gf9b194c40cd569bfe6b37b7f54fc5ed8"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#g6dbcdbaae154f490ae313d30f7fc51b3">kim_selection_hints_get_hint</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> in_selection_hints, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_hint_key, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_hint_string)
-<dl class="el"><dd class="mdescRight">Get the string value of a hint used for identity selection. <a href="#g6dbcdbaae154f490ae313d30f7fc51b3"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#g8fe2f3a8723cacff9241d81a71f4532f">kim_selection_hints_set_application_name</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> io_selection_hints, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_application_name)
-<dl class="el"><dd class="mdescRight">Set the application name for use in user interaction. <a href="#g8fe2f3a8723cacff9241d81a71f4532f"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#g21e88d5a8168ec7f7023faf171adb621">kim_selection_hints_get_application_name</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> in_selection_hints, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_application_name)
-<dl class="el"><dd class="mdescRight">Get the application name for use in user interaction. <a href="#g21e88d5a8168ec7f7023faf171adb621"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#gcc6ec35aa53cad7a2eca07ceea66a3c6">kim_selection_hints_set_explanation</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> io_selection_hints, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_explanation)
+<dl class="el"><dd class="mdescRight">Get the string value of a hint used for identity selection. <a href="#g6dbcdbaae154f490ae313d30f7fc51b3"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#gcc6ec35aa53cad7a2eca07ceea66a3c6">kim_selection_hints_set_explanation</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> io_selection_hints, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_explanation)
<dl class="el"><dd class="mdescRight">Set the strings used to prompt the user to select the identity. <a href="#gcc6ec35aa53cad7a2eca07ceea66a3c6"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#g8fce520fbadcdd10f8928fbea43083ee">kim_selection_hints_get_explanation</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> in_selection_hints, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_explanation)
<dl class="el"><dd class="mdescRight">Get the strings used to prompt the user to select the identity. <a href="#g8fce520fbadcdd10f8928fbea43083ee"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#g2cbc1a52c6fa4c94aa85acf7abb205c4">kim_selection_hints_set_options</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> io_selection_hints, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
<dl class="el"><dd class="mdescRight">Set the options which will be used if credentials need to be acquired. <a href="#g2cbc1a52c6fa4c94aa85acf7abb205c4"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#gb8c6aea4ac6b55d77585a5f3047dd3e7">kim_selection_hints_get_options</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> in_selection_hints, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> *out_options)
<dl class="el"><dd class="mdescRight">Add an entry for the selection hints to the selection hints cache, replacing any existing entry. <a href="#ge33ab4dcf213c7fcb43eea3f35aeef09"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__selection__hints__reference.html#g8bc79c133df171182813ca2a8773d19c">kim_selection_hints_forget_identity</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> in_selection_hints)
<dl class="el"><dd class="mdescRight">Remove an entry for the selection hints from the selection hints cache. <a href="#g8bc79c133df171182813ca2a8773d19c"></a><br></dl><li>void <a class="el" href="group__kim__selection__hints__reference.html#gb8e8fb20d4726f293d6185c11c78b0aa">kim_selection_hints_free</a> (<a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> *io_selection_hints)
<dl class="el"><dd class="mdescRight">Free memory associated with a selection hints object. <a href="#gb8e8fb20d4726f293d6185c11c78b0aa"></a><br></dl></ul>
+<hr><h2>Define Documentation</h2>
+<a class="anchor" name="g56c0b2760fef0565b0fe955164171ea9"></a><!-- doxytag: member="kim_selection_hints.h::kim_hint_key_client_realm" ref="g56c0b2760fef0565b0fe955164171ea9" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define kim_hint_key_client_realm "kim_hint_key_client_realm" </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+A client identity in this realm. See <a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a> for more information
+</div>
+</div><p>
+<a class="anchor" name="g41fb9619b728af091ef298e1d4a085ed"></a><!-- doxytag: member="kim_selection_hints.h::kim_hint_key_user" ref="g41fb9619b728af091ef298e1d4a085ed" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define kim_hint_key_user "kim_hint_key_user" </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+A client identity whose first component is this user string. See <a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a> for more information
+</div>
+</div><p>
+<a class="anchor" name="g71c0a4d5ca46193689deda51878fc6a9"></a><!-- doxytag: member="kim_selection_hints.h::kim_hint_key_service_realm" ref="g71c0a4d5ca46193689deda51878fc6a9" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define kim_hint_key_service_realm "kim_hint_key_service_realm" </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+A client identity which has obtained a service credential for this realm. See <a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a> for more information
+</div>
+</div><p>
+<a class="anchor" name="g60bccf17408f6026cd07106b14bd8231"></a><!-- doxytag: member="kim_selection_hints.h::kim_hint_key_service" ref="g60bccf17408f6026cd07106b14bd8231" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define kim_hint_key_service "kim_hint_key_service" </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+A client identity which has obtained a service credential for this service. See <a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a> for more information
+</div>
+</div><p>
+<a class="anchor" name="g6e2d527be39beced1739b092362a1e9b"></a><!-- doxytag: member="kim_selection_hints.h::kim_hint_key_server" ref="g6e2d527be39beced1739b092362a1e9b" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define kim_hint_key_server "kim_hint_key_server" </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+A client identity which has obtained a service credential for this server. See <a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a> for more information
+</div>
+</div><p>
+<a class="anchor" name="g616972df29e427085479c0c94133916e"></a><!-- doxytag: member="kim_selection_hints.h::kim_hint_key_service_identity" ref="g616972df29e427085479c0c94133916e" args="" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname">#define kim_hint_key_service_identity "kim_hint_key_service_identity" </td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+The client identity which has obtained a service credential for this service identity. See <a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a> for more information
+</div>
+</div><p>
<hr><h2>Function Documentation</h2>
<a class="anchor" name="g261c1e59de5576e3782e7d45bc9a8bac"></a><!-- doxytag: member="kim_selection_hints.h::kim_selection_hints_create" ref="g261c1e59de5576e3782e7d45bc9a8bac" args="(kim_selection_hints *out_selection_hints, kim_string in_application_identifier)" -->
<div class="memitem">
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>in_selection_hints</em> </td><td>a selection hints object. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>in_hint_key</em> </td><td>A string representing the type of hint to obtain. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>out_hint_string</em> </td><td>
A string representation of the hint <em>in_hint_key</em> in <em>in_selection_hints</em>. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_hint_string</em> </td><td>
On exit, a string representation of the hint <em>in_hint_key</em> in <em>in_selection_hints</em>. If the hint is not set, sets the value pointed to by <em>out_hint_string</em> to NULL; Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__selection__hints__reference.html#gf9b194c40cd569bfe6b37b7f54fc5ed8" title="Set the string value of a hint used for identity selection.">kim_selection_hints_set_hint()</a> </dd></dl>
-</div>
-</div><p>
-<a class="anchor" name="g8fe2f3a8723cacff9241d81a71f4532f"></a><!-- doxytag: member="kim_selection_hints.h::kim_selection_hints_set_application_name" ref="g8fe2f3a8723cacff9241d81a71f4532f" args="(kim_selection_hints io_selection_hints, kim_string in_application_name)" -->
-<div class="memitem">
-<div class="memproto">
- <table class="memname">
- <tr>
- <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_selection_hints_set_application_name </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> </td>
- <td class="paramname"> <em>io_selection_hints</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> </td>
- <td class="paramname"> <em>in_application_name</em></td><td> </td>
- </tr>
- <tr>
- <td></td>
- <td>)</td>
- <td></td><td></td><td width="100%"></td>
- </tr>
- </table>
-</div>
-<div class="memdoc">
-
-<p>
-Set the application name for use in user interaction.
-<p>
-<dl compact><dt><b>Parameters:</b></dt><dd>
- <table border="0" cellspacing="2" cellpadding="0">
- <tr><td valign="top"></td><td valign="top"><em>io_selection_hints</em> </td><td>a selection hints object to modify. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_application_name</em> </td><td>a localized string containing the full name of the application. </td></tr>
- </table>
-</dl>
-<dl class="note" compact><dt><b>Note:</b></dt><dd>If you do not call this function KIM will attempt to determine the application name at runtime. If that fails (the functionality is only available on some platforms) then KIM will use the application identity string. </dd></dl>
-<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
-<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__selection__hints__reference.html#g21e88d5a8168ec7f7023faf171adb621" title="Get the application name for use in user interaction.">kim_selection_hints_get_application_name()</a> </dd></dl>
-
-</div>
-</div><p>
-<a class="anchor" name="g21e88d5a8168ec7f7023faf171adb621"></a><!-- doxytag: member="kim_selection_hints.h::kim_selection_hints_get_application_name" ref="g21e88d5a8168ec7f7023faf171adb621" args="(kim_selection_hints in_selection_hints, kim_string *out_application_name)" -->
-<div class="memitem">
-<div class="memproto">
- <table class="memname">
- <tr>
- <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_selection_hints_get_application_name </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gda34b5ed23fb7cc4e4db533edec4e942">kim_selection_hints</a> </td>
- <td class="paramname"> <em>in_selection_hints</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> * </td>
- <td class="paramname"> <em>out_application_name</em></td><td> </td>
- </tr>
- <tr>
- <td></td>
- <td>)</td>
- <td></td><td></td><td width="100%"></td>
- </tr>
- </table>
-</div>
-<div class="memdoc">
-
-<p>
-Get the application name for use in user interaction.
-<p>
-<dl compact><dt><b>Parameters:</b></dt><dd>
- <table border="0" cellspacing="2" cellpadding="0">
- <tr><td valign="top"></td><td valign="top"><em>in_selection_hints</em> </td><td>a selection hints object. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>out_application_name</em> </td><td>on exit, the localized full name of the application specified in <em>in_selection_hints</em>. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>. </td></tr>
- </table>
-</dl>
-<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
-<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__selection__hints__reference.html#g8fe2f3a8723cacff9241d81a71f4532f" title="Set the application name for use in user interaction.">kim_selection_hints_set_application_name()</a> </dd></dl>
-
</div>
</div><p>
<a class="anchor" name="gcc6ec35aa53cad7a2eca07ceea66a3c6"></a><!-- doxytag: member="kim_selection_hints.h::kim_selection_hints_set_explanation" ref="gcc6ec35aa53cad7a2eca07ceea66a3c6" args="(kim_selection_hints io_selection_hints, kim_string in_explanation)" -->
<tr><td valign="top"></td><td valign="top"><em>in_explanation</em> </td><td>a localized string describing why the caller needs the identity. </td></tr>
</table>
</dl>
-<dl class="note" compact><dt><b>Note:</b></dt><dd>If the application only does one thing (the reason it needs an identity is obvious) then you may not need to call this function. You may still need to call <a class="el" href="group__kim__selection__hints__reference.html#g8fe2f3a8723cacff9241d81a71f4532f" title="Set the application name for use in user interaction.">kim_selection_hints_set_application_name()</a> </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd>If the application only does one thing (the reason it needs an identity is obvious) then you may not need to call this function. </dd></dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__selection__hints__reference.html#g8fce520fbadcdd10f8928fbea43083ee" title="Get the strings used to prompt the user to select the identity.">kim_selection_hints_get_explanation()</a> </dd></dl>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<p>
<h2>Functions</h2>
<ul>
-<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__string__reference.html#g
010c32962b2639f4dbc0ebd8303d7c4a">kim_string_create_for_error</a> (<a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_string, <a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> in_error)
-<dl class="el"><dd class="mdescRight">Get a text description of an error
. <a href="#g010c32962b2639f4dbc0ebd8303d7c4a"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__string__reference.html#g75780c8ab031eaab2b588014c7078b58">kim_string_copy</a> (<a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_string, const <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_string)
+<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__string__reference.html#g
f1f7a5aba5f87b139f1b1db1430ca94b">kim_string_create_for_last_error</a> (<a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_string, <a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> in_error)
+<dl class="el"><dd class="mdescRight">Get a text description of an error
suitable for display to the user. <a href="#gf1f7a5aba5f87b139f1b1db1430ca94b"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__string__reference.html#g75780c8ab031eaab2b588014c7078b58">kim_string_copy</a> (<a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_string, const <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_string)
<dl class="el"><dd class="mdescRight">Copy a string. <a href="#g75780c8ab031eaab2b588014c7078b58"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__string__reference.html#g504d17196463065016bfc11ef8ff44bb">kim_string_compare</a> (<a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_string, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_compare_to_string, <a class="el" href="group__kim__types__reference.html#gae48569e847ff6af9d10add42a4338e7">kim_comparison</a> *out_comparison)
<dl class="el"><dd class="mdescRight">Compare two strings. <a href="#g504d17196463065016bfc11ef8ff44bb"></a><br></dl><li>void <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc">kim_string_free</a> (<a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *io_string)
<dl class="el"><dd class="mdescRight">Free memory associated with a string. <a href="#g7e7207329022e97473ec71574e52a1fc"></a><br></dl></ul>
<hr><h2>Function Documentation</h2>
-<a class="anchor" name="g010c32962b2639f4dbc0ebd8303d7c4a"></a><!-- doxytag: member="kim_string.h::kim_string_create_for_error" ref="g010c32962b2639f4dbc0ebd8303d7c4a" args="(kim_string *out_string, kim_error in_error)" -->
+<a class="anchor" name="gf1f7a5aba5f87b139f1b1db1430ca94b"></a><!-- doxytag: member="kim_string.h::kim_string_create_for_last_error" ref="gf1f7a5aba5f87b139f1b1db1430ca94b" args="(kim_string *out_string, kim_error in_error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_string_create_for_error </td>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_string_create_for_last_error </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> * </td>
<td class="paramname"> <em>out_string</em>, </td>
<div class="memdoc">
<p>
-Get a text description of an error.
+Get a text description of an error suitable for display to the user.
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
- <tr><td valign="top"></td><td valign="top"><em>out_string</em> </td><td>
on exit, a human-readable UTF-8 string describing the error represented by <em>in_error</em>. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_error</em> </td><td>an error code. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_string</em> </td><td>
On success, a human-readable UTF-8 string describing the error representedby <em>in_error</em>. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_error</em> </td><td>an error code. Used to verify that the correct error string will be returned (see note below). </td></tr>
</table>
</dl>
-<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, </dd></dl>
-<dl class="note" compact><dt><b>Note:</b></dt><dd>If the caller needs an error string, this API should be called immediately after a KIM API returns an error. </dd></dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, KIM_NO_ERROR. </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd>This API is implemented using thread local storage. It should be called immediately after a KIM API returns an error code so that the correct string is returned. The returned copy may then be held by the caller until needed. If <em>in_error</em> does not match the last saved error KIM may return a less descriptive string. </dd></dl>
</div>
</div><p>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<p>
<h2>Defines</h2>
<ul>
-<li>#define <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a> ((<a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a>) 0)
<li>#define <a class="el" href="group__kim__types__reference.html#g322f65f7d72470d57e21a4c8777ee9fb">KIM_IDENTITY_ANY</a> ((<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a>) NULL)
<li>#define <a class="el" href="group__kim__types__reference.html#ge0384d3f6d9108e3ec84e322c61235a7">KIM_OPTIONS_DEFAULT</a> ((<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a>) NULL)
<li>#define <a class="el" href="group__kim__types__reference.html#g88d98fa3bd4ca00913bff414d65c3590">KIM_OPTIONS_START_IMMEDIATELY</a> ((kim_time_t) 0)
+<li>#define <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a> ((<a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a>) 0)
<li>#define <a class="el" href="group__kim__types__reference.html#g4d38dda6e945454742fd5c0e2038a370">kim_comparison_is_less_than</a>(c) (c < 0)
<li>#define <a class="el" href="group__kim__types__reference.html#g82110d33192b3618a1c3d8d51965e80f">kim_comparison_is_equal_to</a>(c) (c == 0)
<li>#define <a class="el" href="group__kim__types__reference.html#g95693c83e1981bd08bc616ab947ee01d">kim_comparison_is_greater_than</a>(c) (c > 0)
<li>typedef uint64_t <a class="el" href="group__kim__types__reference.html#g098e3611b2bc3af38b5f06838153165d">kim_count</a>
<li>typedef int <a class="el" href="group__kim__types__reference.html#g6f8afd4047c4fe420c05f940f89ffba0">kim_boolean</a>
<li>typedef int <a class="el" href="group__kim__types__reference.html#gae48569e847ff6af9d10add42a4338e7">kim_comparison</a>
-<li>typedef const char * <a class="el" href="group__kim__types__reference.html#g142374af75d94b931badf53148a7c09c">kim_context</a>
<li>typedef const char * <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a>
<li>typedef struct <br>
kim_identity_opaque * <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a>
}
</ul>
<hr><h2>Define Documentation</h2>
-<a class="anchor" name="g8712727bab9e6b02712a8a01285441d1"></a><!-- doxytag: member="kim_error.h::KIM_NO_ERROR" ref="g8712727bab9e6b02712a8a01285441d1" args="" -->
+<a class="anchor" name="g322f65f7d72470d57e21a4c8777ee9fb"></a><!-- doxytag: member="kim_identity.h::KIM_IDENTITY_ANY" ref="g322f65f7d72470d57e21a4c8777ee9fb" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">#define KIM_NO_ERROR ((<a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a>) 0) </td>
+ <td class="memname">#define KIM_IDENTITY_ANY ((<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a>) NULL) </td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
-The kim_error_t returned when no error occurred.
+Constant to specify any Kerberos identity is acceptable.
</div>
</div><p>
-<a class="anchor" name="g322f65f7d72470d57e21a4c8777ee9fb"></a><!-- doxytag: member="kim_identity.h::KIM_IDENTITY_ANY" ref="g322f65f7d72470d57e21a4c8777ee9fb" args="" -->
+<a class="anchor" name="ge0384d3f6d9108e3ec84e322c61235a7"></a><!-- doxytag: member="kim_options.h::KIM_OPTIONS_DEFAULT" ref="ge0384d3f6d9108e3ec84e322c61235a7" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">#define KIM_IDENTITY_ANY ((<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a>) NULL) </td>
+ <td class="memname">#define KIM_OPTIONS_DEFAULT ((<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a>) NULL) </td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
-Constant to specify any Kerberos identity is acceptable.
+Specifies the user's default options.
</div>
</div><p>
-<a class="anchor" name="ge0384d3f6d9108e3ec84e322c61235a7"></a><!-- doxytag: member="kim_options.h::KIM_OPTIONS_DEFAULT" ref="ge0384d3f6d9108e3ec84e322c61235a7" args="" -->
+<a class="anchor" name="g88d98fa3bd4ca00913bff414d65c3590"></a><!-- doxytag: member="kim_options.h::KIM_OPTIONS_START_IMMEDIATELY" ref="g88d98fa3bd4ca00913bff414d65c3590" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">#define KIM_OPTIONS_DEFAULT ((<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a>) NULL) </td>
+ <td class="memname">#define KIM_OPTIONS_START_IMMEDIATELY ((kim_time_t) 0) </td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
-Specifies the user's default options.
+Specifies that credentials should be valid immediately.
</div>
</div><p>
-<a class="anchor" name="g88d98fa3bd4ca00913bff414d65c3590"></a><!-- doxytag: member="kim_options.h::KIM_OPTIONS_START_IMMEDIATELY" ref="g88d98fa3bd4ca00913bff414d65c3590" args="" -->
+<a class="anchor" name="g8712727bab9e6b02712a8a01285441d1"></a><!-- doxytag: member="kim_types.h::KIM_NO_ERROR" ref="g8712727bab9e6b02712a8a01285441d1" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">#define KIM_OPTIONS_START_IMMEDIATELY ((kim_time_t) 0) </td>
+ <td class="memname">#define KIM_NO_ERROR ((<a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a>) 0) </td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
-Specifies that credentials should be valid immediately.
+No error value for the kim_error type.
</div>
</div><p>
<a class="anchor" name="g4d38dda6e945454742fd5c0e2038a370"></a><!-- doxytag: member="kim_types.h::kim_comparison_is_less_than" ref="g4d38dda6e945454742fd5c0e2038a370" args="(c)" -->
<div class="memdoc">
<p>
-Convenience macro for interpreting kim_comparison_t.
+Convenience macro for interpreting <a class="el" href="group__kim__types__reference.html#gae48569e847ff6af9d10add42a4338e7">kim_comparison</a>.
</div>
</div><p>
<a class="anchor" name="g82110d33192b3618a1c3d8d51965e80f"></a><!-- doxytag: member="kim_types.h::kim_comparison_is_equal_to" ref="g82110d33192b3618a1c3d8d51965e80f" args="(c)" -->
<div class="memdoc">
<p>
-Convenience macro for interpreting kim_comparison_t.
+Convenience macro for interpreting <a class="el" href="group__kim__types__reference.html#gae48569e847ff6af9d10add42a4338e7">kim_comparison</a>.
</div>
</div><p>
<a class="anchor" name="g95693c83e1981bd08bc616ab947ee01d"></a><!-- doxytag: member="kim_types.h::kim_comparison_is_greater_than" ref="g95693c83e1981bd08bc616ab947ee01d" args="(c)" -->
<div class="memdoc">
<p>
-Convenience macro for interpreting kim_comparison_t.
+Convenience macro for interpreting <a class="el" href="group__kim__types__reference.html#gae48569e847ff6af9d10add42a4338e7">kim_comparison</a>.
</div>
</div><p>
<hr><h2>Typedef Documentation</h2>
<div class="memdoc">
<p>
-The KIM Error type. See <a class="el" href="kim_error_overview.html">KIM Error Overview</a> for more information.
+The KIM Error type.
</div>
</div><p>
<a class="anchor" name="g3da22452677b45753d40e07f3904dff5"></a><!-- doxytag: member="kim_types.h::kim_time" ref="g3da22452677b45753d40e07f3904dff5" args="" -->
A comparison between two sortable objects. <ul>
<li>Less than 0 means the first object is less than the second. </li>
<li>0 means the two objects are identical. </li>
-<li>Greater than 0 means the first object is greater than the second. <dl class="note" compact><dt><b>Note:</b></dt><dd>Convenience macros are provided for interpreting
kim_comparison_ts to improve code readability. See <a class="el" href="group__kim__types__reference.html#g4d38dda6e945454742fd5c0e2038a370">kim_comparison_is_less_than()</a>, kim_comparison_is_equal() and <a class="el" href="group__kim__types__reference.html#g95693c83e1981bd08bc616ab947ee01d">kim_comparison_is_greater_than()</a> </dd></dl>
+<li>Greater than 0 means the first object is greater than the second. <dl class="note" compact><dt><b>Note:</b></dt><dd>Convenience macros are provided for interpreting
<a class="el" href="group__kim__types__reference.html#gae48569e847ff6af9d10add42a4338e7">kim_comparison</a> values to improve code readability. See <a class="el" href="group__kim__types__reference.html#g4d38dda6e945454742fd5c0e2038a370">kim_comparison_is_less_than()</a>, <a class="el" href="group__kim__types__reference.html#g82110d33192b3618a1c3d8d51965e80f">kim_comparison_is_equal_to()</a> and <a class="el" href="group__kim__types__reference.html#g95693c83e1981bd08bc616ab947ee01d">kim_comparison_is_greater_than()</a> </dd></dl>
</li>
</ul>
-</div>
-</div><p>
-<a class="anchor" name="g142374af75d94b931badf53148a7c09c"></a><!-- doxytag: member="kim_types.h::kim_context" ref="g142374af75d94b931badf53148a7c09c" args="" -->
-<div class="memitem">
-<div class="memproto">
- <table class="memname">
- <tr>
- <td class="memname">typedef const char* <a class="el" href="group__kim__types__reference.html#g142374af75d94b931badf53148a7c09c">kim_context</a> </td>
- </tr>
- </table>
-</div>
-<div class="memdoc">
-
-<p>
-The KIM Context type. See kim_context_overview for more information.
</div>
</div><p>
<a class="anchor" name="geea99aa292876e06003b7480087eecb0"></a><!-- doxytag: member="kim_types.h::kim_string" ref="geea99aa292876e06003b7480087eecb0" args="" -->
<div class="memdoc">
<p>
-A KIM Credential Iterator object. See kim_credential_iterator_t for more information.
+A KIM Credential Iterator object. See <a class="el" href="kim_credential_overview.html#kim_credential_iterator">Iterating over the Credentials in a CCache</a> for more information.
</div>
</div><p>
<a class="anchor" name="ge57b4df3376c4a34a119078a7f4a0030"></a><!-- doxytag: member="kim_types.h::kim_credential" ref="ge57b4df3376c4a34a119078a7f4a0030" args="" -->
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<b>KIM Options (kim_options_t)</b> control options for credential acquisition:<ul>
<li><a class="el" href="kim_options_overview.html">KIM Options Overview</a></li><li><a class="el" href="group__kim__options__reference.html">KIM Options Reference Documentation</a></li></ul>
<p>
-<b>KIM Realms List (kim_favorite_identities_t)</b> views and edits the current user's favorite realms list:<ul>
-<li>kim_favorite_identities_overview</li><li>kim_favorite_identities_reference</li></ul>
-<p>
<b>KIM Preferences (kim_preferences_t)</b> views and edits the current user's preferences:<ul>
<li><a class="el" href="kim_preferences_overview.html">KIM Preferences Overview</a></li><li><a class="el" href="group__kim__preferences__reference.html">KIM Preferences Documentation</a></li></ul>
<h2><a class="anchor" name="utility_apis">
The high and low level APIs depend on the following basic utility classes to manage generic types.<p>
<b>KIM String (kim_string_t)</b> provides memory management for an immutable string:<ul>
<li><a class="el" href="kim_string_overview.html">KIM String Overview</a></li><li><a class="el" href="group__kim__string__reference.html">KIM String Reference Documentation</a></li></ul>
-<p>
-<b>KIM Error (kim_error_t)</b> provides a machine and user-readable error message:<ul>
-<li><a class="el" href="kim_error_overview.html">KIM Error Overview</a></li><li><a class="el" href="group__kim__error__reference.html">KIM Error Reference Documentation</a></li></ul>
<h2><a class="anchor" name="types">
Types and Constants</a></h2>
<ul>
<li><a class="el" href="group__kim__types__reference.html">KIM Types and Constants</a> </li>
</ul>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#g01b4cbb88abf6aafd2efdaad91d74f0f" title="Get the time when the credentials in the ccache will no longer be renewable.">kim_ccache_get_renewal_expiration_time()</a> returns when the credential's in a ccache will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.</li>
</ul>
-See <a class="el" href="group__kim__ccache__reference.html">KIM CCache Reference Documentation</a> and <a class="el" href="group__kim__ccache__iterator__reference.html">KIM CCache Iterator Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<ul>
+<li><a class="el" href="group__kim__ccache__reference.html#g9ad7a15bf94420675c17bc61e83e47da" title="Get a kim_options object based on a ccache's credential attributes.">kim_ccache_get_options()</a> returns a kim_options object with the credential options of the credentials in the ccache. This function is intended to be used when adding an identity with existing credentials to the favorite identities list. By passing in the options returned by this call, future requests for the favorite identity will use the same credential options.</li>
+</ul>
+See <a class="el" href="group__kim__ccache__reference.html">KIM CCache Reference Documentation</a> and <a class="el" href="group__kim__ccache__iterator__reference.html">KIM CCache Iterator Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<li><a class="el" href="group__kim__credential__reference.html#gcf207597546b2397e8534c5bb354001a" title="Check if a credential is a ticket granting ticket.">kim_credential_is_tgt()</a> returns whether the credential is a TGT (ie: "ticket-granting ticket"). TGTs are credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>". These credentials allow the entity named by the client identity to obtain additional service credentials without resending shared secrets (such as a password) to the KDC. Kerberos uses TGTs to provide single sign-on authentication.</li>
</ul>
<ul>
-<li>kim_credential_is_valid() returns whether the credential is valid and if not why the credential is not valid.</li>
+<li><a class="el" href="group__kim__credential__reference.html#g214a9d5e947d7947132a2849826a93f4" title="Check the state of a credential (valid, expired, postdated, etc).">kim_credential_get_state()</a> returns a <a class="el" href="group__kim__types__reference.html#g48e19d7e4aec7dc6662149cab39bbe20">kim_credential_state</a> containing the state of the credential. Possible values are: * kim_credentials_state_valid * kim_credentials_state_expired * kim_credentials_state_not_yet_valid * kim_credentials_state_needs_validation * kim_credentials_state_address_mismatch</li>
</ul>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#gcae9e3e2b129e68215eedf588da60bea" title="Get the time when the credentials become valid.">kim_credential_get_start_time()</a> returns when the credential will become valid. Credentials may be "post-dated" which means that their lifetime starts sometime in the future. Note that when a post-dated credential's start time is reached, the credential must be validated. See <a class="el" href="kim_credential_overview.html#kim_credential_validate">Validating Credentials</a> for more information.</li>
<li><a class="el" href="group__kim__credential__reference.html#gba6367f04f832e086a8b0c01ebd3f77e" title="Get the time when the credentials will expire.">kim_credential_get_expiration_time()</a> returns when the credential will expire. Credentials are time limited by the lifetime of the credential. While you can request a credential of any lifetime, the KDC limits the credential lifetime to a administrator-defined maximum. Typically credential lifetime range from 10 to 21 hours.</li>
</ul>
<ul>
-<li><a class="el" href="group__kim__credential__reference.html#g4e50b4abf3efc36ed10c3049c9ff9a48" title="Get the time when the credentials will no longer be renewable.">kim_credential_get_renewal_expiration_time()</a> returns when the credential will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.</li>
+<li><a class="el" href="group__kim__credential__reference.html#g4e50b4abf3efc36ed10c3049c9ff9a48" title="Get the time when the credentials will no longer be renewable.">kim_credential_get_renewal_expiration_time()</a> returns when the credential will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return a renewal expiration time of 0.</li>
</ul>
-See <a class="el" href="group__kim__credential__reference.html">KIM Credential Reference Documentation</a> and <a class="el" href="group__kim__credential__iterator__reference.html">KIM Credential Iterator Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<ul>
+<li><a class="el" href="group__kim__credential__reference.html#g6d0cb540926a4d95923709a5104fb298" title="Get a kim_options object based on a credential's attributes.">kim_credential_get_options()</a> returns a kim_options object with the credential options of the credential. This function is intended to be used when adding an identity with existing credentials to the favorite identities list. By passing in the options returned by this call, future requests for the favorite identity will use the same credential options.</li>
+</ul>
+See <a class="el" href="group__kim__credential__reference.html">KIM Credential Reference Documentation</a> and <a class="el" href="group__kim__credential__iterator__reference.html">KIM Credential Iterator Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
To solve this problem, <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> takes information from the application in the form of a selection hints object and returns the best matching client identity, if one is available. See <a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a> for more information.<h2><a class="anchor" name="kim_identity_password">
Changing a Identity's Password</a></h2>
Many Kerberos sites use passwords for user accounts. Because passwords may be stolen or compromised, they must be frequently changed. KIM provides APIs to change the identity's password directly, and also handles changing the identity's password when it has expired.<p>
-<a class="el" href="group__kim__identity__reference.html#g660c28e70656127c7c723d50414675e8" title="Change the password for an identity.">kim_identity_change_password()</a> presents a user interface to obtain the old and new passwords from the user.
kim_identity_change_password_with_passwords() takes the old and new passwords as input, but may still present a user interface if it needs to obtain additional information to authenticate.<p>
+<a class="el" href="group__kim__identity__reference.html#g660c28e70656127c7c723d50414675e8" title="Change the password for an identity.">kim_identity_change_password()</a> presents a user interface to obtain the old and new passwords from the user.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>Not all identities have a password. Some sites use certificates (pkinit) and in the future there may be other authentication mechanisms (eg: smart cards).</dd></dl>
-See <a class="el" href="group__kim__identity__reference.html">KIM Identity Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__identity__reference.html">KIM Identity Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
Use <a class="el" href="group__kim__options__reference.html#g15ffe61f06334f4071e5b1ea6be62117" title="Set whether or not to request a proxiable credential.">kim_options_set_proxiable()</a> to change whether or not the Kerberos libraries request proxiable credentials. Use <a class="el" href="group__kim__options__reference.html#g0193dda96349a6e8d98d6154540a364e" title="Get whether or not to request a proxiable credential.">kim_options_get_proxiable()</a> to find out the current setting.<h3><a class="anchor" name="kim_options_service_name">
Service Name</a></h3>
Normally users acquire TGT credentials (ie "ticket granting tickets") and then use those credentials to acquire service credentials. This allows Kerberos to provide single sign-on while still providing mutual authentication to services. However, sometimes you just want an initial credential for a service. KIM options allows you to set the service name with <a class="el" href="group__kim__options__reference.html#g6e31c69a65efe32a5860125083d0b803" title="Set the service name to request a credential for.">kim_options_set_service_name()</a> and query it with <a class="el" href="group__kim__options__reference.html#gdf70addbc8221c252b1223b5e99dfa94" title="Get the service name to request a credential for.">kim_options_get_service_name()</a>.<p>
-See <a class="el" href="group__kim__options__reference.html">KIM Options Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__options__reference.html">KIM Options Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
First, you need to acquire the Favorite Identities stored in the user's preferences using <a class="el" href="group__kim__preferences__reference.html#gf1dc483fcb582add046d552da9b8485f" title="Create a new preferences object from the current user's preferences.">kim_preferences_create()</a>.<p>
Then use <a class="el" href="group__kim__preferences__reference.html#g39ff3407953fedfc861efda92f961f18" title="Get the number of favorite identities in a preferences object.">kim_preferences_get_number_of_favorite_identities()</a> and <a class="el" href="group__kim__preferences__reference.html#g3012077dfb1169ebbbf2d7bf17dbbfdf" title="Get the Nth favorite identity in a preferences object.">kim_preferences_get_favorite_identity_at_index()</a> to display the identities list. Use <a class="el" href="group__kim__preferences__reference.html#gd7ed54017b8d46414c550a87ab775a9d" title="Add a favorite identity to a preferences object.">kim_preferences_add_favorite_identity()</a> and <a class="el" href="group__kim__preferences__reference.html#g85a31ca25607660c9dc2b68527c71f52" title="Remove a favorite identity from a preferences object.">kim_preferences_remove_favorite_identity()</a> 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. If you wish to replace the identities list entirely, use <a class="el" href="group__kim__preferences__reference.html#gc28596bde36d790f569af33d50feedb8" title="Remove all favorite identities in a preferences object.">kim_preferences_remove_all_favorite_identities()</a> to clear the list before adding your identities.<p>
Once you are done editing the favorite identities list, store changes in the user's preference file using <a class="el" href="group__kim__preferences__reference.html#g6815e374d78e13714abcddc478145dd9" title="Synchronize a preferences object with the user's preferences, writing pending...">kim_preferences_synchronize()</a>.<p>
-See <a class="el" href="group__kim__preferences__reference.html">KIM Preferences Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__preferences__reference.html">KIM Preferences Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<dl class="note" compact><dt><b>Note:</b></dt><dd>Due to performance and information exposure concerns, currently all searching is done by examining the cache collection. In the future the KIM may also make network requests as part of its search algorithm. For example it might check to see if the TGT credentials in each ccache can obtain credentials for the service identity specified by the selection hints.</dd></dl>
<h2><a class="anchor" name="kim_selection_hints_selecting">
Selecting an Identity Using Selection Hints</a></h2>
-Once you have provided search criteria for selecting an identity, use <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> to obtain an identity object. You can then use
kim_identity_get_gss_name() to obtain a gss_name_t for use in gss_acquire_cred() or use <a class="el" href="group__kim__ccache__reference.html#g6ecc14b94ffb57ca8008d0a407bb9c7d" title="Find a ccache for a client identity in the cache collection.">kim_ccache_create_from_client_identity()</a> to obtain a ccache containing credentials for the identity.<p>
+Once you have provided search criteria for selecting an identity, use <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> to obtain an identity object. You can then use
<a class="el" href="group__kim__identity__reference.html#g094e916a4d31556c3ead03f85aafa603" title="Get the string representation of a identity.">kim_identity_get_string()</a> to obtain a krb5 principal string for use with gss_import_name() and gss_acquire_cred(). Alternatively, you can use <a class="el" href="group__kim__ccache__reference.html#g6ecc14b94ffb57ca8008d0a407bb9c7d" title="Find a ccache for a client identity in the cache collection.">kim_ccache_create_from_client_identity()</a> to obtain a ccache containing credentials for the identity.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> obtains an identity based on the current state of the selection hints object. If you change the selection hints object you must call <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> again.</dd></dl>
<h2><a class="anchor" name="kim_selection_hints_caching">
Selection Hint Caching Behavior</a></h2>
Selection Hint Prompting Behavior</a></h2>
If valid credentials for identity in the selection hints cache are unavailable or if no identity could be found using searching or caching when <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> is called, KIM may present a GUI to ask the user to select an identity or acquire credentials for an identity.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>Because of the caching behavior described above the user will only be prompted to choose an identity when setting up the application or when their identity stops working.</dd></dl>
-In order to let the user know why Kerberos needs their assistance, KIM displays the name of the application which requested the identity selection. Unfortunately, some platforms do not provide a runtime mechanism for determining the name of the calling process. If your application runs on one of these platforms (or is cross-platform) you should provide a localized version of its name with
<a class="el" href="group__kim__selection__hints__reference.html#g8fe2f3a8723cacff9241d81a71f4532f" title="Set the application name for use in user interaction.">kim_selection_hints_set_application_name()</a>. You can check what name will be used with <a class="el" href="group__kim__selection__hints__reference.html#g21e88d5a8168ec7f7023faf171adb621" title="Get the application name for use in user interaction.">kim_selection_hints_get_application_name()</a>.<p>
+In order to let the user know why Kerberos needs their assistance, KIM displays the name of the application which requested the identity selection. Unfortunately, some platforms do not provide a runtime mechanism for determining the name of the calling process. If your application runs on one of these platforms (or is cross-platform) you should provide a localized version of its name with
the private function <a class="el" href="group__kim__library__reference.html#gfdf50a60bc513497e47852e43a02c8a9" title="Set the name of your application for KIM to use for user interface.">kim_library_set_application_name()</a>.<p>
In many cases a single application may select different identities for different purposes. For example an email application might use different identities to check mail for different accounts. If your application has this property you may need to provide the user with a localized string describing how the identity will be used. You can specify this string with <a class="el" href="group__kim__selection__hints__reference.html#g8fce520fbadcdd10f8928fbea43083ee" title="Get the strings used to prompt the user to select the identity.">kim_selection_hints_get_explanation()</a>. You can find out what string will be used with <a class="el" href="group__kim__selection__hints__reference.html#gcc6ec35aa53cad7a2eca07ceea66a3c6" title="Set the strings used to prompt the user to select the identity.">kim_selection_hints_set_explanation()</a>.<p>
Since the user may choose to acquire credentials when selection an identity, KIM also provides <a class="el" href="group__kim__selection__hints__reference.html#g2cbc1a52c6fa4c94aa85acf7abb205c4" title="Set the options which will be used if credentials need to be acquired.">kim_selection_hints_set_options()</a> to set what credential acquisition options are used. <a class="el" href="group__kim__selection__hints__reference.html#gb8c6aea4ac6b55d77585a5f3047dd3e7" title="Get the options which will be used if credentials need to be acquired.">kim_selection_hints_get_options()</a> returns the options which will be used.<p>
If you need to disable user interaction, use <a class="el" href="group__kim__selection__hints__reference.html#g290210bc1cb57b49539cc7f8c0d8fa2c" title="Set whether or not KIM may interact with the user to select an identity.">kim_selection_hints_set_allow_user_interaction()</a>. Use <a class="el" href="group__kim__selection__hints__reference.html#g95691183f6a85b8208858bd948a64c55" title="Get whether or not KIM may interact with the user to select an identity.">kim_selection_hints_get_allow_user_interaction()</a> to find out whether or not user interaction is enabled. User interaction is enabled by default.<p>
-See <a class="el" href="group__kim__selection__hints__reference.html">KIM Selection Hints Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__selection__hints__reference.html">KIM Selection Hints Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</head><body>
<!-- Generated by Doxygen 1.5.3 -->
<h1><a class="anchor" name="kim_string_overview">KIM String Overview</a></h1>A UTF8 string.<p>
-Memory management routines are provided for runtime consistency on operating systems with shared libraries and multiple runtimes.<p>
-See <a class="el" href="group__kim__string__reference.html">KIM String Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+Memory management routines are provided for runtime consistency on operating systems with shared libraries and multiple runtimes.<h2><a class="anchor" name="kim_string_error_messages">
+KIM Error Messages</a></h2>
+Like most C APIs, the KIM API returns numeric error codes. These error codes may come from KIM, krb5 or GSS APIs. In most cases the caller will want to handle these error programmatically. However, in some circumstances the caller may wish to print an error string to the user.<p>
+One problem with just printing the error code to the user is that frequently the context behind the error has been lost. For example if KIM is trying to obtain credentials via referrals, it may fail partway through the process. In this case the error code will be KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN, which maps to "Client not found in Kerberos database". Unfortunately this error isn't terribly helpful because it doesn't tell the user whether they typoed their principal name or if referrals failed.<p>
+To avoid this problem, KIM maintains an explanatory string for the last error seen in each thread calling into KIM. If a caller wishes to display an error to the user, immediately after getting the error the caller should call <a class="el" href="group__kim__string__reference.html#gf1f7a5aba5f87b139f1b1db1430ca94b" title="Get a text description of an error suitable for display to the user.">kim_string_create_for_last_error()</a> to obtain a copy of the descriptive error message.<p>
+See <a class="el" href="group__kim__string__reference.html">KIM String Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<li><a class="el" href="group__kim__ccache__reference.html">KIM CCache Reference Documentation</a>
<li><a class="el" href="group__kim__credential__iterator__reference.html">KIM Credential Iterator Reference Documentation</a>
<li><a class="el" href="group__kim__credential__reference.html">KIM Credential Reference Documentation</a>
-<li><a class="el" href="group__kim__error__reference.html">KIM Error Reference Documentation</a>
<li><a class="el" href="group__kim__identity__reference.html">KIM Identity Reference Documentation</a>
+<li><a class="el" href="group__kim__library__reference.html">KIM Library Documentation</a>
<li><a class="el" href="group__kim__options__reference.html">KIM Options Reference Documentation</a>
<li><a class="el" href="group__kim__preferences__reference.html">KIM Preferences Documentation</a>
<li><a class="el" href="group__kim__selection__hints__reference.html">KIM Selection Hints Reference Documentation</a>
<li><a class="el" href="group__kim__string__reference.html">KIM String Reference Documentation</a>
<li><a class="el" href="group__kim__types__reference.html">KIM Types and Constants</a>
</ul>
-<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
* - \subpage kim_options_overview
* - \subpage kim_options_reference
*
- * <B>KIM Realms List (kim_favorite_identities_t)</B> views and edits the current user's favorite realms list:
- * - \subpage kim_favorite_identities_overview
- * - \subpage kim_favorite_identities_reference
- *
* <B>KIM Preferences (kim_preferences_t)</B> views and edits the current user's preferences:
* - \subpage kim_preferences_overview
* - \subpage kim_preferences_reference
* - \subpage kim_string_overview
* - \subpage kim_string_reference
*
- * <B>KIM Error (kim_error_t)</B> provides a machine and user-readable error message:
- * - \subpage kim_error_overview
- * - \subpage kim_error_reference
*
*
* \section types Types and Constants
* \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Compare ccache objects.
*/
-kim_error kim_ccache_compare (kim_ccache in_ccache,
- kim_ccache in_compare_to_ccache,
- kim_boolean *out_equal);
+kim_error kim_ccache_compare (kim_ccache in_ccache,
+ kim_ccache in_compare_to_ccache,
+ kim_comparison *out_comparison);
/*!
* \param in_ccache a ccache object.
kim_time *out_renewal_expiration_time);
/*!
- * \param kim_ccache a ccache object.
+ * \param in_ccache a ccache object.
* \param out_options on exit, an options object reflecting the ticket
* options of the credentials in \a in_ccache.
* \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* additional service credentials without resending shared secrets (such as a password)
* to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
*
- * \li #kim_credential_is_valid()
- * returns whether the credential is valid and if not why the credential is not valid.
+ * \li #kim_credential_get_state()
+ * returns a #kim_credential_state containing the state of the credential.
+ * Possible values are:
+ * * kim_credentials_state_valid
+ * * kim_credentials_state_expired
+ * * kim_credentials_state_not_yet_valid
+ * * kim_credentials_state_needs_validation
+ * * kim_credentials_state_address_mismatch
*
* \li #kim_credential_get_start_time()
* returns when the credential will become valid.
* password when it has expired.
*
* #kim_identity_change_password() presents a user interface to obtain the old and
- * new passwords from the user. #kim_identity_change_password_with_passwords() takes
- * the old and new passwords as input, but may still present a user interface if it
- * needs to obtain additional information to authenticate.
+ * new passwords from the user.
*
* \note Not all identities have a password. Some sites use certificates (pkinit)
* and in the future there may be other authentication mechanisms (eg: smart cards).
#include <kim/kim.h>
+/*!
+ * \defgroup kim_library_reference KIM Library Documentation
+ * @{
+ */
+
+/*! Do not present user interface */
#define KIM_UI_ENVIRONMENT_NONE 0
+/*! Automatically determine what user interface is appropriate (default). */
#define KIM_UI_ENVIRONMENT_AUTO 1
+/*! Present a graphical user interface */
#define KIM_UI_ENVIRONMENT_GUI 2
+/*! Present a command line user interface */
#define KIM_UI_ENVIRONMENT_CLI 3
+/*! An integer describing the type of user interface to use. */
typedef int kim_ui_environment;
-
+/*!
+ * \param in_ui_environment an integer value describing the type of user interface to use.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \note Set to KIM_UI_ENVIRONMENT_AUTO by default.
+ * \brief Tell KIM how to present UI from your application.
+ */
kim_error kim_library_set_ui_environment (kim_ui_environment in_ui_environment);
+/*!
+ * \param in_allow_access a boolean containing whether or not to touch the user's home directory.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \note This API is usually used for Kerberos authenticated home directories to prevent a deadlock.
+ * \brief Tells KIM whether or not it is allowed to touch the user's home directory.
+ */
kim_error kim_library_set_allow_home_directory_access (kim_boolean in_allow_access);
+/*!
+ * \param in_allow_automatic_prompting a boolean containing whether or not to prompt automatically.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Tells KIM whether or not it is allowed to automatically present user interface.
+ */
kim_error kim_library_set_allow_automatic_prompting (kim_boolean in_allow_automatic_prompting);
+/*!
+ * \param in_application_name a string containing the localized name of your application.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \note On many operating systems KIM can determine the caller's application
+ * name automatically. This call exists for applications to use when those
+ * mechanisms fail or do not exist.
+ * \brief Set the name of your application for KIM to use for user interface.
+ */
kim_error kim_library_set_application_name (kim_string in_application_name);
+/*!@}*/
#endif /* KIM_LIBRARY_H */
kim_count *out_number_of_identities);
/*!
- * \param kim_preferences a preferences object.
+ * \param in_preferences a preferences object.
* \param in_index a index into the identities list (starting at 0).
* \param out_identity on exit, the identity at \a in_index in \a in_preferences.
* Must be freed with kim_string_free().
*
* Once you have provided search criteria for selecting an identity, use
* #kim_selection_hints_get_identity() to obtain an identity object.
- * You can then use #kim_identity_get_gss_name() to obtain a gss_name_t
- * for use in gss_acquire_cred() or use
- * #kim_ccache_create_from_client_identity() to obtain a ccache containing
- * credentials for the identity.
+ * You can then use #kim_identity_get_string() to obtain a krb5 principal
+ * string for use with gss_import_name() and gss_acquire_cred(). Alternatively,
+ * you can use #kim_ccache_create_from_client_identity() to obtain a ccache
+ * containing credentials for the identity.
*
* \note #kim_selection_hints_get_identity() obtains an identity based on
* the current state of the selection hints object. If you change the
* mechanism for determining the name of the calling process. If your
* application runs on one of these platforms (or is cross-platform)
* you should provide a localized version of its name with
- * #kim_library_set_application_name().
+ * the private function #kim_library_set_application_name().
*
* In many cases a single application may select different identities for
* different purposes. For example an email application might use different
* @{
*/
+/*! A client identity in this realm.
+ * See \ref kim_selection_hints_overview for more information */
#define kim_hint_key_client_realm "kim_hint_key_client_realm"
+
+/*! A client identity whose first component is this user string.
+ * See \ref kim_selection_hints_overview for more information */
#define kim_hint_key_user "kim_hint_key_user"
+
+/*! A client identity which has obtained a service credential for this realm.
+ * See \ref kim_selection_hints_overview for more information */
#define kim_hint_key_service_realm "kim_hint_key_service_realm"
+
+/*! A client identity which has obtained a service credential for this service.
+ * See \ref kim_selection_hints_overview for more information */
#define kim_hint_key_service "kim_hint_key_service"
+
+/*! A client identity which has obtained a service credential for this server.
+ * See \ref kim_selection_hints_overview for more information */
#define kim_hint_key_server "kim_hint_key_server"
+
+/*! The client identity which has obtained a service credential for this service identity.
+ * See \ref kim_selection_hints_overview for more information */
#define kim_hint_key_service_identity "kim_hint_key_service_identity"
/*!
* To avoid this problem, KIM maintains an explanatory string for the last
* error seen in each thread calling into KIM. If a caller wishes to display
* an error to the user, immediately after getting the error the caller should
- * call #kim_string_create_for_error() to obtain a copy of the
+ * call #kim_string_create_for_last_error() to obtain a copy of the
* descriptive error message.
*
* See \ref kim_string_reference for information on specific APIs.
*/
/*!
- * The KIM Error type. See \ref kim_error_overview for more information.
+ * The KIM Error type.
*/
typedef int32_t kim_error;
+/*!
+ * No error value for the kim_error type.
+ */
#define KIM_NO_ERROR ((kim_error) 0)
/*!
* \li Less than 0 means the first object is less than the second.
* \li 0 means the two objects are identical.
* \li Greater than 0 means the first object is greater than the second.
- * \note Convenience macros are provided for interpreting kim_comparison_ts
- * to improve code readability.
- * See #kim_comparison_is_less_than(), #kim_comparison_is_equal() and
+ * \note Convenience macros are provided for interpreting #kim_comparison
+ * values to improve code readability.
+ * See #kim_comparison_is_less_than(), #kim_comparison_is_equal_to() and
* #kim_comparison_is_greater_than()
*/
typedef int kim_comparison;
/*!
- * Convenience macro for interpreting #kim_comparison_t.
+ * Convenience macro for interpreting #kim_comparison.
*/
#define kim_comparison_is_less_than(c) (c < 0)
/*!
- * Convenience macro for interpreting #kim_comparison_t.
+ * Convenience macro for interpreting #kim_comparison.
*/
#define kim_comparison_is_equal_to(c) (c == 0)
/*!
- * Convenience macro for interpreting #kim_comparison_t.
+ * Convenience macro for interpreting #kim_comparison.
*/
#define kim_comparison_is_greater_than(c) (c > 0)
-/*!
- * The KIM Context type. See \ref kim_context_overview for more information.
- */
-typedef const char *kim_context;
-
/*!
* The KIM String type. See \ref kim_string_overview for more information.
*/
typedef const char *kim_string;
-//struct kim_error_opaque;
-/*!
- * A KIM Error object. See \ref kim_error_overview for more information.
- */
-//typedef struct kim_error_opaque *kim_error;
-
struct kim_identity_opaque;
/*!
* A KIM Principal object. See \ref kim_identity_overview for more information.
struct kim_credential_iterator_opaque;
/*!
- * A KIM Credential Iterator object. See \ref kim_credential_iterator_t for more information.
+ * A KIM Credential Iterator object. See \ref kim_credential_iterator for more information.
*/
typedef struct kim_credential_iterator_opaque *kim_credential_iterator;
projects / krb5.git / commitdiff