summaryrefslogtreecommitdiffstats
path: root/src/include
diff options
context:
space:
mode:
authorAlexandra Ellwood <lxs@mit.edu>2008-08-19 16:43:17 +0000
committerAlexandra Ellwood <lxs@mit.edu>2008-08-19 16:43:17 +0000
commitd308f082c1e5a8009853956a96f80c5f9414de9e (patch)
tree160a5133e3af2f32d73e15fba02c983c8594a2e9 /src/include
parent6dca73af4ae57815687d4f5b919863bfc5658b19 (diff)
downloadkrb5-d308f082c1e5a8009853956a96f80c5f9414de9e.tar.gz
krb5-d308f082c1e5a8009853956a96f80c5f9414de9e.tar.xz
krb5-d308f082c1e5a8009853956a96f80c5f9414de9e.zip
Modified hints APIs to be a single API that takes string keys.
Removed error object. Changed error message API to use thread specific data. Split out debugging API into separate files. ticket: 6055 status: open git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@20670 dc483132-0cff-0310-8789-dd5450dbe970
Diffstat (limited to 'src/include')
-rw-r--r--src/include/k5-thread.h1
-rw-r--r--src/include/kim/kim_ccache.h50
-rw-r--r--src/include/kim/kim_credential.h36
-rw-r--r--src/include/kim/kim_error.h94
-rw-r--r--src/include/kim/kim_identity.h28
-rw-r--r--src/include/kim/kim_options.h110
-rw-r--r--src/include/kim/kim_preferences.h56
-rw-r--r--src/include/kim/kim_selection_hints.h178
-rw-r--r--src/include/kim/kim_string.h24
-rw-r--r--src/include/kim/kim_types.h13
10 files changed, 246 insertions, 344 deletions
diff --git a/src/include/k5-thread.h b/src/include/k5-thread.h
index 4122c81511..dbc1a6fd71 100644
--- a/src/include/k5-thread.h
+++ b/src/include/k5-thread.h
@@ -736,6 +736,7 @@ typedef enum {
K5_KEY_GSS_KRB5_SET_CCACHE_OLD_NAME,
K5_KEY_GSS_KRB5_CCACHE_NAME,
K5_KEY_GSS_KRB5_ERROR_MESSAGE,
+ K5_KEY_KIM_ERROR_MESSAGE,
K5_KEY_MAX
} k5_key_t;
/* rename shorthand symbols for export */
diff --git a/src/include/kim/kim_ccache.h b/src/include/kim/kim_ccache.h
index d805c5c92a..5e41e9bc84 100644
--- a/src/include/kim/kim_ccache.h
+++ b/src/include/kim/kim_ccache.h
@@ -259,7 +259,7 @@ extern "C" {
/*!
* \param out_ccache_iterator on exit, a ccache iterator object for the cache collection.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get a ccache iterator to enumerate ccaches in the cache collection.
*/
kim_error kim_ccache_iterator_create (kim_ccache_iterator *out_ccache_iterator);
@@ -269,7 +269,7 @@ kim_error kim_ccache_iterator_create (kim_ccache_iterator *out_ccache_iterator);
* \param out_ccache on exit, the next ccache in the cache collection. If there are
* no more ccaches in the cache collection this argument will be
* set to NULL.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the next ccache in the cache collection.
*/
kim_error kim_ccache_iterator_next (kim_ccache_iterator in_ccache_iterator,
@@ -296,7 +296,7 @@ void kim_ccache_iterator_free (kim_ccache_iterator *io_ccache_iterator);
* \param in_options options to control credential acquisition.
* \note Depending on the kim_options specified, #kim_ccache_create_new() may
* present a GUI or command line prompt to obtain information from the user.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Acquire a new initial credential and store it in a ccache.
*/
kim_error kim_ccache_create_new (kim_ccache *out_ccache,
@@ -310,7 +310,7 @@ kim_error kim_ccache_create_new (kim_ccache *out_ccache,
* \param in_options options to control credential acquisition (if a credential is acquired).
* \note Depending on the kim_options specified, #kim_ccache_create_new_if_needed() may
* present a GUI or command line prompt to obtain information from the user.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Find a ccache containing a valid initial credential in the cache collection, or if
* unavailable, acquire and store a new initial credential.
*/
@@ -322,7 +322,7 @@ kim_error kim_ccache_create_new_if_needed (kim_ccache *out_ccache,
* \param out_ccache on exit, a ccache object for a ccache containing a TGT
* credential. Must be freed with kim_ccache_free().
* \param in_client_identity a client identity to obtain a credential for.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Find a ccache for a client identity in the cache collection.
*/
kim_error kim_ccache_create_from_client_identity (kim_ccache *out_ccache,
@@ -336,7 +336,7 @@ kim_error kim_ccache_create_from_client_identity (kim_ccache *out_ccache,
* the first client identity in the keytab.
* \param in_options options to control credential acquisition.
* \param in_keytab a path to a keytab. Specify NULL for the default keytab location.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Acquire a new initial credential from a keytab and store it in a ccache.
*/
kim_error kim_ccache_create_from_keytab (kim_ccache *out_ccache,
@@ -347,7 +347,7 @@ kim_error kim_ccache_create_from_keytab (kim_ccache *out_ccache,
/*!
* \param out_ccache on exit, a ccache object for the default ccache.
* Must be freed with kim_ccache_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the default ccache.
*/
kim_error kim_ccache_create_from_default (kim_ccache *out_ccache);
@@ -357,7 +357,7 @@ kim_error kim_ccache_create_from_default (kim_ccache *out_ccache);
* \a in_type and \a in_name. Must be freed with kim_ccache_free().
* \param in_type a ccache type string.
* \param in_name a ccache name string.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \note This API is provided for backwards compatibilty with applications which are not
* KIM-aware and should be avoided whenever possible.
* \brief Get a ccache for a ccache type and name.
@@ -371,7 +371,7 @@ kim_error kim_ccache_create_from_type_and_name (kim_ccache *out_ccache,
* Must be freed with kim_ccache_free().
* \param in_krb5_context the krb5 context used to create \a in_krb5_ccache.
* \param in_krb5_ccache a krb5 ccache object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get a ccache for a krb5 ccache.
*/
kim_error kim_ccache_create_from_krb5_ccache (kim_ccache *out_ccache,
@@ -382,7 +382,7 @@ kim_error kim_ccache_create_from_krb5_ccache (kim_ccache *out_ccache,
* \param out_ccache on exit, the new ccache object which is a copy of in_ccache.
* Must be freed with kim_ccache_free().
* \param in_ccache a ccache object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Copy a ccache.
*/
kim_error kim_ccache_copy (kim_ccache *out_ccache,
@@ -393,7 +393,7 @@ kim_error kim_ccache_copy (kim_ccache *out_ccache,
* \param in_krb5_context a krb5 context which will be used to create out_krb5_ccache.
* \param out_krb5_ccache on exit, a new krb5 ccache object which is a copy of in_ccache.
* Must be freed with krb5_cc_close() or krb5_cc_destroy().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get a krb5 ccache for a ccache.
*/
kim_error kim_ccache_get_krb5_ccache (kim_ccache in_ccache,
@@ -403,7 +403,7 @@ kim_error kim_ccache_get_krb5_ccache (kim_ccache in_ccache,
/*!
* \param in_ccache a ccache object.
* \param out_name on exit, the name string of \a in_ccache.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the name of a ccache.
*/
kim_error kim_ccache_get_name (kim_ccache in_ccache,
@@ -412,7 +412,7 @@ kim_error kim_ccache_get_name (kim_ccache in_ccache,
/*!
* \param in_ccache a ccache object.
* \param out_type on exit, the type string of \a in_ccache.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the type of a ccache.
*/
kim_error kim_ccache_get_type (kim_ccache in_ccache,
@@ -424,7 +424,7 @@ kim_error kim_ccache_get_type (kim_ccache in_ccache,
* display to the user in command line programs. (ie: "<type>:<name>")
* Must be freed with kim_string_free().
* Note: this string can also be passed to krb5_cc_resolve().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the type and name for a ccache in display format.
*/
kim_error kim_ccache_get_display_name (kim_ccache in_ccache,
@@ -434,7 +434,7 @@ kim_error kim_ccache_get_display_name (kim_ccache in_ccache,
* \param in_ccache a ccache object.
* \param out_client_identity on exit, an identity object containing the client identity of
* \a in_ccache. Must be freed with kim_identity_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the client identity for a ccache.
*/
kim_error kim_ccache_get_client_identity (kim_ccache in_ccache,
@@ -445,7 +445,7 @@ kim_error kim_ccache_get_client_identity (kim_ccache in_ccache,
* \param out_credential on exit, the first valid credential in \a in_ccache.
* Must be freed with kim_credential_free(). Set to NULL
* if you only want return value, not the actual credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the first valid credential in a ccache.
* \note This function prefers valid TGT credentials. If there are only non-valid TGTs
* in the ccache, it will always return an error. However, if there are no
@@ -460,7 +460,7 @@ kim_error kim_ccache_get_valid_credential (kim_ccache in_ccache,
* \param out_state on exit, the state of the credentials in \a in_ccache.
* See #kim_credential_state_enum for the possible values
* of \a out_state.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Check the state of the credentials in a ccache (valid, expired, postdated, etc).
* \note This function prefers TGT credentials. If there are any TGTs in the
* ccache, it will always return their state. However, if there are no
@@ -473,7 +473,7 @@ kim_error kim_ccache_get_state (kim_ccache in_ccache,
* \param in_ccache a ccache object.
* \param out_start_time on exit, the time when the credentials in \a in_ccache
* become valid. May be in the past or future.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the time when the credentials in the ccache become valid.
*/
kim_error kim_ccache_get_start_time (kim_ccache in_ccache,
@@ -483,7 +483,7 @@ kim_error kim_ccache_get_start_time (kim_ccache in_ccache,
* \param in_ccache a ccache object.
* \param out_expiration_time on exit, the time when the credentials in
* \a in_ccache will expire. May be in the past or future.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the time when the credentials in the ccache will expire.
*/
kim_error kim_ccache_get_expiration_time (kim_ccache in_ccache,
@@ -493,7 +493,7 @@ kim_error kim_ccache_get_expiration_time (kim_ccache in_ccache,
* \param in_ccache a ccache object.
* \param out_renewal_expiration_time on exit, the time when the credentials in \a in_ccache
* will no longer be renewable. May be in the past or future.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the time when the credentials in the ccache will no longer be renewable.
*/
kim_error kim_ccache_get_renewal_expiration_time (kim_ccache in_ccache,
@@ -501,7 +501,7 @@ kim_error kim_ccache_get_renewal_expiration_time (kim_ccache in_ccache,
/*!
* \param io_ccache a ccache object which will be set to the default ccache.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \note This API is provided for backwards compatibilty with applications which are not
* KIM-aware and should be avoided whenever possible.
* \brief Set a ccache to the default ccache.
@@ -518,7 +518,7 @@ kim_error kim_ccache_set_default (kim_ccache io_ccache);
* in the host's keytab will cause a failure.
* \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to
* the Zanarotti attack if the host has no keytab installed.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Verify the TGT in a ccache.
*/
kim_error kim_ccache_verify (kim_ccache in_ccache,
@@ -529,7 +529,7 @@ kim_error kim_ccache_verify (kim_ccache in_ccache,
/*!
* \param in_ccache a ccache object containing a TGT to be renewed.
* \param in_options initial credential options to be used if a new credential is obtained.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Renew the TGT in a ccache.
*/
kim_error kim_ccache_renew (kim_ccache in_ccache,
@@ -538,7 +538,7 @@ kim_error kim_ccache_renew (kim_ccache in_ccache,
/*!
* \param in_ccache a ccache object containing a TGT to be validated.
* \param in_options initial credential options.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Validate the TGT in a ccache.
*/
kim_error kim_ccache_validate (kim_ccache in_ccache,
@@ -546,7 +546,7 @@ kim_error kim_ccache_validate (kim_ccache in_ccache,
/*!
* \param io_ccache a ccache object to be destroyed. Set to NULL on exit.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Remove a ccache from the cache collection.
* \note Frees memory associated with the ccache. Do not call kim_ccache_free()
* after calling this function.
diff --git a/src/include/kim/kim_credential.h b/src/include/kim/kim_credential.h
index adb21c3167..ed58a72ae5 100644
--- a/src/include/kim/kim_credential.h
+++ b/src/include/kim/kim_credential.h
@@ -272,7 +272,7 @@ extern "C" {
* \param out_credential_iterator on exit, a credential iterator object for \a in_ccache.
* Must be freed with kim_credential_iterator_free().
* \param in_ccache a ccache object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get a credential iterator to enumerate credentials in a ccache.
*/
@@ -285,7 +285,7 @@ extern "C" {
* \a in_credential_iterator. Must be freed with
* kim_credential_free(). If there are no more credentials
* this argument will be set to NULL.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the next credential in a ccache.
*/
@@ -313,7 +313,7 @@ extern "C" {
* \param in_options options to control credential acquisition.
* \note Depending on the kim_options specified, #kim_credential_create_new() may
* present a GUI or command line prompt to obtain information from the user.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Acquire a new initial credential.
* \sa kim_ccache_create_new
*/
@@ -329,7 +329,7 @@ extern "C" {
* the first identity in the keytab.
* \param in_options options to control credential acquisition.
* \param in_keytab a path to a keytab. Specify NULL for the default keytab location.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Acquire a new initial credential from a keytab.
* \sa kim_ccache_create_from_keytab
*/
@@ -343,7 +343,7 @@ extern "C" {
* Must be freed with kim_credential_free().
* \param in_krb5_context the krb5 context used to create \a in_krb5_creds.
* \param in_krb5_creds a krb5 credential object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Copy a credential from a krb5 credential object.
*/
kim_error kim_credential_create_from_krb5_creds (kim_credential *out_credential,
@@ -354,7 +354,7 @@ extern "C" {
* \param out_credential on exit, a new credential object which is a copy of \a in_credential.
* Must be freed with kim_credential_free().
* \param in_credential a credential object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Copy a credential object.
*/
kim_error kim_credential_copy (kim_credential *out_credential,
@@ -365,7 +365,7 @@ extern "C" {
* \param in_krb5_context a krb5 context which will be used to create \a out_krb5_creds.
* \param out_krb5_creds on exit, a new krb5 creds object which is a copy of \a in_credential.
* Must be freed with krb5_free_creds().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get a krb5 credentials object for a credential object.
*/
kim_error kim_credential_get_krb5_creds (kim_credential in_credential,
@@ -376,7 +376,7 @@ extern "C" {
* \param in_credential a credential object.
* \param out_client_identity on exit, an identity object containing the client identity of
* \a in_credential. Must be freed with kim_identity_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the client identity of a credential object.
*/
kim_error kim_credential_get_client_identity (kim_credential in_credential,
@@ -386,7 +386,7 @@ extern "C" {
* \param in_credential a credential object.
* \param out_service_identity on exit, an identity object containing the service identity of
* \a in_credential. Must be freed with kim_identity_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the service identity of a credential object.
*/
kim_error kim_credential_get_service_identity (kim_credential in_credential,
@@ -395,7 +395,7 @@ extern "C" {
/*!
* \param in_credential a credential object.
* \param out_is_tgt on exit, whether or not the credential is a TGT.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Check if a credential is a ticket granting ticket.
*/
kim_error kim_credential_is_tgt (kim_credential in_credential,
@@ -405,7 +405,7 @@ extern "C" {
* \param in_credential a credential object.
* \param out_state on exit, the state of the credential. See #kim_credential_state_enum
* for the possible values of \a out_state.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Check the state of a credential (valid, expired, postdated, etc).
*/
kim_error kim_credential_get_state (kim_credential in_credential,
@@ -415,7 +415,7 @@ extern "C" {
* \param in_credential a credential object.
* \param out_start_time on exit, the time when \a in_credential becomes valid.
* May be in the past or future.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the time when the credentials become valid.
* \sa kim_ccache_get_start_time
*/
@@ -426,7 +426,7 @@ extern "C" {
* \param in_credential a credential object.
* \param out_expiration_time on exit, the time when \a in_credential will expire.
* May be in the past or future.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the time when the credentials will expire.
* \sa kim_ccache_get_expiration_time
*/
@@ -437,7 +437,7 @@ extern "C" {
* \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.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \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
*/
@@ -451,7 +451,7 @@ extern "C" {
* \param out_ccache on exit, a ccache object containing \a in_credential with the client
* identity \a in_client_identity. Must be freed with kim_ccache_free().
* Specify NULL if you don't want this return value.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Store a credential in a ccache in the cache collection.
*/
kim_error kim_credential_store (kim_credential in_credential,
@@ -468,7 +468,7 @@ extern "C" {
* in the host's keytab will cause a failure.
* \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to
* the Zanarotti attack if the host has no keytab installed.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Verify a TGT credential.
* \sa kim_ccache_verify
*/
@@ -483,7 +483,7 @@ extern "C" {
* with a new renewed credential. The new credential must be freed
* with kim_credential_free().
* \param in_options initial credential options.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Renew a TGT credential.
* \sa kim_ccache_renew
*/
@@ -496,7 +496,7 @@ extern "C" {
* with a new validated credential. The new credential must be freed
* with kim_credential_free().
* \param in_options initial credential options.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Validate a TGT credential.
* \sa kim_ccache_validate
*/
diff --git a/src/include/kim/kim_error.h b/src/include/kim/kim_error.h
index 87688e083a..de24534220 100644
--- a/src/include/kim/kim_error.h
+++ b/src/include/kim/kim_error.h
@@ -35,40 +35,36 @@ extern "C" {
/*!
* \ingroup kim_types_reference
* The kim_error_t returned when no error occurred.
- * Does not need to be freed with kim_error_free().
*/
-#define KIM_NO_ERROR ((kim_error) NULL)
-
-/*!
- * \ingroup kim_types_reference
- * The kim_error_code_t for KIM_NO_ERROR.
- */
-#define KIM_NO_ERROR_ECODE ((kim_error_code) 0)
+#define KIM_NO_ERROR ((kim_error) 0)
/*!
* \page kim_error_overview KIM Error Overview
*
- * An error object. Error objects consist of a machine readable error code for
- * for programmatic error handling and a string describing the error. All KIM APIs
- * return kim_errors with the exception of memory deallocation functions and the
- * kim_error_t APIs which return pieces of a kim_error_t object.
+ * 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.
*
- * Functions which return successfully will return #KIM_NO_ERROR (NULL). Because
- * #KIM_NO_ERROR does not need to be freed, you may use if-ladders or goto-style
- * error handling when calling the KIM APIs. In addition, kim_error_free() may
- * be called on #KIM_NO_ERROR.
+ * 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.
*
- * \note Certain kim_error_t objects are preallocated by the libraries avoid
- * exacerbating existing problems while trying to report an error. For example,
- * the out of memory error object is preallocated. It is safe to call
- * #kim_error_free() on these errors, although the function may not actually free
- * the object.
- *
- * By providing an error object rather than a numeric code, the KIM APIs can
- * tailor error strings to the circumstances of the error. So rather than returning
- * error strings like "Client not found in Kerberos database", we can report
- * "'user@REALM' not found in Kerberos database" while still providing the machine
- * readable error KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN.
+ * 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.
*/
@@ -79,40 +75,18 @@ extern "C" {
*/
/*!
- * \param out_error on exit, a new error object which is a copy of \a in_error.
- * Must be freed with kim_error_free().
- * \param in_error the error to copy.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Copy an error.
- */
-kim_error kim_error_copy (kim_error *out_error,
- kim_error in_error);
-
-/*!
- * \param in_error an error object.
- * \return On success, a machine-readable error code describing the error represented
- * by \a in_error. On failure, #KIM_PARAMETER_ECODE.
- * \brief Get a numerical error code for an error.
- */
-kim_error_code kim_error_get_code (kim_error in_error);
-
-/*!
- * \param in_error an error object.
- * \return On success, a human-readable error string describing the error represented
- * by \a in_error. On failure, NULL, indicating that the kim_error_t object was
- * invalid.
- * \brief Get a text description of an error.
- */
-kim_string kim_error_get_display_string (kim_error in_error);
-
-/*!
- * \param io_error the error object to be freed. Set to NULL on exit.
- * \return a machine-readable error code describing the error represented
- * by \a io_error. This is the same code returned by
- * #kim_error_get_code.
- * \brief Free memory associated with an 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.
+ * \return On success, KIM_NO_ERROR.
+ * \note This API returns thread local storage. It should be called
+ * immediately after a KIM API returns an error so that the correct string
+ * is returned.
+ * \brief Get a text description of an error suitable for display to the user.
*/
-kim_error_code kim_error_free (kim_error *io_error);
+kim_error kim_string_get_last_error_message (kim_string *out_string,
+ kim_error in_error);
/*!@}*/
diff --git a/src/include/kim/kim_identity.h b/src/include/kim/kim_identity.h
index 14fce8cc42..8e3facada4 100644
--- a/src/include/kim/kim_identity.h
+++ b/src/include/kim/kim_identity.h
@@ -127,7 +127,7 @@ extern "C" {
* \param out_identity on exit, a new identity object. Must be freed with kim_identity_free().
* \param in_string a string representation of a Kerberos identity.
* Special characters such as '/' and '@' must be escaped with '\'.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Create a identity from a string.
*/
kim_error kim_identity_create_from_string (kim_identity *out_identity,
@@ -142,7 +142,7 @@ kim_error kim_identity_create_from_string (kim_identity *out_identity,
* order (ie: the 4th argument to kim_identity_create_from_components() will be
* the 2nd component of the identity).
* \note The last argument must be a NULL or kim_identity_create_from_components() may crash.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Create a identity from a realm and component strings.
*/
kim_error kim_identity_create_from_components (kim_identity *out_identity,
@@ -155,7 +155,7 @@ kim_error kim_identity_create_from_components (kim_identity *out_identity,
* Must be freed with kim_identity_free().
* \param in_krb5_context the krb5 context used to create \a in_krb5_principal.
* \param in_krb5_principal a krb5 principal object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Create an identity object from a krb5_principal.
*/
kim_error kim_identity_create_from_krb5_principal (kim_identity *out_identity,
@@ -166,7 +166,7 @@ kim_error kim_identity_create_from_krb5_principal (kim_identity *out_identity,
* \param out_identity on exit, a new identity object which is a copy of \a in_identity.
* Must be freed with kim_identity_free().
* \param in_identity an identity object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Copy an identity object.
*/
kim_error kim_identity_copy (kim_identity *out_identity,
@@ -180,7 +180,7 @@ kim_error kim_identity_copy (kim_identity *out_identity,
* \a in_compare_to_identity which determines whether
* or not the two identities are equivalent and their
* sort order (for display to the user) if they are not.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Compare identity objects for equivalency.
*/
kim_error kim_identity_compare (kim_identity in_identity,
@@ -190,7 +190,7 @@ kim_error kim_identity_compare (kim_identity in_identity,
* \param in_identity an identity object.
* \param out_string on exit, a string representation of \a in_identity.
* Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the string representation of a identity.
* \note Special characters such as '@' and '/' will be escaped with '\'.
*/
@@ -202,7 +202,7 @@ kim_error kim_identity_get_string (kim_identity in_identity,
* \param in_identity an identity object.
* \param out_display_string on exit, a string representation of \a in_identity appropriate for
* display to the user. Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get a human-readable string representation of an identity.
* \note Special characters such as '/' and '@' are \em not escaped with '\'. As a result the
* string returned from this function cannot be used with kim_identity_create_from_string()
@@ -216,7 +216,7 @@ kim_error kim_identity_get_display_string (kim_identity in_identity,
* \param in_identity an identity object.
* \param out_realm_string on exit, a string representation of \a in_identity's realm.
* Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the realm string of an identity.
*/
kim_error kim_identity_get_realm (kim_identity in_identity,
@@ -225,7 +225,7 @@ kim_error kim_identity_get_realm (kim_identity in_identity,
/*!
* \param in_identity an identity object.
* \param out_number_of_components on exit the number of components in \a in_identity.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the number of components of an identity.
*/
kim_error kim_identity_get_number_of_components (kim_identity in_identity,
@@ -236,7 +236,7 @@ kim_error kim_identity_get_number_of_components (kim_identity in_identity,
* \param in_index the index of the desired component. Component indexes start at 0.
* \param out_component_string on exit, a string representation of the component in \a in_identity
* specified by \a in_index. Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the Nth component of an identity.
*/
kim_error kim_identity_get_component_at_index (kim_identity in_identity,
@@ -249,7 +249,7 @@ kim_error kim_identity_get_component_at_index (kim_identity in_identity,
* \param out_krb5_principal on exit, a krb5_principal representation of \a in_identity
* allocated with \a in_krb5_context. Must be freed with
* krb5_free_principal() using \a in_krb5_context.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the krb5_principal representation of an identity.
*/
kim_error kim_identity_get_krb5_principal (kim_identity in_identity,
@@ -260,7 +260,7 @@ kim_error kim_identity_get_krb5_principal (kim_identity in_identity,
* \param in_identity an identity object.
* \param out_gss_name on exit, a gss_name_t representation of \a in_identity.
* Must be freed with gss_release_name().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the gss_name_t representation of an identity.
*/
kim_error kim_identity_get_gss_name (kim_identity in_identity,
@@ -269,7 +269,7 @@ kim_error kim_identity_get_gss_name (kim_identity in_identity,
/*!
* \param in_identity an identity object whose password will be changed.
* \param in_options initial credential options to be used if a new credential is obtained.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Change the password for an identity.
* \note kim_identity_change_password() will acquire a temporary credential to change
* the password. It uses the \a in_options structure to obtain information about the desired
@@ -282,7 +282,7 @@ kim_error kim_identity_change_password (kim_identity in_identity,
* \param in_identity an identity object whose password will be changed.
* \param in_options initial credential options to be used if a new credential is obtained.
* \param in_new_password a string representation of the identity's new password.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Change the password for an identity to a caller-provided new password.
* \note kim_identity_change_password_with_passwords() will acquire a temporary credential
* to change the password. It uses the \a in_options structure to obtain information about
diff --git a/src/include/kim/kim_options.h b/src/include/kim/kim_options.h
index bf30b75b66..fd6efdf478 100644
--- a/src/include/kim/kim_options.h
+++ b/src/include/kim/kim_options.h
@@ -62,45 +62,45 @@ enum kim_prompt_type_enum {
* The prompt callback used to display a prompt to the user.
* See \ref kim_options_custom_prompt_callback for more information.
*/
-typedef kim_error_code (*kim_prompt_callback) (kim_options *io_options,
- kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- void **out_reply);
+typedef kim_error (*kim_prompt_callback) (kim_options *io_options,
+ kim_prompt_type in_type,
+ kim_string in_title,
+ kim_string in_message,
+ kim_string in_description,
+ void **out_reply);
/*!
* The default prompt callback.
* See \ref kim_options_custom_prompt_callback for more information.
*/
-kim_error_code kim_prompt_callback_default (kim_options *io_options,
- kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- void **out_reply);
-
+kim_error kim_prompt_callback_default (kim_options *io_options,
+ kim_prompt_type in_type,
+ kim_string in_title,
+ kim_string in_message,
+ kim_string in_description,
+ void **out_reply);
+
/*!
* The graphical prompt callback.
* See \ref kim_options_custom_prompt_callback for more information.
*/
-kim_error_code kim_prompt_callback_gui (kim_options *io_options,
- kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- void **out_reply);
+kim_error kim_prompt_callback_gui (kim_options *io_options,
+ kim_prompt_type in_type,
+ kim_string in_title,
+ kim_string in_message,
+ kim_string in_description,
+ void **out_reply);
/*!
* The command line prompt callback.
* See \ref kim_options_custom_prompt_callback for more information.
*/
-kim_error_code kim_prompt_callback_cli (kim_options *io_options,
- kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- void **out_reply);
+kim_error kim_prompt_callback_cli (kim_options *io_options,
+ kim_prompt_type in_type,
+ kim_string in_title,
+ kim_string in_message,
+ kim_string in_description,
+ void **out_reply);
/*!
* The prompt callback which always returns an error.
@@ -108,12 +108,12 @@ kim_error_code kim_prompt_callback_cli (kim_options *io_options,
* \note Using this callback may prevent the user from authenicating.
* See \ref kim_options_custom_prompt_callback for more information.
*/
-kim_error_code kim_prompt_callback_none (kim_options *io_options,
- kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- void **out_reply);
+kim_error kim_prompt_callback_none (kim_options *io_options,
+ kim_prompt_type in_type,
+ kim_string in_title,
+ kim_string in_message,
+ kim_string in_description,
+ void **out_reply);
/*! @} */
@@ -292,7 +292,7 @@ kim_error_code kim_prompt_callback_none (kim_options *io_options,
/*!
* \param out_options on exit, a new options object. Must be freed with kim_options_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Create new options with default values.
*/
kim_error kim_options_create (kim_options *out_options);
@@ -301,7 +301,7 @@ kim_error kim_options_create (kim_options *out_options);
* \param out_options on exit, a new options object which is a copy of \a in_options.
* Must be freed with kim_options_free().
* \param in_options a options object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Copy options.
*/
kim_error kim_options_copy (kim_options *out_options,
@@ -310,7 +310,7 @@ kim_error kim_options_copy (kim_options *out_options,
/*!
* \param io_options an options object to modify.
* \param in_prompt_callback a prompt callback function.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the prompt callback for obtaining information from the user.
* \par Default value
* #kim_prompt_callback_default
@@ -324,7 +324,7 @@ kim_error kim_options_set_prompt_callback (kim_options io_options,
* \param out_prompt_callback on exit, the prompt callback specified by in_options.
* Does not need to be freed but may become invalid when
* \a in_options is freed.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the prompt callback for obtaining information from the user.
* \par Default value
* #kim_prompt_callback_default
@@ -336,7 +336,7 @@ kim_error kim_options_get_prompt_callback (kim_options in_options,
/*!
* \param io_options an options object to modify.
* \param in_data a pointer to caller-specific data.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set caller-specific data for use in library callbacks.
* \note This option can be used by the caller to store a pointer to data needed when handling a
* callback. The KIM library does not use this options data in any way.
@@ -351,7 +351,7 @@ kim_error kim_options_set_data (kim_options io_options,
* \param in_options an options object.
* \param out_data on exit, the pointer to caller specific data specified by in_options.
* Does not need to be freed but may become invalid when \a in_options is freed.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get caller-specific data for use in library callbacks.
* \note This option can be used by the caller to store a pointer to data needed when handling a
* callback. The KIM library does not use this options data in any way.
@@ -366,7 +366,7 @@ kim_error kim_options_get_data (kim_options in_options,
* \param io_options an options object to modify.
* \param in_prompt_type a type of prompt.
* \param in_response a response to prompts of \a in_prompt_type.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set a response for a prompt for use when acquiring credentials.
* \note Each response only overrides the first prompt of a given prompt type. If multiple
* prompts of the same type are required, or if a prompt of a different type is requested,
@@ -386,7 +386,7 @@ kim_error kim_options_set_prompt_response (kim_options io_options,
* \param out_response on exit, the response to prompts of type \a in_prompt_type specified
* by \a in_options. Does not need to be freed but may become invalid
* when \a in_options is freed.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the response for a prompt for use when acquiring credentials.
* \note Each response only overrides the first prompt of a given prompt type. If multiple
* prompts of the same type are required, or if a prompt of a different type is requested,
@@ -405,7 +405,7 @@ kim_error kim_options_get_prompt_response (kim_options in_options,
* \param in_start_time a start date (in seconds since January 1, 1970). Set to
* #KIM_OPTIONS_START_IMMEDIATELY for the acquired credential to be valid
* immediately.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the date when a credential should become valid.
* \note When using a start time in the future, once the start time has been reached the credential
* must be validated before it can be used.
@@ -421,7 +421,7 @@ kim_error kim_options_set_start_time (kim_options io_options,
* \param out_start_time on exit, the start date (in seconds since January 1, 1970) specified by
* \a in_options. #KIM_OPTIONS_START_IMMEDIATELY indicates the credential
* will be valid immediately.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the date when a credential should become valid.
* \note When using a start time in the future, once the start time has been reached the credential
* must be validated before it can be used.
@@ -435,7 +435,7 @@ kim_error kim_options_get_start_time (kim_options in_options,
/*!
* \param io_options an options object to modify.
* \param in_lifetime a lifetime duration (in seconds).
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the duration during which a credential should be valid.
* \note KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours).
* As a result the credential will actually have a lifetime which is the minimum of
@@ -450,7 +450,7 @@ kim_error kim_options_set_lifetime (kim_options io_options,
/*!
* \param in_options an options object.
* \param out_lifetime on exit, the lifetime duration (in seconds) specified in \a in_options.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the duration during which an acquired credential should be valid.
* \note KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours).
* As a result the credential will actually have a lifetime which is the minimum of
@@ -466,7 +466,7 @@ kim_error kim_options_get_lifetime (kim_options in_options,
* \param io_options an options object to modify.
* \param in_renewable a boolean value indicating whether or not to request a renewable
* credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set whether or not to request a renewable credential.
* \par Default value
* Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
@@ -479,7 +479,7 @@ kim_error kim_options_set_renewable (kim_options io_options,
* \param in_options an options object.
* \param out_renewable on exit, a boolean value indicating whether or \a in_options will
* request a renewable credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get whether or not to request a renewable credential.
* \par Default value
* Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
@@ -491,7 +491,7 @@ kim_error kim_options_get_renewable (kim_options in_options,
/*!
* \param io_options an options object to modify.
* \param in_renewal_lifetime a renewal lifetime duration (in seconds).
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the duration during which a valid credential should be renewable.
* \note KDCs have a maximum allowed renewal lifetime per identity (usually 10 to 21 hours).
* As a result the credential will actually have a lifetime which is the minimum of
@@ -507,7 +507,7 @@ kim_error kim_options_set_renewal_lifetime (kim_options io_options,
* \param in_options an options object.
* \param out_renewal_lifetime on exit, the renewal lifetime duration (in seconds) specified
* in \a in_options.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the duration during which a valid credential should be renewable.
* \note KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours).
* As a result the credential will actually have a lifetime which is the minimum of
@@ -523,7 +523,7 @@ kim_error kim_options_get_renewal_lifetime (kim_options in_options,
* \param io_options an options object to modify.
* \param in_forwardable a boolean value indicating whether or not to request a forwardable
* credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set whether or not to request a forwardable credential.
* \par Default value
* Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
@@ -536,7 +536,7 @@ kim_error kim_options_set_forwardable (kim_options io_options,
* \param in_options an options object.
* \param out_forwardable on exit, a boolean value indicating whether or \a in_options will
* request a forwardable credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get whether or not to request a forwardable credential.
* \par Default value
* Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
@@ -549,7 +549,7 @@ kim_error kim_options_get_forwardable (kim_options in_options,
* \param io_options an options object to modify.
* \param in_proxiable a boolean value indicating whether or not to request a proxiable
* credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set whether or not to request a proxiable credential.
* \par Default value
* Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
@@ -562,7 +562,7 @@ kim_error kim_options_set_proxiable (kim_options io_options,
* \param in_options an options object.
* \param out_proxiable on exit, a boolean value indicating whether or \a in_options will
* request a proxiable credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get whether or not to request a proxiable credential.
* \par Default value
* Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
@@ -575,7 +575,7 @@ kim_error kim_options_get_proxiable (kim_options in_options,
* \param io_options an options object to modify.
* \param in_addressless a boolean value indicating whether or not to request an addressless
* credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set whether or not to request an addressless credential.
* \par Default value
* Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
@@ -588,7 +588,7 @@ kim_error kim_options_set_addressless (kim_options io_options,
* \param in_options an options object.
* \param out_addressless on exit, a boolean value indicating whether or \a in_options will
* request an addressless credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get whether or not to request an addressless credential.
* \par Default value
* Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
@@ -600,7 +600,7 @@ kim_error kim_options_get_addressless (kim_options in_options,
/*!
* \param io_options an options object to modify.
* \param in_service_name a service name.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the service name to request a credential for.
* \par Default value
* NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
@@ -613,7 +613,7 @@ kim_error kim_options_set_service_name (kim_options io_options,
* \param in_options an options object.
* \param out_service_name on exit, the service name specified in \a in_options.
* Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the service name to request a credential for.
* \par Default value
* NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
diff --git a/src/include/kim/kim_preferences.h b/src/include/kim/kim_preferences.h
index 052ac455d2..15e2e3eb0a 100644
--- a/src/include/kim/kim_preferences.h
+++ b/src/include/kim/kim_preferences.h
@@ -97,7 +97,7 @@ extern "C" {
/*!
* \param out_favorite_identities on exit, a new favorite identities object.
* Must be freed with kim_favorite_identities_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Create a new favorite identities list.
*/
kim_error kim_favorite_identities_create (kim_favorite_identities *out_favorite_identities);
@@ -107,7 +107,7 @@ kim_error kim_favorite_identities_create (kim_favorite_identities *out_favorite_
* a copy of in_favorite_identities.
* Must be freed with kim_favorite_identities_free().
* \param in_favorite_identities a favorite identities object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Copy a favorite identities list.
*/
kim_error kim_favorite_identities_copy (kim_favorite_identities *out_favorite_identities,
@@ -116,7 +116,7 @@ kim_error kim_favorite_identities_copy (kim_favorite_identities *out_favorite_id
/*!
* \param in_favorite_identities a favorite identities object.
* \param out_number_of_identities on exit, the number of identities in \a in_favorite_identities.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the number of identities in a favorite identities list.
*/
kim_error kim_favorite_identities_get_number_of_identities (kim_favorite_identities in_favorite_identities,
@@ -127,7 +127,7 @@ kim_error kim_favorite_identities_get_number_of_identities (kim_favorite_identit
* \param in_index a index into the identities list (starting at 0).
* \param out_realm on exit, the identity at \a in_index in \a in_favorite_identities.
* Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the Nth identity in a favorite identities list.
*/
kim_error kim_favorite_identities_get_identity_at_index (kim_favorite_identities in_favorite_identities,
@@ -136,7 +136,7 @@ kim_error kim_favorite_identities_get_identity_at_index (kim_favorite_identities
/*!
* \param io_favorite_identities a favorite identities object.
* \param in_identity an identity string to add to \a in_favorite_identities.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Add an identity to a favorite identities list.
*/
kim_error kim_favorite_identities_add_identity (kim_favorite_identities io_favorite_identities,
@@ -145,7 +145,7 @@ kim_error kim_favorite_identities_add_identity (kim_favorite_identities io_favor
/*!
* \param io_favorite_identities a favorite identities object.
* \param in_identity an identity to remove from \a in_favorite_identities.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Remove an identity from a identities list.
*/
kim_error kim_favorite_identities_remove_identity (kim_favorite_identities io_favorite_identities,
@@ -153,7 +153,7 @@ kim_error kim_favorite_identities_remove_identity (kim_favorite_identities io_fa
/*!
* \param io_favorite_identities a favorite identities object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Empty a favorite identities list.
*/
kim_error kim_favorite_identities_remove_all_identities (kim_favorite_identities io_favorite_identities);
@@ -247,7 +247,7 @@ void kim_favorite_identities_free (kim_favorite_identities *io_favorite_identiti
/*!
* \param out_preferences on exit, a new preferences object.
* Must be freed with kim_preferences_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Create a new preferences object from the current user's preferences.
*/
kim_error kim_preferences_create (kim_preferences *out_preferences);
@@ -256,7 +256,7 @@ kim_error kim_preferences_create (kim_preferences *out_preferences);
* \param out_preferences on exit, a new preferences object which is a copy of in_preferences.
* Must be freed with kim_preferences_free().
* \param in_preferences a preferences object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Copy a preferences object.
*/
kim_error kim_preferences_copy (kim_preferences *out_preferences,
@@ -265,7 +265,7 @@ kim_error kim_preferences_copy (kim_preferences *out_preferences,
/*!
* \param io_preferences a preferences object to modify.
* \param in_options an options object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the user's preferred options.
* \sa kim_preferences_get_options()
*/
@@ -276,7 +276,7 @@ kim_error kim_preferences_set_options (kim_preferences io_preferences,
* \param in_preferences a preferences object.
* \param out_options on exit, the options specified in \a in_preferences.
* Must be freed with kim_options_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the user's preferred options.
* \sa kim_preferences_set_options()
*/
@@ -287,7 +287,7 @@ kim_error kim_preferences_get_options (kim_preferences in_preferences,
* \param io_preferences a preferences object to modify.
* \param in_remember_options a boolean value indicating whether or not to remember the last
* options used to acquire a credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set whether or not to remember the last options the user used to acquire a credential.
* \sa kim_preferences_get_remember_options()
*/
@@ -298,7 +298,7 @@ kim_error kim_preferences_set_remember_options (kim_preferences io_preferences,
* \param in_preferences a preferences object.
* \param out_remember_options on exit, a boolean value indicating whether or \a in_preferences will
* remember the last options used to acquire a credential.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get whether or not to remember the last options the user used to acquire a credential.
* \sa kim_preferences_set_remember_options()
*/
@@ -308,7 +308,7 @@ kim_error kim_preferences_get_remember_options (kim_preferences in_preferences,
/*!
* \param io_preferences a preferences object to modify.
* \param in_client_identity a client identity object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the user's preferred client identity.
* \sa kim_preferences_get_client_identity()
*/
@@ -319,7 +319,7 @@ kim_error kim_preferences_set_client_identity (kim_preferences io_preferences,
* \param in_preferences a preferences object.
* \param out_client_identity on exit, the client identity specified in \a in_preferences.
* Must be freed with kim_identity_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the user's preferred client identity.
* \sa kim_preferences_set_client_identity()
*/
@@ -330,7 +330,7 @@ kim_error kim_preferences_get_client_identity (kim_preferences in_preferences,
* \param io_preferences a preferences object to modify.
* \param in_remember_client_identity a boolean value indicating whether or not to remember the last
* client identity for which a credential was acquired.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set whether or not to remember the last client identity the user acquired a credential for.
* \sa kim_preferences_get_remember_client_identity()
*/
@@ -341,7 +341,7 @@ kim_error kim_preferences_set_remember_client_identity (kim_preferences io_prefe
* \param in_preferences a preferences object.
* \param out_remember_client_identity on exit, a boolean value indicating whether or \a in_preferences will
* remember the last client identity for which a credential was acquired.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get whether or not to remember the last client identity the user acquired a credential for.
* \sa kim_preferences_set_remember_client_identity()
*/
@@ -352,7 +352,7 @@ kim_error kim_preferences_get_remember_client_identity (kim_preferences in_pref
* \param io_preferences a preferences object to modify.
* \param in_minimum_lifetime a minimum lifetime indicating how small a lifetime the
* GUI tools should allow the user to specify for credentials.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the minimum credential lifetime for GUI credential lifetime controls.
* \sa kim_preferences_get_minimum_lifetime()
*/
@@ -363,7 +363,7 @@ kim_error kim_preferences_set_minimum_lifetime (kim_preferences io_preferences,
* \param in_preferences a preferences object.
* \param out_minimum_lifetime on exit, the minimum lifetime that GUI tools will
* allow the user to specify for credentials.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the minimum credential lifetime for GUI credential lifetime controls.
* \sa kim_preferences_set_minimum_lifetime()
*/
@@ -374,7 +374,7 @@ kim_error kim_preferences_get_minimum_lifetime (kim_preferences in_preferences,
* \param io_preferences a preferences object to modify.
* \param in_maximum_lifetime a maximum lifetime indicating how large a lifetime the
* GUI tools should allow the user to specify for credentials.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the maximum credential lifetime for GUI credential lifetime controls.
* \sa kim_preferences_get_maximum_lifetime()
*/
@@ -385,7 +385,7 @@ kim_error kim_preferences_set_maximum_lifetime (kim_preferences io_preferences,
* \param in_preferences a preferences object.
* \param out_maximum_lifetime on exit, the maximum lifetime that GUI tools will
* allow the user to specify for credentials.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the maximum credential lifetime for GUI credential lifetime controls.
* \sa kim_preferences_set_maximum_lifetime()
*/
@@ -397,7 +397,7 @@ kim_error kim_preferences_get_maximum_lifetime (kim_preferences in_preferences,
* \param in_minimum_renewal_lifetime a minimum lifetime indicating how small a lifetime the
* GUI tools should allow the user to specify for
* credential renewal.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the minimum credential renewal lifetime for GUI credential lifetime controls.
* \sa kim_preferences_get_minimum_renewal_lifetime()
*/
@@ -408,7 +408,7 @@ kim_error kim_preferences_set_minimum_renewal_lifetime (kim_preferences io_prefe
* \param in_preferences a preferences object.
* \param out_minimum_renewal_lifetime on exit, the minimum lifetime that GUI tools will
* allow the user to specify for credential renewal.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the minimum credential renewal lifetime for GUI credential lifetime controls.
* \sa kim_preferences_set_minimum_renewal_lifetime()
*/
@@ -420,7 +420,7 @@ kim_error kim_preferences_get_minimum_renewal_lifetime (kim_preferences in_pref
* \param in_maximum_renewal_lifetime a maximum lifetime indicating how large a lifetime the
* GUI tools should allow the user to specify for
* credential renewal.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the maximum credential renewal lifetime for GUI credential lifetime controls.
* \sa kim_preferences_get_minimum_renewal_lifetime()
*/
@@ -431,7 +431,7 @@ kim_error kim_preferences_set_maximum_renewal_lifetime (kim_preferences io_prefe
* \param in_preferences a preferences object.
* \param out_maximum_renewal_lifetime on exit, the maximum lifetime that GUI tools will
* allow the user to specify for credential renewal.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the maximum credential renewal lifetime for GUI credential lifetime controls.
* \sa kim_preferences_set_minimum_renewal_lifetime()
*/
@@ -443,7 +443,7 @@ kim_error kim_preferences_get_maximum_renewal_lifetime (kim_preferences in_pref
* \param in_favorite_identities a favorite identities object.
* See \ref kim_favorite_identities_overview for more information on KIM
* Favorite Identities.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the user's preferred list of identities.
* \sa kim_preferences_get_favorite_identities()
*/
@@ -455,7 +455,7 @@ kim_error kim_preferences_set_favorite_identities (kim_preferences io_pr
* \param out_favorite_identities on exit, a copy of the favorite identities specified in \a in_preferences.
* See \ref kim_favorite_identities_overview for more information on KIM
* Favorite Identities. Must be freed with kim_favorite_identities_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the user's preferred list of identities.
* \sa kim_preferences_set_favorite_identities()
*/
@@ -464,7 +464,7 @@ kim_error kim_preferences_get_favorite_identities (kim_preferences in_p
/*!
* \param in_preferences a preferences object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Synchronize a preferences object with the user's preferences, writing pending changes
* and reading any changes applied by other processes.
*/
diff --git a/src/include/kim/kim_selection_hints.h b/src/include/kim/kim_selection_hints.h
index 9acfc5ac3c..a8d63415b2 100644
--- a/src/include/kim/kim_selection_hints.h
+++ b/src/include/kim/kim_selection_hints.h
@@ -219,12 +219,19 @@ extern "C" {
* @{
*/
+#define kim_hint_key_client_realm "kim_hint_key_client_realm"
+#define kim_hint_key_user "kim_hint_key_user"
+#define kim_hint_key_service_realm "kim_hint_key_service_realm"
+#define kim_hint_key_service "kim_hint_key_service"
+#define kim_hint_key_server "kim_hint_key_server"
+#define kim_hint_key_service_identity "kim_hint_key_service_identity"
+
/*!
* \param out_selection_hints on exit, a new selection hints object.
* Must be freed with kim_selection_hints_free().
* \param in_application_identifier an application identifier string. Java-style identifiers are recommended
* to avoid cache entry collisions (eg: "com.example.MyApplication")
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Create a new selection hints object.
*/
kim_error kim_selection_hints_create (kim_selection_hints *out_selection_hints,
@@ -234,138 +241,39 @@ kim_error kim_selection_hints_create (kim_selection_hints *out_selection_hints,
* \param out_selection_hints on exit, a new selection hints object which is a copy of in_selection_hints.
* Must be freed with kim_selection_hints_free().
* \param in_selection_hints a selection hints object.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Copy a selection hints object.
*/
kim_error kim_selection_hints_copy (kim_selection_hints *out_selection_hints,
kim_selection_hints in_selection_hints);
/*!
- * \param io_selection_hints a selection hints object to modify.
- * \param in_service_identity a service identity.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Set the preferred service identity.
- * \sa kim_selection_hints_get_service_identity_hint()
+ * \param io_selection_hints a selection hints object to modify.
+ * \param in_hint_key A string representing the type of hint to set.
+ * \param in_hint_string A string representation of a hint for
+ * \a in_hint_key to set in \a in_selection_hints.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Set the string value of a hint used for identity selection.
+ * \sa kim_selection_hints_get_hint()
*/
-kim_error kim_selection_hints_set_service_identity_hint (kim_selection_hints io_selection_hints,
- kim_identity in_service_identity);
+kim_error kim_selection_hints_set_hint (kim_selection_hints io_selection_hints,
+ kim_string in_hint_key,
+ kim_string in_hint_string);
/*!
* \param in_selection_hints a selection hints object.
- * \param out_service_identity on exit, the service identity specified in \a in_selection_hints.
- * Must be freed with kim_identity_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Get the preferred service identity.
- * \sa kim_selection_hints_set_service_identity_hint()
- */
-kim_error kim_selection_hints_get_service_identity_hint (kim_selection_hints in_selection_hints,
- kim_identity *out_service_identity);
-
-/*!
- * \param io_selection_hints a selection hints object to modify.
- * \param in_client_realm a client realm string.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Set the preferred client realm.
- * \sa kim_selection_hints_get_client_realm_hint()
- */
-kim_error kim_selection_hints_set_client_realm_hint (kim_selection_hints io_selection_hints,
- kim_string in_client_realm);
-
-/*!
- * \param in_selection_hints a selection hints object.
- * \param out_client_realm on exit, the client realm string specified in \a in_selection_hints.
- * Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Get the preferred client realm.
- * \sa kim_selection_hints_set_client_realm_hint()
- */
-kim_error kim_selection_hints_get_client_realm_hint (kim_selection_hints in_selection_hints,
- kim_string *out_client_realm);
-
-/*!
- * \param io_selection_hints a selection hints object to modify.
- * \param in_user a user name string.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Set the preferred user name.
- * \sa kim_selection_hints_get_user_hint()
- */
-kim_error kim_selection_hints_set_user_hint (kim_selection_hints io_selection_hints,
- kim_string in_user);
-
-/*!
- * \param in_selection_hints a selection hints object.
- * \param out_user on exit, the user name string specified in \a in_selection_hints.
- * Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Get the preferred user name.
- * \sa kim_selection_hints_set_user_hint()
- */
-kim_error kim_selection_hints_get_user_hint (kim_selection_hints in_selection_hints,
- kim_string *out_user);
-
-
-/*!
- * \param io_selection_hints a selection hints object to modify.
- * \param in_service_realm a service realm string.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Set the preferred service realm.
- * \sa kim_selection_hints_get_service_realm_hint()
- */
-kim_error kim_selection_hints_set_service_realm_hint (kim_selection_hints io_selection_hints,
- kim_string in_service_realm);
-
-/*!
- * \param io_selection_hints a selection hints object.
- * \param out_service_realm on exit, the service realm string specified in \a in_selection_hints.
- * Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Get the preferred service realm.
- * \sa kim_selection_hints_set_service_realm_hint()
- */
-kim_error kim_selection_hints_get_service_realm_hint (kim_selection_hints io_selection_hints,
- kim_string *out_service_realm);
-
-/*!
- * \param io_selection_hints a selection hints object to modify.
- * \param in_service a service name string.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Set the preferred service name.
- * \sa kim_selection_hints_get_service_hint()
- */
-kim_error kim_selection_hints_set_service_hint (kim_selection_hints io_selection_hints,
- kim_string in_service);
-
-/*!
- * \param in_selection_hints a selection hints object.
- * \param out_service on exit, the service name string specified in \a in_selection_hints.
- * Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Get the preferred service name.
- * \sa kim_selection_hints_set_service_hint()
- */
-kim_error kim_selection_hints_get_service_hint (kim_selection_hints in_selection_hints,
- kim_string *out_service);
-
-/*!
- * \param io_selection_hints a selection hints object to modify.
- * \param in_server a server host name string.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Set the preferred server host name.
- * \sa kim_selection_hints_get_server_hint()
- */
-kim_error kim_selection_hints_set_server_hint (kim_selection_hints io_selection_hints,
- kim_string in_server);
-
-/*!
- * \param in_selection_hints a selection hints object.
- * \param out_server on exit, the server host name string specified in \a in_selection_hints.
- * Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
- * \brief Get the preferred server host name.
- * \sa kim_selection_hints_set_server_hint()
+ * \param in_hint_key A string representing the type of hint to
+ * obtain.
+ * \param out_hint_string A string representation of the hint
+ * \a in_hint_key in \a in_selection_hints.
+ * Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Get the string value of a hint used for identity selection.
+ * \sa kim_selection_hints_set_hint()
*/
-kim_error kim_selection_hints_get_server_hint (kim_selection_hints in_selection_hints,
- kim_string *out_server);
+kim_error kim_selection_hints_get_hint (kim_selection_hints in_selection_hints,
+ kim_string in_hint_key,
+ kim_string *out_hint_string);
/*!
* \param io_selection_hints a selection hints object to modify.
@@ -373,7 +281,7 @@ kim_error kim_selection_hints_get_server_hint (kim_selection_hints in_selection
* \note 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.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the application name for use in user interaction.
* \sa kim_selection_hints_get_application_name()
*/
@@ -384,7 +292,7 @@ kim_error kim_selection_hints_set_application_name (kim_selection_hints io_selec
* \param in_selection_hints a selection hints object.
* \param out_application_name on exit, the localized full name of the application specified
* in \a in_selection_hints. Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the application name for use in user interaction.
* \sa kim_selection_hints_set_application_name()
*/
@@ -397,7 +305,7 @@ kim_error kim_selection_hints_get_application_name (kim_selection_hints in_sele
* \note 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
* #kim_selection_hints_set_application_name()
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the strings used to prompt the user to select the identity.
* \sa kim_selection_hints_get_explanation()
*/
@@ -409,7 +317,7 @@ kim_error kim_selection_hints_set_explanation (kim_selection_hints io_selection_
* \param out_explanation on exit, the localized string specified in \a in_selection_hints
* which describes why the caller needs the identity. May be NULL.
* If non-NULL, must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the strings used to prompt the user to select the identity.
* \sa kim_selection_hints_set_explanation()
*/
@@ -420,7 +328,7 @@ kim_error kim_selection_hints_get_explanation (kim_selection_hints in_selection
/*!
* \param io_selection_hints a selection hints object to modify.
* \param in_options options to control credential acquisition.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the options which will be used if credentials need to be acquired.
* \sa kim_selection_hints_get_options()
*/
@@ -432,7 +340,7 @@ kim_error kim_selection_hints_set_options (kim_selection_hints io_selection_hint
* \param out_options on exit, the options to control credential acquisition
* specified in \a in_selection_hints. May be KIM_OPTIONS_DEFAULT.
* If not, must be freed with kim_options_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the options which will be used if credentials need to be acquired.
* \sa kim_selection_hints_set_options()
*/
@@ -443,7 +351,7 @@ kim_error kim_selection_hints_get_options (kim_selection_hints in_selection_hin
* \param in_selection_hints a selection hints object to modify
* \param in_allow_user_interaction a boolean value specifying whether or not KIM should ask
* the user to select an identity for \a in_selection_hints.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \note This setting defaults to TRUE.
* \brief Set whether or not KIM may interact with the user to select an identity.
* \sa kim_selection_hints_get_allow_user_interaction
@@ -456,7 +364,7 @@ kim_error kim_selection_hints_set_allow_user_interaction (kim_selection_hints in
* \param out_allow_user_interaction on exit, a boolean value specifying whether or not KIM
* should ask the user to select an identity for
* \a in_selection_hints.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \note This setting defaults to TRUE.
* \brief Get whether or not KIM may interact with the user to select an identity.
* \sa kim_selection_hints_set_allow_user_interaction
@@ -468,7 +376,7 @@ kim_error kim_selection_hints_get_allow_user_interaction (kim_selection_hints i
* \param in_selection_hints a selection hints object to modify
* \param in_remember_identity a boolean value specifying whether or not KIM should use a cached
* mapping between \a in_selection_hints and a Kerberos identity.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \note This setting defaults to TRUE.
* \brief Set whether or not KIM will use cached mappings for this selection hints object.
* \sa kim_selection_hints_get_remember_identity
@@ -480,7 +388,7 @@ kim_error kim_selection_hints_set_remember_identity (kim_selection_hints in_sele
* \param in_selection_hints a selection hints object to modify
* \param out_remember_identity on exit, a boolean value specifying whether or not KIM will use a
* cached mapping between \a in_selection_hints and a Kerberos identity.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \note This setting defaults to TRUE.
* \brief Get whether or not KIM will use cache mappings for this selection hints object.
* \sa kim_selection_hints_set_remember_identity
@@ -492,7 +400,7 @@ kim_error kim_selection_hints_get_remember_identity (kim_selection_hints in_sel
* \param in_selection_hints the selection hints to add to the cache.
* \param out_identity the Kerberos identity \a in_selection_hints maps to.
* Must be freed with kim_identity_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \note \a out_identity is the identity mapped to by the current state of \a in_selection_hints.
* This function may prompt the user via a GUI to choose that identity.
* Subsequent modifications to \a in_selection_hints will not change \a out_identity.
@@ -505,7 +413,7 @@ kim_error kim_selection_hints_get_identity (kim_selection_hints in_selection_hin
/*!
* \param in_selection_hints the selection hints to add to the cache.
* \param in_identity the Kerberos identity \a in_selection_hints maps to.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Add an entry for the selection hints to the selection hints cache,
* replacing any existing entry.
*/
@@ -515,7 +423,7 @@ kim_error kim_selection_hints_remember_identity (kim_selection_hints in_selectio
/*!
* \param in_selection_hints the selection hints to remove from the cache.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Remove an entry for the selection hints from the selection hints cache.
*/
diff --git a/src/include/kim/kim_string.h b/src/include/kim/kim_string.h
index 77b3abe61f..79cd0ee247 100644
--- a/src/include/kim/kim_string.h
+++ b/src/include/kim/kim_string.h
@@ -48,26 +48,40 @@ extern "C" {
*/
/*!
+ * \param out_string on exit, a human-readable UTF-8 string describing the
+ * error represented by \a in_error. Must be freed with
+ * kim_string_free().
+ * \param in_error an error code.
+ * \return On success, #KIM_NO_ERROR. On failure,
+ * \note If the caller needs an error string, this API should be called
+ * immediately after a KIM API returns an error.
+ * \brief Get a text description of an error.
+ */
+kim_error kim_string_create_for_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.
Must be freed with kim_string_free().
* \param in_string the string to copy.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Copy a string.
*/
kim_error kim_string_copy (kim_string *out_string,
- const kim_string in_string);
+ const kim_string in_string);
/*!
* \param in_string a string.
* \param in_compare_to_string a string to be compared to \a in_string.
* \param out_comparison on exit, a comparison result indicating whether \a in_string
* is greater than, less than or equal to \a in_compare_to_string.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Compare two strings.
*/
kim_error kim_string_compare (kim_string in_string,
- kim_string in_compare_to_string,
- kim_comparison *out_comparison);
+ kim_string in_compare_to_string,
+ kim_comparison *out_comparison);
/*!
* \param io_string a string to be freed. Set to NULL on exit.
diff --git a/src/include/kim/kim_types.h b/src/include/kim/kim_types.h
index b342ad7788..9c611d226c 100644
--- a/src/include/kim/kim_types.h
+++ b/src/include/kim/kim_types.h
@@ -37,9 +37,9 @@ extern "C" {
*/
/*!
- * The KIM String type. See \ref kim_string_overview for more information.
+ * The KIM Error type. See \ref kim_error_overview for more information.
*/
-typedef int32_t kim_error_code;
+typedef int32_t kim_error;
/*!
* A time value represented in seconds since January 1, 1970.
@@ -89,15 +89,20 @@ typedef int 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;
+//struct kim_error_opaque;
/*!
* A KIM Error object. See \ref kim_error_overview for more information.
*/
-typedef struct kim_error_opaque *kim_error;
+//typedef struct kim_error_opaque *kim_error;
struct kim_identity_opaque;
/*!
generated by cgit (git 2.34.1) at 2026-01-06 01:51:40 +0000