/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
/*
 * Copyright 2008 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_UI_PLUGIN_H
#define KIM_UI_PLUGIN_H

#ifdef __cplusplus
extern "C" {
#endif

/*!
 * The type of prompt which needs to be displayed.
 * This value determines what type of user interface is displayed.
 * See \ref kim_options_custom_prompt_callback for more information.
 */
typedef uint32_t kim_prompt_type;

enum kim_prompt_type_enum {
    kim_prompt_type_password = 0,
    kim_prompt_type_preauth = 1
};

/*
 * Plugins for Controlling Identity Selection and Credential Acquisition
 *
 * In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user.
 * These secrets may be a certificate, password, SecurID pin, or information from a smart card.
 * If obtaining the secret requires interaction with the user, the Kerberos libraries call a
 * "prompter callback" to display a dialog or command line prompt to request information from
 * the user.  If you want to provide your own custom dialogs or command line prompts,
 * the KIM APIs provide a plugin mechanism for replacing the default prompt ui with your own.
 *
 * The function table / structure which a KIM ui plugin module must export
 * as "kim_ui_0".  If the interfaces work correctly, future versions of the
 * table will add either more callbacks or more arguments to callbacks, and
 * in both cases we'll be able to wrap the v0 functions.
 */
/* extern kim_ui_plugin_ftable_v0 kim_ui_0; */


typedef struct kim_ui_plugin_ftable_v0 {
    int minor_version;          /* currently 0 */

    /* Called before other calls to allow the UI to initialize.
     * Return an error if you can't display your UI in this environment.
     * To allow your plugin to be called from multiple threads, pass back
     * state associated with this instance of your UI in out_context.
     * The same context pointer will be provided to all plugin calls for
     * this ui. */
    kim_error (*init) (void **out_context);

    /* Present UI which allows the user to enter a new identity.
     * This is typically called when the user selects a "new tickets"
     * control or menu item from a ticket management utility.
     * If this UI calls into KIM to get new credentials it may
     * call auth_prompt below.
     * If out_change_password is set to TRUE, KIM will call change_password
     * on the identity and then call enter_identity again, allowing you
     * to have a change password option on your UI. */
    kim_error (*enter_identity) (void         *in_context,
                                 kim_options   io_options,
                                 kim_identity *out_identity,
                                 kim_boolean  *out_change_password);

    /* Present UI to select which identity to use.
     * This is typically called the first time an application tries to use
     * Kerberos and is used to establish a hints preference for the application.
     * If this UI calls into KIM to get new credentials it may
     * call auth_prompt below.
     * If out_change_password is set to TRUE, KIM will call change_password
     * on the identity and then call select_identity again, allowing you
     * to have a change password option on your UI. */
    kim_error (*select_identity) (void                *in_context,
                                  kim_selection_hints  io_hints,
                                  kim_identity        *out_identity,
                                  kim_boolean         *out_change_password);

    /* Present UI to display authentication to the user */
    /* If in_allow_save_reply is FALSE do not display UI to allow the user
     * to save their password. In this case the value of out_save_reply will
     * be ignored. */
    kim_error (*auth_prompt) (void              *in_context,
                              kim_identity       in_identity,
                              kim_prompt_type    in_type,
                              kim_boolean        in_allow_save_reply,
                              kim_boolean        in_hide_reply,
                              kim_string         in_title,
                              kim_string         in_message,
                              kim_string         in_description,
                              char             **out_reply,
                              kim_boolean       *out_save_reply);

    /* Prompt to change the identity's password.
     * May be combined with an auth_prompt if additional auth is required,
     * eg: SecurID pin.
     * If in_old_password_expired is true, this callback is in response
     * to an expired password error.  If this is the case the same context
     * which generated the error will be used for this callback. */
    kim_error (*change_password) (void          *in_context,
                                  kim_identity   in_identity,
                                  kim_boolean    in_old_password_expired,
                                  char         **out_old_password,
                                  char         **out_new_password,
                                  char         **out_verify_password);

    /* Display an error to the user; may be called after any of the prompts */
    kim_error (*handle_error) (void         *in_context,
                               kim_identity  in_identity,
                               kim_error     in_error,
                               kim_string    in_error_message,
                               kim_string    in_error_description);

    /* Free strings returned by the UI. Will be called once for each string
     * returned from a plugin callback.  If you have returned a string twice
     * just make sure your free function checks for NULL and sets the pointer
     * to NULL when done freeing memory.  */
    void (*free_string) (void  *in_context,
                         char **io_string);

    /* Called after the last prompt (even on error) to allow the UI to
     * free allocated resources associated with its context. */
    kim_error (*fini) (void *io_context);

} kim_ui_plugin_ftable_v0;


#ifdef __cplusplus
}
#endif

#endif /* KIM_UI_PLUGIN_H */
