Renamed error handling files to reflect what they do now.

Moved GUI code into OS-specific directory.
Fixed bugs in cache collection iterator routines where it was mishandling
the magic empty ccache created when the cache collection is empty.

ticket: 6055

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@20747 dc483132-0cff-0310-8789-dd5450dbe970

5 files changed, 53 insertions, 103 deletions

diff --git a/src/include/kim/kim.h b/src/include/kim/kim.h
index 893891def..19e82ecb6 100644
--- a/src/include/kim/kim.h
+++ b/src/include/kim/kim.h
@@ -30,8 +30,8 @@ extern "C" {
 #endif
 
 #include <kim/kim_types.h>
+#include <kim/kim_errors.h>
 #include <kim/kim_string.h>
-#include <kim/kim_error.h>
 #include <kim/kim_identity.h>
 #include <kim/kim_options.h>
 #include <kim/kim_selection_hints.h>
diff --git a/src/include/kim/kim_credential.h b/src/include/kim/kim_credential.h
index 88ccc5dce..c25b02e90 100644
--- a/src/include/kim/kim_credential.h
+++ b/src/include/kim/kim_credential.h
@@ -451,7 +451,8 @@ kim_error kim_credential_get_expiration_time (kim_credential  in_credential,
 /*!
  * \param in_credential               a credential object. 
  * \param out_renewal_expiration_time on exit, the time when \a in_credential will no longer 
- *                                    be renewable. May be in the past or future.
+ *                                    be renewable. May be in the past or future.  If 
+ *                                    credentials are not renewable at all, returns 0.
  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
  * \brief Get the time when the credentials will no longer be renewable.
  * \sa kim_ccache_get_renewal_expiration_time
@@ -459,7 +460,17 @@ kim_error kim_credential_get_expiration_time (kim_credential  in_credential,
 kim_error kim_credential_get_renewal_expiration_time (kim_credential  in_credential,
                                                       kim_time       *out_renewal_expiration_time);
 
+/*!
+ * \param in_credential       a credential object. 
+ * \param out_ticket_flags    on exit, the krb5 ticket flags for \a in_credential.
+ *                            See krb5 API documentation for the meaning of these flags.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
+ * \brief Get the krb5 ticket_flags for a credential.
+ */
+kim_error kim_credential_get_krb5_ticket_flags (kim_credential  in_credential,
+                                                krb5_flags     *out_ticket_flags);
 
+    
 /*!
  * \param in_credential       a credential object. 
  * \param in_client_identity  a client identity.
@@ -521,7 +532,7 @@ kim_error kim_credential_validate (kim_credential *io_credential,
 /*!
  * \param in_credential            a credential object containing a change
  *                                 password credential.  Use 
- *                                 #kim_credential_change_password to obtain
+ *                                 #kim_credential_create_for_change_password to obtain
  *                                 a change password credential.
  * \param in_identity              an identity to change the password for.  May
  *                                 be different than the identity the credential
diff --git a/src/include/kim/kim_error.h b/src/include/kim/kim_error.h
deleted file mode 100644
index 07c6d172f..000000000
--- a/src/include/kim/kim_error.h
+++ /dev/null
@@ -1,100 +0,0 @@
-/*
- * Copyright 2005-2006 Massachusetts Institute of Technology.
- * All Rights Reserved.
- *
- * Export of this software from the United States of America may
- * require a specific license from the United States Government.
- * It is the responsibility of any person or organization contemplating
- * export to obtain such a license before exporting.
- * 
- * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
- * distribute this software and its documentation for any purpose and
- * without fee is hereby granted, provided that the above copyright
- * notice appear in all copies and that both that copyright notice and
- * this permission notice appear in supporting documentation, and that
- * the name of M.I.T. not be used in advertising or publicity pertaining
- * to distribution of the software without specific, written prior
- * permission.  Furthermore if you modify this software you must label
- * your software as modified software and not distribute it in such a
- * fashion that it might be confused with the original M.I.T. software.
- * M.I.T. makes no representations about the suitability of
- * this software for any purpose.  It is provided "as is" without express
- * or implied warranty.
- */
-
-#ifndef KIM_ERROR_H
-#define KIM_ERROR_H
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#include <kim/kim_types.h>
-#include <kim/kim_error_code.h>
-
-/*!
- * \ingroup kim_types_reference
- * The kim_error_t returned when no error occurred. 
- */
-#define KIM_NO_ERROR                  ((kim_error) 0)
-    
-/*!
- * \page kim_error_overview KIM Error Overview
- *
- * 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.  
- *
- * 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.  
- *
- * 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_get_last_error_message() to obtain a copy of the  
- * descriptive error message.
- * 
- * Note that because this string is stored in thread-specific data, callers 
- * must call #kim_string_get_last_error_message() before calling any KIM APIs
- * or any other APIs which might call into KIM.  Callers who are not going
- * to display this error string immediately should also make a copy of it
- * so that it is not overwritten by the next call into KIM.
- *
- * See \ref kim_error_reference for information on specific APIs.
- */
-
-/*!
- * \defgroup kim_error_reference KIM Error Reference Documentation
- * @{
- */
-
-/*!
- * \param out_string On success, a human-readable UTF-8 string describing the 
- *                   error representedby \a in_error.  Must be freed with
- *                   kim_string_free().
- * \param in_error   an error code.  Used to verify that the correct error
- *                   string will be returned (see note below).
- * \return On success, KIM_NO_ERROR.  
- * \note 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 \a in_error does not match the last saved error KIM may return
- * a less descriptive string.
- * \brief Get a text description of an error suitable for display to the user.
- */
-kim_error kim_string_get_last_error_message (kim_string *out_string,
-                                             kim_error   in_error);
-
-/*!@}*/
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* KIM_ERROR_H */
diff --git a/src/include/kim/kim_string.h b/src/include/kim/kim_string.h
index 79cd0ee24..bc4f647e8 100644
--- a/src/include/kim/kim_string.h
+++ b/src/include/kim/kim_string.h
@@ -39,6 +39,27 @@ extern "C" {
  * Memory management routines are provided for runtime consistency on
  * operating systems with shared libraries and multiple runtimes.
  *
+ * \section kim_string_error_messages KIM Error Messages
+ *
+ * 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.  
+ *
+ * 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.  
+ *
+ * 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  
+ * descriptive error message.
+ *
  * See \ref kim_string_reference for information on specific APIs.
  */
 
@@ -60,6 +81,22 @@ extern "C" {
 kim_error kim_string_create_for_error (kim_string *out_string,
                                        kim_error   in_error);
 
+/*!
+ * \param out_string On success, a human-readable UTF-8 string describing the 
+ *                   error representedby \a in_error.  Must be freed with
+ *                   kim_string_free().
+ * \param in_error   an error code.  Used to verify that the correct error
+ *                   string will be returned (see note below).
+ * \return On success, KIM_NO_ERROR.  
+ * \note 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 \a in_error does not match the last saved error KIM may return
+ * a less descriptive string.
+ * \brief Get a text description of an error suitable for display to the user.
+ */
+kim_error kim_string_create_for_last_error (kim_string *out_string,
+                                            kim_error   in_error);
     
 /*!
  * \param out_string on exit, a new string object which is a copy of \a in_string.  
diff --git a/src/include/kim/kim_types.h b/src/include/kim/kim_types.h
index 545d7479c..8cf97246e 100644
--- a/src/include/kim/kim_types.h
+++ b/src/include/kim/kim_types.h
@@ -41,6 +41,8 @@ extern "C" {
  */
 typedef int32_t     kim_error;
 
+#define KIM_NO_ERROR ((kim_error) 0)
+
 /*!
  * A time value represented in seconds since January 1, 1970.
  */