From d308f082c1e5a8009853956a96f80c5f9414de9e Mon Sep 17 00:00:00 2001 From: Alexandra Ellwood Date: Tue, 19 Aug 2008 16:43:17 +0000 Subject: [PATCH] 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 --- src/include/k5-thread.h | 1 + src/include/kim/kim_ccache.h | 50 ++-- src/include/kim/kim_credential.h | 36 +-- src/include/kim/kim_error.h | 94 +++----- src/include/kim/kim_identity.h | 28 +-- src/include/kim/kim_options.h | 110 ++++----- src/include/kim/kim_preferences.h | 56 ++--- src/include/kim/kim_selection_hints.h | 178 ++++---------- src/include/kim/kim_string.h | 24 +- src/include/kim/kim_types.h | 13 +- src/kim/agent/mac/Identities.m | 21 +- src/kim/lib/kim.exports | 5 +- src/kim/lib/kim_ccache.c | 24 +- src/kim/lib/kim_credential.c | 34 +-- src/kim/lib/kim_debug.c | 76 ++++++ src/kim/lib/kim_debug_private.h | 38 +++ src/kim/lib/kim_error.c | 281 ++++++++++------------- src/kim/lib/kim_error_code.et | 5 +- src/kim/lib/kim_error_private.h | 38 ++- src/kim/lib/kim_library.c | 39 +--- src/kim/lib/kim_library_private.h | 5 - src/kim/lib/kim_options.c | 63 +++-- src/kim/lib/kim_preferences.c | 11 +- src/kim/lib/kim_private.h | 3 +- src/kim/lib/kim_selection_hints.c | 264 ++++++--------------- src/kim/lib/mac/kim_os_debug.c | 37 +++ src/kim/lib/mac/kim_os_library.c | 7 - src/kim/lib/mac/kim_os_preferences.c | 6 +- src/kim/lib/mac/kim_os_selection_hints.c | 8 +- src/kim/test/test_kim_common.c | 3 +- src/kim/test/test_kim_identity.c | 12 - src/kim/test/test_kim_preferences.c | 5 - 32 files changed, 683 insertions(+), 892 deletions(-) create mode 100644 src/kim/lib/kim_debug.c create mode 100644 src/kim/lib/kim_debug_private.h create mode 100644 src/kim/lib/mac/kim_os_debug.c diff --git a/src/include/k5-thread.h b/src/include/k5-thread.h index 4122c8151..dbc1a6fd7 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 d805c5c92..5e41e9bc8 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: ":") * 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 adb21c316..ed58a72ae 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 87688e083..de2453422 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 14fce8cc4..8e3facada 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 bf30b75b6..fd6efdf47 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@", 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@", the ticket granting ticket (TGT) service. diff --git a/src/include/kim/kim_preferences.h b/src/include/kim/kim_preferences.h index 052ac455d..15e2e3eb0 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 9acfc5ac3..a8d63415b 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 77b3abe61..79cd0ee24 100644 --- a/src/include/kim/kim_string.h +++ b/src/include/kim/kim_string.h @@ -47,27 +47,41 @@ 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 b342ad778..9c611d226 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. @@ -88,16 +88,21 @@ 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; /*! diff --git a/src/kim/agent/mac/Identities.m b/src/kim/agent/mac/Identities.m index e59af9534..651a49fe3 100644 --- a/src/kim/agent/mac/Identities.m +++ b/src/kim/agent/mac/Identities.m @@ -105,26 +105,22 @@ } if (!err) { - kim_error kimErr = KIM_NO_ERROR; kim_favorite_identities favoriteIdentities = NULL; kim_count count = 0; - kimErr = kim_favorite_identities_create (&favorite_identities); - err = kim_error_free (&kimErr); + err = kim_favorite_identities_create (&favorite_identities); if (!err) { - kimErr = kim_favorite_identities_get_number_of_identities (favoriteIdentities, - &count); - err = kim_error_free (&kimErr); + err = kim_favorite_identities_get_number_of_identities (favoriteIdentities, + &count); } for (i = 0; !err && i < count; i++) { kim_identity kimIdentity = NULL; Identity *identity = NULL: - kimErr = kim_favorite_identities_get_identity_at_index (favoriteIdentities, - i, &kimIdentity); - err = kim_error_free (&kimErr); + err = kim_favorite_identities_get_identity_at_index (favoriteIdentities, + i, &kimIdentity); if (!err) { Identity *identity = [[[Identity alloc] initWithIdentity: kimIdentity] autorelease]; @@ -234,9 +230,8 @@ } } - if (kim_error_get_code (err) == KIM_NO_CREDENTIALS_ECODE) { + if (err == KIM_NO_CREDENTIALS_ECODE) { /* ccache is empty, just ignore it */ - kim_error_free (&err); err = KIM_NO_ERROR; } @@ -247,10 +242,10 @@ kim_ccache_iterator_free (&iterator); if (err) { - NSLog (@"Got error %s", kim_error_get_display_string (err)); + NSLog (@"Got error %s", kim_error_message (err)); } - return kim_error_free (&err); + return err; } diff --git a/src/kim/lib/kim.exports b/src/kim/lib/kim.exports index 4a90fd499..17c24f39e 100644 --- a/src/kim/lib/kim.exports +++ b/src/kim/lib/kim.exports @@ -1,7 +1,4 @@ -kim_error_copy -kim_error_get_code -kim_error_get_display_string -kim_error_free +kim_string_get_last_error_message kim_string_copy kim_string_compare diff --git a/src/kim/lib/kim_ccache.c b/src/kim/lib/kim_ccache.c index 0bfcfb08e..31a2af597 100644 --- a/src/kim/lib/kim_ccache.c +++ b/src/kim/lib/kim_ccache.c @@ -248,7 +248,7 @@ kim_error kim_ccache_create_new_if_needed (kim_ccache *out_ccache, err = kim_ccache_create_from_client_identity (out_ccache, in_client_identity); if (err) { - kim_error_free (&err); /* toss error since we don't care */ + /* ccache does not already exist, create a new one */ err = kim_ccache_create_new (out_ccache, in_client_identity, in_options); } } @@ -284,8 +284,8 @@ kim_error kim_ccache_create_from_client_identity (kim_ccache *out_ccache, err = kim_identity_get_display_string (in_client_identity, &string); if (!err) { - err = kim_error_create_from_code (KIM_NO_SUCH_PRINCIPAL_ECODE, - string); + err = kim_error_set_message_for_code (KIM_NO_SUCH_PRINCIPAL_ECODE, + string); } kim_string_free (&string); @@ -721,8 +721,8 @@ static kim_error kim_ccache_get_dominant_credential (kim_ccache in_cc } if (!err) { - err = kim_error_create_from_code (KIM_NO_CREDENTIALS_ECODE, - identity_string); + err = kim_error_set_message_for_code (KIM_NO_CREDENTIALS_ECODE, + identity_string); } kim_string_free (&identity_string); @@ -781,21 +781,21 @@ kim_error kim_ccache_get_valid_credential (kim_ccache in_ccache, if (!err) { if (state == kim_credentials_state_expired) { - err = kim_error_create_from_code (KIM_CREDENTIALS_EXPIRED_ECODE, + err = kim_error_set_message_for_code (KIM_CREDENTIALS_EXPIRED_ECODE, identity_string); } else if (state == kim_credentials_state_not_yet_valid || state == kim_credentials_state_needs_validation) { - err = kim_error_create_from_code (KIM_NEEDS_VALIDATION_ECODE, - identity_string); + err = kim_error_set_message_for_code (KIM_NEEDS_VALIDATION_ECODE, + identity_string); } else if (state == kim_credentials_state_address_mismatch) { - err = kim_error_create_from_code (KIM_BAD_IP_ADDRESS_ECODE, - identity_string); + err = kim_error_set_message_for_code (KIM_BAD_IP_ADDRESS_ECODE, + identity_string); } else { /* just default to this */ - err = kim_error_create_from_code (KIM_NEEDS_VALIDATION_ECODE, - identity_string); + err = kim_error_set_message_for_code (KIM_NEEDS_VALIDATION_ECODE, + identity_string); } } diff --git a/src/kim/lib/kim_credential.c b/src/kim/lib/kim_credential.c index 40302e7b0..0fb0e7e5a 100644 --- a/src/kim/lib/kim_credential.c +++ b/src/kim/lib/kim_credential.c @@ -662,9 +662,8 @@ kim_error kim_credential_store (kim_credential in_credential, if (!err) { err = kim_ccache_get_krb5_ccache (ccache, context, &k5ccache); - } else if (kim_error_get_code (err) == KIM_NO_SUCH_PRINCIPAL_ECODE) { - /* Nothing to replace, toss error and create a new ccache */ - kim_error_free (&err); + } else if (err == KIM_NO_SUCH_PRINCIPAL_ECODE) { + /* Nothing to replace, create a new ccache */ err = krb5_error (context, krb5_cc_new_unique (context, "API", NULL, &k5ccache)); @@ -749,46 +748,47 @@ kim_error kim_credential_verify (kim_credential in_credential, &options)); if (err && !service_principal && in_fail_if_no_service_key) { - /* If the service principal wasn't specified but we are supposed to fail without a key - we should walk the keytab trying to find one that succeeds. */ - krb5_error_code code = 0; + /* If the service principal wasn't specified but we are supposed to + * fail without a key we should walk the keytab trying to find one + * that succeeds. */ + krb5_error_code terr = 0; kim_boolean verified = 0; krb5_kt_cursor cursor = NULL; krb5_keytab_entry entry; if (!keytab) { - code = krb5_kt_default (scontext, &keytab); + terr = krb5_kt_default (scontext, &keytab); } - if (!err) { - code = krb5_kt_start_seq_get (scontext, keytab, &cursor); + if (!terr) { + terr = krb5_kt_start_seq_get (scontext, keytab, &cursor); } - while (!code && !verified) { + while (!terr && !verified) { kim_boolean free_entry = 0; - code = krb5_kt_next_entry (scontext, keytab, &entry, &cursor); - free_entry = !code; /* remember to free */ + terr = krb5_kt_next_entry (scontext, keytab, &entry, &cursor); + free_entry = !terr; /* remember to free */ - if (!code) { - code = krb5_verify_init_creds (scontext, in_credential->creds, + if (!terr) { + terr = krb5_verify_init_creds (scontext, in_credential->creds, entry.principal /* get principal for the 1st entry */, keytab, NULL /* don't store creds in ccache */, &options); } - if (!code) { + if (!terr) { verified = 1; } if (free_entry) { krb5_free_keytab_entry_contents (scontext, &entry); } } - if (!code && verified) { + if (!terr && verified) { /* We found a key that verified! */ - kim_error_free (&err); + err = KIM_NO_ERROR; } if (cursor) { krb5_kt_end_seq_get (scontext, keytab, &cursor); } diff --git a/src/kim/lib/kim_debug.c b/src/kim/lib/kim_debug.c new file mode 100644 index 000000000..ee10c3f4d --- /dev/null +++ b/src/kim/lib/kim_debug.c @@ -0,0 +1,76 @@ +/* + * $Header$ + * + * Copyright 2008 Massachusetts Institute of Technology. + * All Rights Reserved. + * + * Export of this software from the United States of America may + * require a specific license from the United States Government. + * It is the responsibility of any person or organization contemplating + * export to obtain such a license before exporting. + * + * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + * distribute this software and its documentation for any purpose and + * without fee is hereby granted, provided that the above copyright + * notice appear in all copies and that both that copyright notice and + * this permission notice appear in supporting documentation, and that + * the name of M.I.T. not be used in advertising or publicity pertaining + * to distribution of the software without specific, written prior + * permission. Furthermore if you modify this software you must label + * your software as modified software and not distribute it in such a + * fashion that it might be confused with the original M.I.T. software. + * M.I.T. makes no representations about the suitability of + * this software for any purpose. It is provided "as is" without express + * or implied warranty. + */ + +#include "kim_private.h" + +/* ------------------------------------------------------------------------ */ + +kim_error _check_error (kim_error in_err, + kim_string in_function, + kim_string in_file, + int in_line) +{ + if (in_err) { + kim_debug_printf ("%s(): got %d ('%s') at %s: %d", + in_function, in_err, kim_error_message (in_err), + in_file, in_line); + } + + return in_err; +} + +/* ------------------------------------------------------------------------ */ + +void __kim_debug_printf (kim_string in_function, + kim_string in_format, + ...) +{ + kim_error err = KIM_NO_ERROR; + kim_string format = NULL; + kim_string string = NULL; + + if (!err && !in_function) { err = param_error (1, "in_function", "NULL"); } + if (!err && !in_format ) { err = param_error (2, "in_format", "NULL"); } + + if (!err) { + err = kim_string_create_from_format (&format, "%s(): %s", + in_function, in_format); + } + + if (!err) { + va_list args; + va_start (args, in_format); + err = kim_string_create_from_format_va (&string, format, args); + va_end (args); + } + + if (!err) { + kim_os_debug_print (string); + } + + kim_string_free (&format); + kim_string_free (&string); +} diff --git a/src/kim/lib/kim_debug_private.h b/src/kim/lib/kim_debug_private.h new file mode 100644 index 000000000..f9b67f0d9 --- /dev/null +++ b/src/kim/lib/kim_debug_private.h @@ -0,0 +1,38 @@ +/* + * $Header$ + * + * Copyright 2008 Massachusetts Institute of Technology. + * All Rights Reserved. + * + * Export of this software from the United States of America may + * require a specific license from the United States Government. + * It is the responsibility of any person or organization contemplating + * export to obtain such a license before exporting. + * + * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + * distribute this software and its documentation for any purpose and + * without fee is hereby granted, provided that the above copyright + * notice appear in all copies and that both that copyright notice and + * this permission notice appear in supporting documentation, and that + * the name of M.I.T. not be used in advertising or publicity pertaining + * to distribution of the software without specific, written prior + * permission. Furthermore if you modify this software you must label + * your software as modified software and not distribute it in such a + * fashion that it might be confused with the original M.I.T. software. + * M.I.T. makes no representations about the suitability of + * this software for any purpose. It is provided "as is" without express + * or implied warranty. + */ + +#define kim_debug_printf(format, ...) __kim_debug_printf(__FUNCTION__, format, ## __VA_ARGS__) +void __kim_debug_printf (kim_string in_function, + kim_string in_format, + ...); + +kim_error _check_error (kim_error in_err, + kim_string in_function, + kim_string in_file, + int in_line); +#define check_error(err) _check_error(err, __FUNCTION__, __FILE__, __LINE__) + +void kim_os_debug_print (kim_string in_string); diff --git a/src/kim/lib/kim_error.c b/src/kim/lib/kim_error.c index 265c02f79..24d78963a 100644 --- a/src/kim/lib/kim_error.c +++ b/src/kim/lib/kim_error.c @@ -24,61 +24,93 @@ * or implied warranty. */ +#include "k5-int.h" #include "kim_private.h" #include #include -struct kim_error_opaque { - kim_error_code code; - kim_string message; -}; +static k5_mutex_t kim_error_lock = K5_MUTEX_PARTIAL_INITIALIZER; -struct kim_error_opaque kim_no_memory_error_struct = { KIM_OUT_OF_MEMORY_ECODE, NULL, }; -kim_error kim_no_memory_error = &kim_no_memory_error_struct; +MAKE_INIT_FUNCTION(kim_error_initialize); +MAKE_FINI_FUNCTION(kim_error_terminate); -struct kim_error_opaque kim_error_initializer = { KIM_NO_ERROR_ECODE, NULL }; +/* ------------------------------------------------------------------------ */ + +typedef struct kim_last_error { + kim_error code; + char message[1024]; +} *kim_last_error; /* ------------------------------------------------------------------------ */ -static inline kim_error kim_error_allocate (kim_error *out_error, - kim_error_code in_code) +static kim_error kim_error_set_message (kim_error in_error, + kim_string in_message) { + int lock_err = 0; kim_error err = KIM_NO_ERROR; - kim_error error = NULL; + kim_last_error last_error = NULL; - /* short circuit out of memory errors so we don't loop */ - switch (in_code) { - case 0: - return KIM_NO_ERROR; - - case KIM_OUT_OF_MEMORY_ECODE: - case ENOMEM: - case KRB5_CC_NOMEM: - case ccErrNoMem: - // case klMemFullErr: - // case memFullErr: - return kim_no_memory_error; - } + err = lock_err = k5_mutex_lock (&kim_error_lock); if (!err) { - error = malloc (sizeof (*error)); - if (!error) { - err = kim_no_memory_error; - } else { - *error = kim_error_initializer; + last_error = k5_getspecific (K5_KEY_KIM_ERROR_MESSAGE); + + if (!last_error) { + last_error = malloc (sizeof (*last_error)); + if (!last_error) { + err = KIM_OUT_OF_MEMORY_ECODE; + } else { + last_error->code = KIM_NO_ERROR; + err = k5_setspecific (K5_KEY_KIM_ERROR_MESSAGE, last_error); + } } } if (!err) { - error->code = in_code; - - *out_error = error; - error = NULL; + strncpy (last_error->message, in_message, sizeof (last_error->message)); + last_error->message[sizeof (last_error->message)-1] = '\0'; + last_error->code = in_error; } - kim_error_free (&error); + if (!lock_err) { k5_mutex_unlock (&kim_error_lock); } - return check_error (err); + return err; +} + +/* ------------------------------------------------------------------------ */ + +static void kim_error_free_message (void *io_error) +{ + kim_last_error error = io_error; + + if (error) { + if (error->message) { + free (error->message); + } + free (error); + } +} + +/* ------------------------------------------------------------------------ */ + +kim_string kim_error_message (kim_error in_error) +{ + int lock_err = 0; + kim_last_error last_error = NULL; + kim_string message = NULL; + + lock_err = k5_mutex_lock (&kim_error_lock); + + if (!lock_err) { + last_error = k5_getspecific (K5_KEY_KIM_ERROR_MESSAGE); + if (last_error && last_error->code == in_error) { + message = last_error->message; + } + } + + if (!lock_err) { k5_mutex_unlock (&kim_error_lock); } + + return message ? message : error_message (in_error); } /* ------------------------------------------------------------------------ */ @@ -86,7 +118,7 @@ static inline kim_error kim_error_allocate (kim_error *out_error, static kim_boolean kim_error_is_builtin (kim_error in_error) { return (in_error == KIM_NO_ERROR || - in_error == kim_no_memory_error); + in_error == KIM_OUT_OF_MEMORY_ECODE); } #pragma mark -- Helper Functions -- @@ -95,30 +127,30 @@ static kim_boolean kim_error_is_builtin (kim_error in_error) /* ------------------------------------------------------------------------ */ -kim_error _kim_error_create_for_param (kim_string in_function, - unsigned int in_argument_position, - kim_string in_argument_name, - kim_string in_invalid_value) +kim_error _kim_error_set_message_for_param (kim_string in_function, + unsigned int in_argument_position, + kim_string in_argument_name, + kim_string in_invalid_value) { - return kim_error_create_from_code (KIM_PARAMETER_ECODE, - in_function, - in_argument_position, - in_argument_name, - in_invalid_value); + return kim_error_set_message_for_code (KIM_PARAMETER_ECODE, + in_function, + in_argument_position, + in_argument_name, + in_invalid_value); } #pragma mark -- Generic Functions -- /* ------------------------------------------------------------------------ */ -kim_error kim_error_create_from_code (kim_error_code in_code, - ...) +kim_error kim_error_set_message_for_code (kim_error in_error, + ...) { kim_error err = KIM_NO_ERROR; va_list args; - va_start (args, in_code); - err = kim_error_create_from_code_va (in_code, args); + va_start (args, in_error); + err = kim_error_set_message_for_code_va (in_error, args); va_end (args); return check_error (err); @@ -126,159 +158,84 @@ kim_error kim_error_create_from_code (kim_error_code in_code, /* ------------------------------------------------------------------------ */ -kim_error kim_error_create_from_code_va (kim_error_code in_code, - va_list in_args) +kim_error kim_error_set_message_for_code_va (kim_error in_error, + va_list in_args) { kim_error err = KIM_NO_ERROR; - kim_error error = KIM_NO_ERROR; - if (!err) { - err = kim_error_allocate (&error, in_code); - } - - if (!err && !kim_error_is_builtin (error)) { - err = kim_string_create_from_format_va_retcode (&error->message, - error_message (in_code), + if (!err && !kim_error_is_builtin (in_error)) { + kim_string message = NULL; + + err = kim_string_create_from_format_va_retcode (&message, + error_message (in_error), in_args); + + if (!err) { + err = kim_error_set_message (in_error, message); + } + + kim_string_free (&message); } - if (!err) { - err = error; - error = NULL; /* take ownership */ - } - - kim_error_free (&error); - - return err; + return err ? err : in_error; } /* ------------------------------------------------------------------------ */ -kim_error kim_error_create_from_krb5_error (krb5_context in_context, - krb5_error_code in_code) +kim_error kim_error_set_message_for_krb5_error (krb5_context in_context, + krb5_error_code in_code) { kim_error err = KIM_NO_ERROR; - kim_error error = KIM_NO_ERROR; - - if (!err) { - err = kim_error_allocate (&error, in_code); - } - if (!err && !kim_error_is_builtin (error)) { + if (!err && !kim_error_is_builtin (in_code)) { const char *message = krb5_get_error_message (in_context, in_code); - err = kim_string_copy (&error->message, message); - - if (message) { krb5_free_error_message (in_context, message); } - } - - if (!err) { - err = error; - error = NULL; /* take ownership */ + err = kim_error_set_message (in_code, message); } - kim_error_free (&error); - - return err; + return err ? err : in_code; } - + +#pragma mark -- Debugging Functions -- + /* ------------------------------------------------------------------------ */ -kim_error kim_error_copy (kim_error *out_error, - kim_error in_error) +int kim_error_initialize (void) { - kim_error err = KIM_NO_ERROR; - kim_error error = KIM_NO_ERROR; - - if (!err && !out_error) { err = param_error (1, "out_error", "NULL"); } - if (!err && !in_error ) { err = param_error (2, "in_error", "NULL"); } + int err = 0; - if (!err) { - if (kim_error_is_builtin (in_error)) { - error = in_error; - - } else { - err = kim_error_allocate (&error, in_error->code); - - if (!err && in_error->message) { - err = kim_string_copy (&error->message, in_error->message); - } - } + if (!err) { + err = k5_mutex_finish_init (&kim_error_lock); } if (!err) { - *out_error = error; - error = KIM_NO_ERROR; + err = k5_key_register (K5_KEY_KIM_ERROR_MESSAGE, + kim_error_free_message); } - kim_error_free (&error); - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error_code kim_error_get_code (kim_error in_error) -{ - if (!in_error) { /* KIM_NO_ERROR */ - return KIM_NO_ERROR_ECODE; - } else { - return in_error->code; - } -} - -/* ------------------------------------------------------------------------ */ - -kim_string kim_error_get_display_string (kim_error in_error) -{ - if (!in_error) { /* KIM_NO_ERROR */ - return error_message (KIM_NO_ERROR_ECODE); - - } else if (in_error->message) { - return in_error->message; - - } else { - /* Note: kim_no_memory_error will get here because its string is NULL */ - return error_message (in_error->code); - } + return err; } /* ------------------------------------------------------------------------ */ -kim_error_code kim_error_free (kim_error *io_error) +void kim_error_terminate (void) { - kim_error_code code = 0; - - if (io_error && *io_error) { - code = (*io_error)->code; - - if (kim_error_is_builtin (*io_error)) { - kim_string_free (&(*io_error)->message); - free (*io_error); - *io_error = KIM_NO_ERROR; - } + if (!INITIALIZER_RAN (kim_error_initialize) || PROGRAM_EXITING ()) { + return; } - return code; + k5_key_delete (K5_KEY_KIM_ERROR_MESSAGE); + k5_mutex_destroy (&kim_error_lock); } -#pragma mark -- Debugging Functions -- +#pragma mark -- Public API -- + /* ------------------------------------------------------------------------ */ -kim_error _check_error (kim_error in_err, - kim_string in_function, - kim_string in_file, - int in_line) +kim_error kim_string_get_last_error_message (kim_string *out_string, + kim_error in_error) { - if (in_err) { - kim_error_code code = kim_error_get_code (in_err); - kim_string message = kim_error_get_display_string (in_err); - - kim_debug_printf ("%s(): got %d ('%s') at %s: %d", - in_function, code, message, in_file, in_line); - } - - return in_err; + return kim_string_copy (out_string, kim_error_message (in_error)); } diff --git a/src/kim/lib/kim_error_code.et b/src/kim/lib/kim_error_code.et index f46ad21be..673d05708 100644 --- a/src/kim/lib/kim_error_code.et +++ b/src/kim/lib/kim_error_code.et @@ -28,6 +28,7 @@ error_code KIM_PARAMETER_ECODE, "%s(): argument %d (%s) may error_code KIM_KRB5_INIT_FAILED_ECODE, "Unable to initialize Kerberos v5" error_code KIM_NO_REALMS_ECODE, "There are no Kerberos realms configured" error_code KIM_NO_SUCH_REALM_ECODE, "The realm '%s' is not in your configuration file or does not exist" +error_code KIM_UNSUPPORTED_HINT_ECODE, "The hint '%s' is not supported by this version of KIM" index 25 # Principal Errors @@ -61,9 +62,9 @@ error_code KIM_BAD_IDENTITY_INDEX_ECODE, "No identity at index %d in index 125 # Cache Collection Errors error_code KIM_NO_SUCH_PRINCIPAL_ECODE, "Principal '%s' does not exist in the cache collection" -error_code KIM_CANT_BECOME_DEFAULT_ECODE, "The credentials cache '%s' cannot become the system default cache." +error_code KIM_CANT_BECOME_DEFAULT_ECODE, "The credentials cache '%s' cannot become the system default cache" error_code KIM_CREDENTIALS_EXPIRED_ECODE, "The Kerberos credentials for '%s' have expired" -error_code KIM_NO_CREDENTIALS_ECODE, "You do not have Kerberos credentials for principal '%s'" +error_code KIM_NO_CREDENTIALS_ECODE, "No Kerberos credentials for '%s' available" error_code KIM_BAD_IP_ADDRESS_ECODE, "The IP addresses in the Kerberos credentials for '%s' do not match any of your computer's IP addresses" error_code KIM_NO_SUCH_CCACHE_ECODE, "The credentials cache '%s' does not exist" error_code KIM_BAD_HOST_CONFIGURATION_ECODE, "Unable to get local hostname or address information" diff --git a/src/kim/lib/kim_error_private.h b/src/kim/lib/kim_error_private.h index 536b2d0de..6a3bcff91 100644 --- a/src/kim/lib/kim_error_private.h +++ b/src/kim/lib/kim_error_private.h @@ -29,29 +29,25 @@ #include -kim_error _kim_error_create_for_param (kim_string in_function, - unsigned int in_argument_position, - kim_string in_argument_name, - kim_string in_invalid_value); -#define param_error(pos, name, value) _kim_error_create_for_param(__FUNCTION__,\ - pos, name, \ - value) +kim_error _kim_error_set_message_for_param (kim_string in_function, + unsigned int in_argument_position, + kim_string in_argument_name, + kim_string in_invalid_value); +#define param_error(pos, name, value) _kim_error_set_message_for_param(__FUNCTION__,\ + pos, name, \ + value) -kim_error kim_error_create_from_code (kim_error_code in_code, - ...); -kim_error kim_error_create_from_code_va (kim_error_code in_code, - va_list args); -kim_error kim_error_create_from_krb5_error (krb5_context in_context, - krb5_error_code in_code); +kim_error kim_error_set_message_for_code (kim_error in_code, + ...); +kim_error kim_error_set_message_for_code_va (kim_error in_code, + va_list in_args); +kim_error kim_error_set_message_for_krb5_error (krb5_context in_context, + krb5_error_code in_code); -#define krb5_error(context,code) kim_error_create_from_krb5_error(context, code) -#define ccapi_error(code) kim_error_create_from_code(code) -#define os_error(code) kim_error_create_from_code(code) +#define krb5_error(context,code) kim_error_set_message_for_krb5_error(context, code) +#define ccapi_error(code) kim_error_set_message_for_code(code) +#define os_error(code) kim_error_set_message_for_code(code) -kim_error _check_error (kim_error in_err, - kim_string in_function, - kim_string in_file, - int in_line); -#define check_error(err) _check_error(err, __FUNCTION__, __FILE__, __LINE__) +kim_string kim_error_message (kim_error in_error); #endif /* KIM_ERROR_PRIVATE_H */ diff --git a/src/kim/lib/kim_library.c b/src/kim/lib/kim_library.c index 858ab7d03..928d8aa05 100644 --- a/src/kim/lib/kim_library.c +++ b/src/kim/lib/kim_library.c @@ -1,7 +1,7 @@ /* * $Header$ * - * Copyright 2006 Massachusetts Institute of Technology. + * Copyright 2006-2008 Massachusetts Institute of Technology. * All Rights Reserved. * * Export of this software from the United States of America may @@ -34,39 +34,6 @@ #include "kim_private.h" #include "kim_os_private.h" -/* ------------------------------------------------------------------------ */ - -void __kim_library_debug_printf (kim_string in_function, - kim_string in_format, - ...) -{ - kim_error err = KIM_NO_ERROR; - kim_string format = NULL; - kim_string string = NULL; - - if (!err && !in_function) { err = param_error (1, "in_function", "NULL"); } - if (!err && !in_format ) { err = param_error (2, "in_format", "NULL"); } - - if (!err) { - err = kim_string_create_from_format (&format, "%s(): %s", in_function, in_format); - } - - if (!err) { - va_list args; - va_start (args, in_format); - err = kim_string_create_from_format_va (&string, format, args); - va_end (args); - } - - if (!err) { - kim_os_library_debug_print (string); - } - - kim_string_free (&format); - kim_string_free (&string); - kim_error_free (&err); -} - #pragma mark -- Allow Home Directory Access -- static pthread_mutex_t g_allow_home_directory_access_mutex = PTHREAD_MUTEX_INITIALIZER; @@ -118,8 +85,6 @@ kim_boolean kim_library_allow_home_directory_access (void) kim_boolean allow_access = FALSE; kim_error err = kim_library_get_allow_home_directory_access (&allow_access); - kim_error_free (&err); - return allow_access; } @@ -208,7 +173,5 @@ kim_boolean kim_library_allow_automatic_prompting (void) if (files ) { krb5_free_config_files (files); } } - kim_error_free (&err); - return allow_automatic_prompting; } diff --git a/src/kim/lib/kim_library_private.h b/src/kim/lib/kim_library_private.h index af8d489a2..2f51ab767 100644 --- a/src/kim/lib/kim_library_private.h +++ b/src/kim/lib/kim_library_private.h @@ -30,11 +30,6 @@ #include -#define kim_debug_printf(format, ...) __kim_library_debug_printf(__FUNCTION__, format, ## __VA_ARGS__) -void __kim_library_debug_printf (kim_string in_function, - kim_string in_format, - ...); - kim_error kim_library_set_allow_home_directory_access (kim_boolean in_allow_access); kim_error kim_library_get_allow_home_directory_access (kim_boolean *out_allow_access); diff --git a/src/kim/lib/kim_options.c b/src/kim/lib/kim_options.c index 3eb09e44b..4b3d1147f 100644 --- a/src/kim/lib/kim_options.c +++ b/src/kim/lib/kim_options.c @@ -615,15 +615,14 @@ void kim_options_free (kim_options *io_options) /* ------------------------------------------------------------------------ */ -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) { kim_error err = KIM_NO_ERROR; - kim_error_code code = KIM_NO_ERROR_ECODE; if (!err && !io_options) { err = param_error (1, "io_options", "NULL"); } if (!err && !out_reply ) { err = param_error (6, "out_reply", "NULL"); } @@ -631,22 +630,19 @@ kim_error_code kim_prompt_callback_default (kim_options *io_options, if (!err) { } - code = kim_error_get_code (check_error (err)); - kim_error_free (&err); - return code; + return check_error (err); } /* ------------------------------------------------------------------------ */ -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) { kim_error err = KIM_NO_ERROR; - kim_error_code code = KIM_NO_ERROR_ECODE; if (!err && !io_options) { err = param_error (1, "io_options", "NULL"); } if (!err && !out_reply ) { err = param_error (6, "out_reply", "NULL"); } @@ -654,22 +650,19 @@ kim_error_code kim_prompt_callback_gui (kim_options *io_options, if (!err) { } - code = kim_error_get_code (check_error (err)); - kim_error_free (&err); - return code; + return check_error (err); } /* ------------------------------------------------------------------------ */ -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) { kim_error err = KIM_NO_ERROR; - kim_error_code code = KIM_NO_ERROR_ECODE; if (!err && !io_options) { err = param_error (1, "io_options", "NULL"); } if (!err && !out_reply ) { err = param_error (6, "out_reply", "NULL"); } @@ -677,19 +670,17 @@ kim_error_code kim_prompt_callback_cli (kim_options *io_options, if (!err) { } - code = kim_error_get_code (check_error (err)); - kim_error_free (&err); - return code; + return check_error (err); } /* ------------------------------------------------------------------------ */ -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) { return KIM_USER_CANCELED_ECODE; } diff --git a/src/kim/lib/kim_preferences.c b/src/kim/lib/kim_preferences.c index c017fa866..c2805fda0 100644 --- a/src/kim/lib/kim_preferences.c +++ b/src/kim/lib/kim_preferences.c @@ -192,7 +192,8 @@ kim_error kim_favorite_identities_get_identity_at_index (kim_favorite_identities if (!err) { if (in_index >= in_favorite_identities->count) { - err = kim_error_create_from_code (KIM_BAD_IDENTITY_INDEX_ECODE, in_index); + err = kim_error_set_message_for_code (KIM_BAD_IDENTITY_INDEX_ECODE, + in_index); } } @@ -238,8 +239,8 @@ kim_error kim_favorite_identities_add_identity (kim_favorite_identities io_favor err = kim_identity_get_display_string (in_identity, &display_string); if (!err) { - err = kim_error_create_from_code (KIM_IDENTITY_ALREADY_IN_IDENTITIES_LIST, - display_string); + err = kim_error_set_message_for_code (KIM_IDENTITY_ALREADY_IN_IDENTITIES_LIST, + display_string); } kim_string_free (&display_string); @@ -296,7 +297,6 @@ kim_error kim_favorite_identities_remove_identity (kim_favorite_identities io_fa kim_error terr = kim_favorite_identities_resize (io_favorite_identities, new_count); if (terr) { kim_debug_printf ("failed to resize list to %d. Continuing.", new_count); - kim_error_free (&terr); } kim_identity_free (&identity); @@ -310,7 +310,8 @@ kim_error kim_favorite_identities_remove_identity (kim_favorite_identities io_fa err = kim_identity_get_display_string (in_identity, &display_string); if (!err) { - err = kim_error_create_from_code (KIM_IDENTITY_NOT_IN_IDENTITIES_LIST, display_string); + err = kim_error_set_message_for_code (KIM_IDENTITY_NOT_IN_IDENTITIES_LIST, + display_string); } kim_string_free (&display_string); diff --git a/src/kim/lib/kim_private.h b/src/kim/lib/kim_private.h index cf9ed81c2..16452a33d 100644 --- a/src/kim/lib/kim_private.h +++ b/src/kim/lib/kim_private.h @@ -33,10 +33,11 @@ #include +#include "kim_library_private.h" +#include "kim_debug_private.h" #include "kim_error_private.h" #include "kim_identity_private.h" #include "kim_ccache_private.h" -#include "kim_library_private.h" #include "kim_options_private.h" #include "kim_preferences_private.h" #include "kim_selection_hints_private.h" diff --git a/src/kim/lib/kim_selection_hints.c b/src/kim/lib/kim_selection_hints.c index 709f1b95b..07ea4e99b 100644 --- a/src/kim/lib/kim_selection_hints.c +++ b/src/kim/lib/kim_selection_hints.c @@ -191,146 +191,44 @@ kim_error kim_selection_hints_copy (kim_selection_hints *out_selection_hints, /* ------------------------------------------------------------------------ */ -kim_error kim_selection_hints_set_service_identity_hint (kim_selection_hints io_selection_hints, - kim_identity in_service_identity) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !io_selection_hints ) { err = param_error (1, "io_selection_hints", "NULL"); } - if (!err && !in_service_identity) { err = param_error (2, "in_service_identity", "KIM_IDENTITY_ANY"); } - - if (!err) { - err = kim_identity_get_string (in_service_identity, &io_selection_hints->service_identity); - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_get_service_identity_hint (kim_selection_hints in_selection_hints, - kim_identity *out_service_identity) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !in_selection_hints ) { err = param_error (1, "in_selection_hints", "NULL"); } - if (!err && !out_service_identity) { err = param_error (2, "out_service_identity", "NULL"); } - - if (!err) { - err = kim_identity_create_from_string (out_service_identity, in_selection_hints->service_identity); - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_set_client_realm_hint (kim_selection_hints io_selection_hints, - kim_string in_client_realm) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !io_selection_hints) { err = param_error (1, "io_selection_hints", "NULL"); } - if (!err && !in_client_realm ) { err = param_error (2, "in_client_realm", "NULL"); } - - if (!err) { - err = kim_string_copy (&io_selection_hints->client_realm, in_client_realm); - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_get_client_realm_hint (kim_selection_hints in_selection_hints, - kim_string *out_client_realm) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !in_selection_hints) { err = param_error (1, "in_selection_hints", "NULL"); } - if (!err && !out_client_realm ) { err = param_error (2, "out_client_realm", "NULL"); } - - if (!err) { - if (in_selection_hints->client_realm) { - err = kim_string_copy (out_client_realm, in_selection_hints->client_realm); - } else { - *out_client_realm = NULL; - } - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_set_user_hint (kim_selection_hints io_selection_hints, - kim_string in_user) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !io_selection_hints) { err = param_error (1, "io_selection_hints", "NULL"); } - if (!err && !in_user ) { err = param_error (2, "in_user", "NULL"); } - - if (!err) { - err = kim_string_copy (&io_selection_hints->user, in_user); - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_get_user_hint (kim_selection_hints in_selection_hints, - kim_string *out_user) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !in_selection_hints) { err = param_error (1, "in_selection_hints", "NULL"); } - if (!err && !out_user ) { err = param_error (2, "out_user", "NULL"); } - - if (!err) { - if (in_selection_hints->user) { - err = kim_string_copy (out_user, in_selection_hints->user); - } else { - *out_user = NULL; - } - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_set_service_realm_hint (kim_selection_hints io_selection_hints, - kim_string in_service_realm) +kim_error kim_selection_hints_set_hint (kim_selection_hints io_selection_hints, + kim_string in_hint_key, + kim_string in_hint_string) { kim_error err = KIM_NO_ERROR; if (!err && !io_selection_hints) { err = param_error (1, "io_selection_hints", "NULL"); } - if (!err && !in_service_realm ) { err = param_error (2, "in_service_realm", "NULL"); } - - if (!err) { - err = kim_string_copy (&io_selection_hints->service_realm, in_service_realm); - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_get_service_realm_hint (kim_selection_hints in_selection_hints, - kim_string *out_service_realm) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !in_selection_hints) { err = param_error (1, "in_selection_hints", "NULL"); } - if (!err && !out_service_realm ) { err = param_error (2, "out_service_realm", "NULL"); } - - if (!err) { - if (in_selection_hints->service_realm) { - err = kim_string_copy (out_service_realm, in_selection_hints->service_realm); + if (!err && !in_hint_key ) { err = param_error (2, "in_hint_key", "NULL"); } + if (!err && !in_hint_string ) { err = param_error (3, "in_hint_string", "NULL"); } + + if (!err) { + if (!strcmp (in_hint_key, kim_hint_key_client_realm)) { + err = kim_string_copy (&io_selection_hints->client_realm, + in_hint_string); + + } else if (!strcmp (in_hint_key, kim_hint_key_user)) { + err = kim_string_copy (&io_selection_hints->user, + in_hint_string); + + } else if (!strcmp (in_hint_key, kim_hint_key_service_realm)) { + err = kim_string_copy (&io_selection_hints->service_realm, + in_hint_string); + + } else if (!strcmp (in_hint_key, kim_hint_key_service)) { + err = kim_string_copy (&io_selection_hints->service, + in_hint_string); + + } else if (!strcmp (in_hint_key, kim_hint_key_server)) { + err = kim_string_copy (&io_selection_hints->server, + in_hint_string); + + } else if (!strcmp (in_hint_key, kim_hint_key_service_identity)) { + err = kim_string_copy (&io_selection_hints->service_identity, + in_hint_string); + } else { - *out_service_realm = NULL; + err = kim_error_set_message_for_code (KIM_UNSUPPORTED_HINT_ECODE, + in_hint_key); } } @@ -339,74 +237,44 @@ kim_error kim_selection_hints_get_service_realm_hint (kim_selection_hints in_se /* ------------------------------------------------------------------------ */ -kim_error kim_selection_hints_set_service_hint (kim_selection_hints io_selection_hints, - kim_string in_service) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !io_selection_hints) { err = param_error (1, "io_selection_hints", "NULL"); } - if (!err && !in_service ) { err = param_error (2, "in_service", "NULL"); } - - if (!err) { - err = kim_string_copy (&io_selection_hints->service, in_service); - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_get_service_hint (kim_selection_hints in_selection_hints, - kim_string *out_service) +kim_error kim_selection_hints_get_hint (kim_selection_hints in_selection_hints, + kim_string in_hint_key, + kim_string *out_hint_string) { kim_error err = KIM_NO_ERROR; if (!err && !in_selection_hints) { err = param_error (1, "in_selection_hints", "NULL"); } - if (!err && !out_service ) { err = param_error (2, "out_service", "NULL"); } - - if (!err) { - if (in_selection_hints->service) { - err = kim_string_copy (out_service, in_selection_hints->service); - } else { - *out_service = NULL; - } - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_set_server_hint (kim_selection_hints io_selection_hints, - kim_string in_server_hostname) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !io_selection_hints) { err = param_error (1, "io_selection_hints", "NULL"); } - if (!err && !in_server_hostname) { err = param_error (2, "in_server_hostname", "NULL"); } - - if (!err) { - err = kim_string_copy (&io_selection_hints->server, in_server_hostname); - } - - return check_error (err); -} - -/* ------------------------------------------------------------------------ */ - -kim_error kim_selection_hints_get_server_hint (kim_selection_hints in_selection_hints, - kim_string *out_server_hostname) -{ - kim_error err = KIM_NO_ERROR; - - if (!err && !in_selection_hints ) { err = param_error (1, "in_selection_hints", "NULL"); } - if (!err && !out_server_hostname) { err = param_error (2, "out_server_hostname", "NULL"); } - - if (!err) { - if (in_selection_hints->server) { - err = kim_string_copy (out_server_hostname, in_selection_hints->server); + if (!err && !in_hint_key ) { err = param_error (2, "in_hint_key", "NULL"); } + if (!err && !out_hint_string ) { err = param_error (3, "out_hint_string", "NULL"); } + + if (!err) { + if (!strcmp (in_hint_key, kim_hint_key_client_realm)) { + err = kim_string_copy (out_hint_string, + in_selection_hints->client_realm); + + } else if (!strcmp (in_hint_key, kim_hint_key_user)) { + err = kim_string_copy (out_hint_string, + in_selection_hints->user); + + } else if (!strcmp (in_hint_key, kim_hint_key_service_realm)) { + err = kim_string_copy (out_hint_string, + in_selection_hints->service_realm); + + } else if (!strcmp (in_hint_key, kim_hint_key_service)) { + err = kim_string_copy (out_hint_string, + in_selection_hints->service); + + } else if (!strcmp (in_hint_key, kim_hint_key_server)) { + err = kim_string_copy (out_hint_string, + in_selection_hints->server); + + } else if (!strcmp (in_hint_key, kim_hint_key_service_identity)) { + err = kim_string_copy (out_hint_string, + in_selection_hints->service_identity); + } else { - *out_server_hostname = NULL; + err = kim_error_set_message_for_code (KIM_UNSUPPORTED_HINT_ECODE, + in_hint_key); } } diff --git a/src/kim/lib/mac/kim_os_debug.c b/src/kim/lib/mac/kim_os_debug.c new file mode 100644 index 000000000..e4236872f --- /dev/null +++ b/src/kim/lib/mac/kim_os_debug.c @@ -0,0 +1,37 @@ +/* + * $Header$ + * + * Copyright 2008 Massachusetts Institute of Technology. + * All Rights Reserved. + * + * Export of this software from the United States of America may + * require a specific license from the United States Government. + * It is the responsibility of any person or organization contemplating + * export to obtain such a license before exporting. + * + * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + * distribute this software and its documentation for any purpose and + * without fee is hereby granted, provided that the above copyright + * notice appear in all copies and that both that copyright notice and + * this permission notice appear in supporting documentation, and that + * the name of M.I.T. not be used in advertising or publicity pertaining + * to distribution of the software without specific, written prior + * permission. Furthermore if you modify this software you must label + * your software as modified software and not distribute it in such a + * fashion that it might be confused with the original M.I.T. software. + * M.I.T. makes no representations about the suitability of + * this software for any purpose. It is provided "as is" without express + * or implied warranty. + */ + +#include +#include + +#include "kim_os_private.h" + +/* ------------------------------------------------------------------------ */ + +void kim_os_debug_print (kim_string in_string) +{ + dprintf (in_string); +} diff --git a/src/kim/lib/mac/kim_os_library.c b/src/kim/lib/mac/kim_os_library.c index cbe3c0d55..350515bca 100644 --- a/src/kim/lib/mac/kim_os_library.c +++ b/src/kim/lib/mac/kim_os_library.c @@ -31,13 +31,6 @@ /* ------------------------------------------------------------------------ */ -void kim_os_library_debug_print (kim_string in_string) -{ - dprintf (in_string); -} - -/* ------------------------------------------------------------------------ */ - kim_boolean kim_os_library_caller_is_server (void) { CFBundleRef mainBundle = CFBundleGetMainBundle (); diff --git a/src/kim/lib/mac/kim_os_preferences.c b/src/kim/lib/mac/kim_os_preferences.c index 9b3f44d4a..3d8e2b4e5 100644 --- a/src/kim/lib/mac/kim_os_preferences.c +++ b/src/kim/lib/mac/kim_os_preferences.c @@ -147,7 +147,7 @@ static kim_error kim_os_preferences_get_value (kim_preference_key in_key, } if (value && CFGetTypeID (value) != in_type) { - err = kim_error_create_from_code (KIM_PREFERENCES_READ_ECODE); + err = check_error (KIM_PREFERENCES_READ_ECODE); } } @@ -184,7 +184,7 @@ static kim_error kim_os_preferences_set_value (kim_preference_key in_key, CFPreferencesSetValue (kim_key, in_value, KIM_PREFERENCES_FILE, user, host); if (!CFPreferencesSynchronize (KIM_PREFERENCES_FILE, user, host)) { - err = kim_error_create_from_code (KIM_PREFERENCES_WRITE_ECODE); + err = check_error (KIM_PREFERENCES_WRITE_ECODE); } } @@ -301,7 +301,7 @@ kim_error kim_os_preferences_get_favorite_identities_for_key (kim_preference_key cfstring = (CFStringRef) CFArrayGetValueAtIndex (value, i); if (!cfstring || CFGetTypeID (cfstring) != CFStringGetTypeID ()) { - err = kim_error_create_from_code (KIM_PREFERENCES_READ_ECODE); + err = check_error (KIM_PREFERENCES_READ_ECODE); } if (!err) { diff --git a/src/kim/lib/mac/kim_os_selection_hints.c b/src/kim/lib/mac/kim_os_selection_hints.c index f10b10e8a..42b56d08e 100644 --- a/src/kim/lib/mac/kim_os_selection_hints.c +++ b/src/kim/lib/mac/kim_os_selection_hints.c @@ -71,7 +71,7 @@ static kim_error kim_os_selection_hints_get_selection_hints_array (CFArrayRef *o } if (value && CFGetTypeID (value) != CFArrayGetTypeID ()) { - err = kim_error_create_from_code (KIM_PREFERENCES_READ_ECODE); + err = check_error (KIM_PREFERENCES_READ_ECODE); } } @@ -101,7 +101,7 @@ static kim_error kim_os_selection_hints_set_selection_hints_array (CFArrayRef in CFPreferencesSetValue (KIM_SELECTION_HINTS_ARRAY, in_selection_hints_array, KIM_SELECTION_HINTS_FILE, user, host); if (!CFPreferencesSynchronize (KIM_SELECTION_HINTS_FILE, user, host)) { - err = kim_error_create_from_code (KIM_PREFERENCES_WRITE_ECODE); + err = check_error (KIM_PREFERENCES_WRITE_ECODE); } } @@ -210,8 +210,6 @@ static kim_boolean kim_os_selection_hints_compare_hint (kim_string in_string, if (!err && kim_comparison_is_equal_to (comparison)) { equal = 1; } - - kim_error_free (&err); } else { kim_debug_printf ("%s: Malformed string in hints dictionary.", __FUNCTION__); } @@ -299,7 +297,7 @@ static kim_error kim_os_selection_hints_get_dictionary_identity (CFDictionaryRef identity_cfstr = CFDictionaryGetValue (in_dictionary, KIM_IDENTITY_HINT); if (!identity_cfstr || CFGetTypeID (identity_cfstr) != CFStringGetTypeID ()) { kim_debug_printf ("%s: Malformed hints dictionary (invalid identity).", __FUNCTION__); - err = kim_error_create_from_code (KIM_PREFERENCES_READ_ECODE); + err = check_error (KIM_PREFERENCES_READ_ECODE); } if (!err) { diff --git a/src/kim/test/test_kim_common.c b/src/kim/test/test_kim_common.c index 75b7116cc..1e10aae0f 100644 --- a/src/kim/test/test_kim_common.c +++ b/src/kim/test/test_kim_common.c @@ -101,8 +101,7 @@ void fail_if_error (kim_test_state_t in_state, printf ("\tFAILURE: "); printf ("%s() got %d (%s) ", - in_function, kim_error_get_code (in_err), - kim_error_get_display_string (in_err)); + in_function, in_err, kim_error_message (in_err)); va_start (args, in_format); vprintf (in_format, args); diff --git a/src/kim/test/test_kim_identity.c b/src/kim/test/test_kim_identity.c index 5a0c63fa6..db225e54c 100644 --- a/src/kim/test/test_kim_identity.c +++ b/src/kim/test/test_kim_identity.c @@ -109,8 +109,6 @@ void test_kim_identity_create_from_krb5_principal (kim_test_state_t state) kim_identity_free (&identity); if (principal) { krb5_free_principal (context, principal); } if (context ) { krb5_free_context (context); } - - kim_error_free (&err); } printf ("\n"); @@ -154,7 +152,6 @@ void test_kim_identity_create_from_string (kim_test_state_t state) kim_string_free (&string); kim_identity_free (&identity); - kim_error_free (&err); } printf ("\n"); @@ -207,7 +204,6 @@ void test_kim_identity_copy (kim_test_state_t state) kim_string_free (&string); kim_identity_free (&identity_copy); kim_identity_free (&identity); - kim_error_free (&err); } printf ("\n"); @@ -265,7 +261,6 @@ void test_kim_identity_compare (kim_test_state_t state) } kim_identity_free (&identity); - kim_error_free (&err); } printf ("\n"); @@ -309,7 +304,6 @@ void test_kim_identity_get_display_string (kim_test_state_t state) kim_string_free (&string); kim_identity_free (&identity); - kim_error_free (&err); } printf ("\n"); @@ -352,7 +346,6 @@ void test_kim_identity_get_realm (kim_test_state_t state) kim_string_free (&realm); kim_identity_free (&identity); - kim_error_free (&err); } printf ("\n"); @@ -395,7 +388,6 @@ void test_kim_identity_get_number_of_components (kim_test_state_t state) } kim_identity_free (&identity); - kim_error_free (&err); } printf ("\n"); @@ -443,7 +435,6 @@ void test_kim_identity_get_component_at_index (kim_test_state_t state) } kim_identity_free (&identity); - kim_error_free (&err); } printf ("\n"); @@ -505,8 +496,6 @@ void test_kim_identity_get_krb5_principal (kim_test_state_t state) if (identity_principal) { krb5_free_principal (context, identity_principal); } if (principal ) { krb5_free_principal (context, principal); } if (context ) { krb5_free_context (context); } - - kim_error_free (&err); } printf ("\n"); @@ -549,7 +538,6 @@ void test_kim_identity_is_tgt_service (kim_test_state_t state) } kim_identity_free (&identity); - kim_error_free (&err); } printf ("\n"); diff --git a/src/kim/test/test_kim_preferences.c b/src/kim/test/test_kim_preferences.c index 7c7637ef6..8b7a54912 100644 --- a/src/kim/test/test_kim_preferences.c +++ b/src/kim/test/test_kim_preferences.c @@ -42,7 +42,6 @@ void test_kim_preferences_create (kim_test_state_t state) "while creating preferences"); kim_preferences_free (&prefs); - kim_error_free (&err); } end_test (state); @@ -72,7 +71,6 @@ void test_kim_preferences_copy (kim_test_state_t state) kim_preferences_free (&prefs_copy); kim_preferences_free (&prefs); - kim_error_free (&err); } end_test (state); @@ -149,7 +147,6 @@ void test_kim_preferences_set_options (kim_test_state_t state) kim_options_free (&new_options); kim_options_free (&verify_options); kim_preferences_free (&prefs); - kim_error_free (&err); } end_test (state); @@ -206,7 +203,6 @@ void test_kim_preferences_set_remember_options (kim_test_state_t state) } kim_preferences_free (&prefs); - kim_error_free (&err); } end_test (state); @@ -291,7 +287,6 @@ void test_kim_preferences_set_client_identity (kim_test_state_t state) kim_identity_free (&identity); kim_identity_free (&test_identity); kim_preferences_free (&prefs); - kim_error_free (&err); } end_test (state); -- 2.26.2