From 048049230d7e60c90ad40e6c3b7a8a43c4c5af5b Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Wed, 23 Mar 2016 13:15:58 -0400 Subject: [PATCH] Amend KDC hook documentation In the Doxygen comments for the new APIs and types, include @version tags indicating that they are new in 1.15, and put @param declarations just after the brief message for consistency with other comments. ticket: 8386 --- src/include/krb5/krb5.hin | 46 +++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin index c045ee3770..f52a9ea90c 100644 --- a/src/include/krb5/krb5.hin +++ b/src/include/krb5/krb5.hin @@ -8302,6 +8302,13 @@ krb5_set_trace_filename(krb5_context context, const char *filename); /** * Hook function for inspecting or modifying messages sent to KDCs. * + * @param [in] context Library context + * @param [in] data Callback data + * @param [in] realm The realm the message will be sent to + * @param [in] message The original message to be sent to the KDC + * @param [out] new_message_out Optional replacement message to be sent + * @param [out] reply_out Optional synthetic reply + * * If the hook function returns an error code, the KDC communication will be * aborted and the error code will be returned to the library operation which * initiated the communication. @@ -8319,12 +8326,7 @@ krb5_set_trace_filename(krb5_context context, const char *filename); * @a new_message_out or @a reply_out, to ensure that it can be freed correctly * by the library. * - * @param [in] context Library context - * @param [in] data Callback data - * @param [in] realm The realm the message will be sent to - * @param [in] message The original message to be sent to the KDC - * @param [out] new_message_out Optional replacement message to be sent - * @param [out] reply_out Optional synthetic reply + * @version New in 1.15 * * @retval 0 Success * @return A Kerberos error code @@ -8339,6 +8341,14 @@ typedef krb5_error_code /** * Hook function for inspecting or overriding KDC replies. * + * @param [in] context Library context + * @param [in] data Callback data + * @param [in] code Status of KDC communication + * @param [in] realm The realm the reply was received from + * @param [in] message The message sent to the realm's KDC + * @param [in] reply The reply received from the KDC + * @param [out] new_reply_out Optional replacement reply + * * If @a code is zero, @a reply contains the reply received from the KDC. The * hook function may return an error code to simulate an error, may synthesize * a different reply by setting @a new_reply_out, or may simply return @@ -8351,13 +8361,7 @@ typedef krb5_error_code * The hook function should use krb5_copy_data() to construct the value for * @a new_reply_out, to ensure that it can be freed correctly by the library. * - * @param [in] context Library context - * @param [in] data Callback data - * @param [in] code Status of KDC communication - * @param [in] realm The realm the reply was received from - * @param [in] message The message sent to the realm's KDC - * @param [in] reply The reply received from the KDC - * @param [out] new_reply_out Optional replacement reply + * @version New in 1.15 * * @retval 0 Success * @return A Kerberos error code @@ -8373,13 +8377,15 @@ typedef krb5_error_code /** * Set a KDC pre-send hook function. * + * @param [in] context Library context + * @param [in] send_hook Hook function (or NULL to disable the hook) + * @param [in] data Callback data to be passed to @a send_hook + * * @a send_hook will be called before messages are sent to KDCs by library * functions such as krb5_get_credentials(). The hook function may inspect, * override, or synthesize its own reply to the message. * - * @param [in] context Library context - * @param [in] send_hook Hook function (or NULL to disable the hook) - * @param [in] data Callback data to be passed to @a send_hook + * @version New in 1.15 */ void KRB5_CALLCONV krb5_set_kdc_send_hook(krb5_context context, krb5_pre_send_fn send_hook, @@ -8388,14 +8394,16 @@ krb5_set_kdc_send_hook(krb5_context context, krb5_pre_send_fn send_hook, /** * Set a KDC post-receive hook function. * + * @param [in] context The library context. + * @param [in] recv_hook Hook function (or NULL to disable the hook) + * @param [in] data Callback data to be passed to @a recv_hook + * * @a recv_hook will be called after a reply is received from a KDC during a * call to a library function such as krb5_get_credentials(). The hook * function may inspect or override the reply. This hook will not be executed * if the pre-send hook returns a synthetic reply. * - * @param [in] context The library context. - * @param [in] recv_hook Hook function (or NULL to disable the hook) - * @param [in] data Callback data to be passed to @a recv_hook + * @version New in 1.15 */ void KRB5_CALLCONV krb5_set_kdc_recv_hook(krb5_context context, krb5_post_recv_fn recv_hook, -- 2.47.2