<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>kim_string.h</title>
<style type="text/css">
.enscript-comment { font-style: italic; color: rgb(178,34,34); }
.enscript-function-name { font-weight: bold; color: rgb(0,0,255); }
.enscript-variable-name { font-weight: bold; color: rgb(184,134,11); }
.enscript-keyword { font-weight: bold; color: rgb(160,32,240); }
.enscript-reference { font-weight: bold; color: rgb(95,158,160); }
.enscript-string { font-weight: bold; color: rgb(188,143,143); }
.enscript-builtin { font-weight: bold; color: rgb(218,112,214); }
.enscript-type { font-weight: bold; color: rgb(34,139,34); }
.enscript-highlight { text-decoration: underline; color: 0; }
</style>
</head>
<body id="top">
<h1 style="margin:8px;" id="f1">kim_string.h&nbsp;&nbsp;&nbsp;<span style="font-weight: normal; font-size: 0.5em;">[<a href="kim_string.h">plain text</a>]</span></h1>
<hr/>
<div></div>
<pre>
<span class="enscript-comment">/*
 * 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 &quot;as is&quot; without express
 * or implied warranty.
 */</span>

#<span class="enscript-reference">ifndef</span> <span class="enscript-variable-name">KIM_STRING_H</span>
#<span class="enscript-reference">define</span> <span class="enscript-variable-name">KIM_STRING_H</span>

#<span class="enscript-reference">ifdef</span> <span class="enscript-variable-name">__cplusplus</span>
<span class="enscript-type">extern</span> <span class="enscript-string">&quot;C&quot;</span> {
#<span class="enscript-reference">endif</span>

#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_types.h&gt;</span>

<span class="enscript-comment">/*!
 * \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 &quot;Client not found in Kerberos database&quot;.  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.
 */</span>

<span class="enscript-comment">/*!
 * \defgroup kim_string_reference KIM String Reference Documentation
 * @{
 */</span>

<span class="enscript-comment">/*!
 * \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.
 */</span>
kim_error <span class="enscript-function-name">kim_string_create_for_last_error</span> (kim_string *out_string,
                                            kim_error   in_error);
    
<span class="enscript-comment">/*!
 * \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.
 */</span>
kim_error <span class="enscript-function-name">kim_string_copy</span> (kim_string       *out_string,
                           <span class="enscript-type">const</span> kim_string  in_string);

<span class="enscript-comment">/*!
 * \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.
 */</span>
kim_error <span class="enscript-function-name">kim_string_compare</span> (kim_string      in_string, 
                              kim_string      in_compare_to_string,
                              kim_comparison *out_comparison);
    
<span class="enscript-comment">/*!
 * \param io_string a string to be freed.  Set to NULL on exit.
 * \brief Free memory associated with a string.
 */</span>
<span class="enscript-type">void</span> <span class="enscript-function-name">kim_string_free</span> (kim_string *io_string);

<span class="enscript-comment">/*!@}*/</span>

#<span class="enscript-reference">ifdef</span> <span class="enscript-variable-name">__cplusplus</span>
}
#<span class="enscript-reference">endif</span>

#<span class="enscript-reference">endif</span> <span class="enscript-comment">/* KIM_STRING_H */</span>
</pre>
<hr />
</body></html>