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 */
/*!
* \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);
* \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,
* \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,
* \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.
*/
* \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,
* 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,
/*!
* \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);
* \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.
* 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,
* \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,
* \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,
/*!
* \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,
/*!
* \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,
* display to the user in command line programs. (ie: "<type>:<name>")
* Must be freed with kim_string_free().
* Note: this string can also be passed to krb5_cc_resolve().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the type and name for a ccache in display format.
*/
kim_error kim_ccache_get_display_name (kim_ccache in_ccache,
* \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,
* \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
* \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
* \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,
* \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,
* \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,
/*!
* \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.
* 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,
/*!
* \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,
/*!
* \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,
/*!
* \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.
* \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.
*/
* \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.
*/
* \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
*/
* 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
*/
* 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,
* \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,
* \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,
* \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,
* \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,
/*!
* \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,
* \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,
* \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
*/
* \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
*/
* \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
*/
* \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,
* 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
*/
* 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
*/
* 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
*/
/*!
* \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.
*/
*/
/*!
- * \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);
/*!@}*/
* \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,
* 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,
* 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,
* \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,
* \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,
* \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 '\'.
*/
* \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()
* \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,
/*!
* \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,
* \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,
* \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,
* \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,
/*!
* \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
* \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
* 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.
* \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);
/*! @} */
/*!
* \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);
* \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,
/*!
* \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
* \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
/*!
* \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.
* \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.
* \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,
* \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,
* \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.
* \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.
/*!
* \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
/*!
* \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
* \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.
* \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.
/*!
* \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
* \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
* \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.
* \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.
* \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.
* \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.
* \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.
* \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.
/*!
* \param io_options an options object to modify.
* \param in_service_name a service name.
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Set the service name to request a credential for.
* \par Default value
* NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
* \param in_options an options object.
* \param out_service_name on exit, the service name specified in \a in_options.
* Must be freed with kim_string_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error object representing the failure.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Get the service name to request a credential for.
* \par Default value
* NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
/*!
* \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);
* 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,
/*!
* \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,
* \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,
/*!
* \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,
/*!
* \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,
/*!
* \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);
/*!
* \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);
* \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,
/*!
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
/*!
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
/*!
* \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.
*/
* @{
*/
+#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,
* \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.
* \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()
*/
* \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()
*/
* \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()
*/
* \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()
*/
/*!
* \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()
*/
* \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()
*/
* \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
* \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
* \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
* \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
* \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.
/*!
* \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.
*/
/*!
* \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.
*/
* @{
*/
+/*!
+ * \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.
*/
/*!
- * 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.
*/
#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;
/*!
}
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];
}
}
- 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;
}
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;
}
-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
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);
}
}
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);
}
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);
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);
}
}
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));
&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); }
--- /dev/null
+/*
+ * $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);
+}
--- /dev/null
+/*
+ * $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);
* or implied warranty.
*/
+#include "k5-int.h"
#include "kim_private.h"
#include <com_err.h>
#include <CredentialsCache.h>
-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);
}
/* ------------------------------------------------------------------------ */
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 --
/* ------------------------------------------------------------------------ */
-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);
/* ------------------------------------------------------------------------ */
-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));
}
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
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"
#include <kim/kim.h>
-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 */
/*
* $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
#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;
kim_boolean allow_access = FALSE;
kim_error err = kim_library_get_allow_home_directory_access (&allow_access);
- kim_error_free (&err);
-
return allow_access;
}
if (files ) { krb5_free_config_files (files); }
}
- kim_error_free (&err);
-
return allow_automatic_prompting;
}
#include <kim/kim.h>
-#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);
/* ------------------------------------------------------------------------ */
-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"); }
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"); }
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"); }
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;
}
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);
}
}
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);
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);
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);
#include <kim/kim.h>
+#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"
/* ------------------------------------------------------------------------ */
-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);
}
}
/* ------------------------------------------------------------------------ */
-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);
}
}
--- /dev/null
+/*
+ * $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 <CoreServices/CoreServices.h>
+#include <Kerberos/KerberosDebug.h>
+
+#include "kim_os_private.h"
+
+/* ------------------------------------------------------------------------ */
+
+void kim_os_debug_print (kim_string in_string)
+{
+ dprintf (in_string);
+}
/* ------------------------------------------------------------------------ */
-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 ();
}
if (value && CFGetTypeID (value) != in_type) {
- err = kim_error_create_from_code (KIM_PREFERENCES_READ_ECODE);
+ err = check_error (KIM_PREFERENCES_READ_ECODE);
}
}
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);
}
}
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) {
}
if (value && CFGetTypeID (value) != CFArrayGetTypeID ()) {
- err = kim_error_create_from_code (KIM_PREFERENCES_READ_ECODE);
+ err = check_error (KIM_PREFERENCES_READ_ECODE);
}
}
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);
}
}
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__);
}
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) {
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);
kim_identity_free (&identity);
if (principal) { krb5_free_principal (context, principal); }
if (context ) { krb5_free_context (context); }
-
- kim_error_free (&err);
}
printf ("\n");
kim_string_free (&string);
kim_identity_free (&identity);
- kim_error_free (&err);
}
printf ("\n");
kim_string_free (&string);
kim_identity_free (&identity_copy);
kim_identity_free (&identity);
- kim_error_free (&err);
}
printf ("\n");
}
kim_identity_free (&identity);
- kim_error_free (&err);
}
printf ("\n");
kim_string_free (&string);
kim_identity_free (&identity);
- kim_error_free (&err);
}
printf ("\n");
kim_string_free (&realm);
kim_identity_free (&identity);
- kim_error_free (&err);
}
printf ("\n");
}
kim_identity_free (&identity);
- kim_error_free (&err);
}
printf ("\n");
}
kim_identity_free (&identity);
- kim_error_free (&err);
}
printf ("\n");
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");
}
kim_identity_free (&identity);
- kim_error_free (&err);
}
printf ("\n");
"while creating preferences");
kim_preferences_free (&prefs);
- kim_error_free (&err);
}
end_test (state);
kim_preferences_free (&prefs_copy);
kim_preferences_free (&prefs);
- kim_error_free (&err);
}
end_test (state);
kim_options_free (&new_options);
kim_options_free (&verify_options);
kim_preferences_free (&prefs);
- kim_error_free (&err);
}
end_test (state);
}
kim_preferences_free (&prefs);
- kim_error_free (&err);
}
end_test (state);
kim_identity_free (&identity);
kim_identity_free (&test_identity);
kim_preferences_free (&prefs);
- kim_error_free (&err);
}
end_test (state);
projects / krb5.git / commitdiff