# kim_string.h   [plain text]

/*
* Copyright 2005-2006 Massachusetts Institute of Technology.
*
* 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 */