/* * Copyright 2005-2006 Massachusetts Institute of Technology. * All Rights Reserved. * * Export of this software from the United States of America may * require a specific license from the United States Government. * It is the responsibility of any person or organization contemplating * export to obtain such a license before exporting. * * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and * distribute this software and its documentation for any purpose and * without fee is hereby granted, provided that the above copyright * notice appear in all copies and that both that copyright notice and * this permission notice appear in supporting documentation, and that * the name of M.I.T. not be used in advertising or publicity pertaining * to distribution of the software without specific, written prior * permission. Furthermore if you modify this software you must label * your software as modified software and not distribute it in such a * fashion that it might be confused with the original M.I.T. software. * M.I.T. makes no representations about the suitability of * this software for any purpose. It is provided "as is" without express * or implied warranty. */ #ifndef KIM_STRING_H #define KIM_STRING_H #ifdef __cplusplus extern "C" { #endif #include <Kerberos/kim_types.h> /*! * \page kim_string_overview KIM String Overview * * A UTF8 string. * * Memory management routines are provided for runtime consistency on * operating systems with shared libraries and multiple runtimes. * * \section kim_string_error_messages KIM Error Messages * * Like most C APIs, the KIM API returns numeric error codes. These error * codes may come from KIM, krb5 or GSS APIs. In most cases the caller will * want to handle these error programmatically. However, in some circumstances * the caller may wish to print an error string to the user. * * One problem with just printing the error code to the user is that frequently * the context behind the error has been lost. For example if KIM is trying to * obtain credentials via referrals, it may fail partway through the process. * In this case the error code will be KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN, which * maps to "Client not found in Kerberos database". Unfortunately this error * isn't terribly helpful because it doesn't tell the user whether they typoed * their principal name or if referrals failed. * * To avoid this problem, KIM maintains an explanatory string for the last * error seen in each thread calling into KIM. If a caller wishes to display * an error to the user, immediately after getting the error the caller should * call #kim_string_create_for_last_error() to obtain a copy of the * descriptive error message. * * See \ref kim_string_reference for information on specific APIs. */ /*! * \defgroup kim_string_reference KIM String Reference Documentation * @{ */ /*! * \param out_string On success, a human-readable UTF-8 string describing the * error representedby \a in_error. Must be freed with * kim_string_free(). * \param in_error an error code. Used to verify that the correct error * string will be returned (see note below). * \return On success, KIM_NO_ERROR. * \note This API is implemented using thread local storage. It should be * called immediately after a KIM API returns an error code so that the correct * string is returned. The returned copy may then be held by the caller until * needed. If \a in_error does not match the last saved error KIM may return * a less descriptive string. * \brief Get a text description of an error suitable for display to the user. */ kim_error kim_string_create_for_last_error (kim_string *out_string, kim_error in_error); /*! * \param out_string on exit, a new string object which is a copy of \a in_string. Must be freed with kim_string_free(). * \param in_string the string to copy. * \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); /*! * \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 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); /*! * \param io_string a string to be freed. Set to NULL on exit. * \brief Free memory associated with a string. */ void kim_string_free (kim_string *io_string); /*!@}*/ #ifdef __cplusplus } #endif #endif /* KIM_STRING_H */