From f40e802c4e1bea4734d48890e21eee5b571fe120 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Love=20H=C3=B6rnquist=20=C3=85strand?= Date: Sun, 11 Nov 2007 10:09:42 +0000 Subject: [PATCH] Sprinkle some more doxygen. git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@22048 ec53bebd-3082-4978-b11e-865c3cabbd6b --- lib/krb5/context.c | 123 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 118 insertions(+), 5 deletions(-) diff --git a/lib/krb5/context.c b/lib/krb5/context.c index f1e1183d4..a79bd8708 100644 --- a/lib/krb5/context.c +++ b/lib/krb5/context.c @@ -186,6 +186,21 @@ init_context_from_config_file(krb5_context context) return 0; } +/** + * Initializes the context structure and reads the configuration file + * /etc/krb5.conf. The structure should be freed by calling + * krb5_free_context() when it is no longer being used. + * + * @param context pointer to returned context + * + * @return Returns 0 to indicate success. Otherwise an errno code is + * returned. Failure means either that something bad happened during + * initialization (typically ENOMEM) or that Kerberos should not be + * used ENXIO. + * + * @ingroup krb5 + */ + krb5_error_code KRB5_LIB_FUNCTION krb5_init_context(krb5_context *context) { @@ -246,6 +261,14 @@ out: return ret; } +/** + * Frees the krb5_context allocated by krb5_init_context(). + * + * @param context context to be freed. + * + * @ingroup krb5 +*/ + void KRB5_LIB_FUNCTION krb5_free_context(krb5_context context) { @@ -274,6 +297,18 @@ krb5_free_context(krb5_context context) free(context); } +/** + * Reinit the context from a new set of filenames. + * + * @param context context to add configuration too. + * @param filenames array of filenames, end of list is indicated with a NULL filename. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + krb5_error_code KRB5_LIB_FUNCTION krb5_set_config_files(krb5_context context, char **filenames) { @@ -382,6 +417,18 @@ krb5_prepend_config_files(const char *filelist, char **pq, char ***ret_pp) return 0; } +/** + * Prepend the filename to the global configuration list. + * + * @param filelist a filename to add to the default list of filename + * @param pfilenames return array of filenames, should be freed with krb5_free_config_files(). + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + krb5_error_code KRB5_LIB_FUNCTION krb5_prepend_config_files_default(const char *filelist, char ***pfilenames) { @@ -401,6 +448,17 @@ krb5_prepend_config_files_default(const char *filelist, char ***pfilenames) return 0; } +/** + * Get the global configuration list. + * + * @param pfilenames return array of filenames, should be freed with krb5_free_config_files(). + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + krb5_error_code KRB5_LIB_FUNCTION krb5_get_default_config_files(char ***pfilenames) { @@ -416,6 +474,17 @@ krb5_get_default_config_files(char ***pfilenames) return krb5_prepend_config_files(files, NULL, pfilenames); } +/** + * Free a list of configuration files. + * + * @param filenames list to be freed. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + void KRB5_LIB_FUNCTION krb5_free_config_files(char **filenames) { @@ -425,12 +494,17 @@ krb5_free_config_files(char **filenames) free(filenames); } -/* +/** * Returns the list of Kerberos encryption types sorted in order of - * most preferred to least preferred encryption type. The array ends - * with ETYPE_NULL. Note that some encryption types might be - * disabled, so you need to check with krb5_enctype_valid() before - * using the encryption type. + * most preferred to least preferred encryption type. Note that some + * encryption types might be disabled, so you need to check with + * krb5_enctype_valid() before using the encryption type. + * + * @return list of enctypes, terminated with ETYPE_NULL. Its a static + * array completed into the Kerberos library so the content doesn't + * need to be freed. + * + * @ingroup krb5 */ const krb5_enctype * KRB5_LIB_FUNCTION @@ -536,6 +610,18 @@ krb5_get_default_in_tkt_etypes(krb5_context context, return 0; } +/** + * Return the error string for the error code. The caller must not + * free the string. + * + * @param context Kerberos 5 context. + * @param code Kerberos error code. + * + * @return the error message matching code + * + * @ingroup krb5 + */ + const char* KRB5_LIB_FUNCTION krb5_get_err_text(krb5_context context, krb5_error_code code) { @@ -549,6 +635,14 @@ krb5_get_err_text(krb5_context context, krb5_error_code code) return p; } +/** + * Init the built-in ets in the Kerberos library. + * + * @param context kerberos context to add the ets too + * + * @ingroup krb5 + */ + void KRB5_LIB_FUNCTION krb5_init_ets(krb5_context context) { @@ -563,12 +657,31 @@ krb5_init_ets(krb5_context context) } } +/** + * Make the kerberos library default to the admin KDC. + * + * @param context kerberos context + * @param flag boolean flag to select if the use the admin KDC or not. + * + * @ingroup krb5 + */ + void KRB5_LIB_FUNCTION krb5_set_use_admin_kdc (krb5_context context, krb5_boolean flag) { context->use_admin_kdc = flag; } +/** + * Make the kerberos library default to the admin KDC. + * + * @param context kerberos context + * + * @return boolean flag to telling the context will use admin KDC as the default KDC. + * + * @ingroup krb5 + */ + krb5_boolean KRB5_LIB_FUNCTION krb5_get_use_admin_kdc (krb5_context context) {