path: root/src/windows/identity/include/khmsgtypes.h

/*
 * Copyright (c) 2005 Massachusetts Institute of Technology
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use, copy,
 * modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/* $Id$ */

#ifndef __KHIMAIRA_KHMSGTYPES_H
#define __KHIMAIRA_KHMSGTYPES_H

/*! \addtogroup kmq
@{*/
/*! \defgroup kmq_msg Message Types
@{*/

/*! \name Global message types
@{*/

/*! \brief System messages.

    All subscribers are subscribed to the system message class by default.

    \see \ref kmq_msg_system
*/
#define KMSG_SYSTEM     0

/*! \brief Ad-hoc messages.

    These are messages that are sent through add hoc publishers and
    subscribers.
*/
#define KMSG_ADHOC      1

/*! \brief NetIDMgr Credentials Database messages

    These messages notify subscribers of events related to the
    credentials database, such as the registration, unregistration and
    modification of identities, attributes, attribute types and
    credential types.  It also provides notifications of changes to
    the root crednetial set.

    \see \ref kmq_msg_kcdb
*/
#define KMSG_KCDB       2

/*! \brief NetIDMgr Module Manager messages

    \see \ref kmq_msg_kmm
*/
#define KMSG_KMM        3

/*! \brief NetIDMgr Credential messages

    Notifications of crednetial events.  These are the most important
    events that a credentials provider should respond to.  The
    notifications provide co-oridination between credential providers
    for performing basic credentials management tasks such as
    obtaining new credentials for an identity, deleting credentials
    for an identity, obtaining or deleting credentials of a particular
    type for an identity etc.

    \see \ref cred_msgs
    \see \ref kmq_msg_cred
 */
#define KMSG_CRED       4

/*! \brief Action list messages

    Notifications of changes in action state and firing of custom
    actions.

    \see \ref kmq_msg_act
 */
#define KMSG_ACT        5

/*! \brief Alert messages

    Notifier is the component which displays alerts and error messages
    when the NetIDMgr window is normally in operation and which
    displays balloon prompts when the window is minimized to alert the
    user to important messages such as credentials expiring etc.

    \note This is an internal message class.  Components that are not
        the notifier should not be subscribing to alert messages.

    \see \ref kmq_msg_alert
 */
#define KMSG_ALERT      6

/*! \brief Identity messages

    These are messages that are sent to the identity provider.  These
    are generally dispatched through a specific subscription object
    and are not broadcast.

    \see \ref kmq_msg_ident
 */
#define KMSG_IDENT      7

/*! \brief Base message type ID for customized message types
 */
#define KMSGBASE_USER   16

/*@}*/

/*! \defgroup kmq_msg_system KMSG_SYSTEM subtypes
@{*/
/*! \brief Generic initialization message

    This message is used by specific components to signal that the
    recipient is to perform initialization tasks.  As a convention,
    the recipient should return KHM_ERROR_SUCCESS if it successfully
    performed the initlization tasks or some other value if it failed
    to do so.  Failure to successfully initialize is usually taken to
    mean that the recipient component is not able to perform its
    function.

    Usually this is the first message to be received by the recipient.

    \see \ref pi_pt_cred_init
 */
#define KMSG_SYSTEM_INIT    1

/*! \brief Generic uninitialization message

    Used by specific components to signal that the recipient should
    perform uninitilization tasks in preparation of termination.  The
    return value of this message is not used.

    Usually this is the last message to be received by the recipient.

    \see \ref pi_pt_cred_exit
 */
#define KMSG_SYSTEM_EXIT    2

/*! \brief Message completion

    This is an internal message
 */
#define KMSG_SYSTEM_COMPLETION 3
/*@}*/

/*! \defgroup kmq_msg_kcdb KMSG_KCDB subtypes
@{*/
#define KMSG_KCDB_IDENT     1
#define KMSG_KCDB_CREDTYPE  2
#define KMSG_KCDB_ATTRIB    3
#define KMSG_KCDB_TYPE      4

/*! \brief Generic credentials request

    \see ::kcdb_cred_request for more information
 */
#define KMSG_KCDB_REQUEST   256
/*@}*/

/*! \defgroup kmq_msg_kmm KMSG_KMM subtypes
@{*/
#define KMSG_KMM_I_REG      1

#define KMSG_KMM_I_DONE     2
/*@}*/

/*! \defgroup kmq_msg_act KMSG_ACT subtypes
  @{*/

/*! \brief One or more actions changed state

    This message is sent in response to a call to
    khui_enable_actions() or khui_enable_action() and indicates that
    one or more actions have changed their state.
 */
#define KMSG_ACT_ENABLE     1

/*! \brief One or more actions changed check state

    Sent in response to khui_check_radio_action() or
    khui_check_action() and indicates that one or more actions have
    either been checked or unchecked.
 */
#define KMSG_ACT_CHECK      2

/*! \brief Refresh action states

    Sent after a batch of modifications were made to action states.
 */
#define KMSG_ACT_REFRESH    3

/*! \brief A new action was created

    Sent when a new custom action was created.  The \a uparam
    parameter of the message contains the identifier of the newly
    created action.
*/
#define KMSG_ACT_NEW        4

/*! \brief A custom action was deleted

    Sent after a custom action is deleted.  The \a uparam parameter of
    the message contains the identifier of the deleted action.
 */
#define KMSG_ACT_DELETE     5

/*! \brief A custom action has been activated

    When a custom action is activated, then the listener of that
    custom action receives this message.  Note that only the listener
    for that custom action will receive this notification.

    \a uparam of the message is set to the identifier of the custom
    action.
 */
#define KMSG_ACT_ACTIVATE   6

/*! \brief Internal */
#define KMSG_ACT_BEGIN_CMDLINE       128

/*! \brief Internal */
#define KMSG_ACT_CONTINUE_CMDLINE    129

/*! \brief Internal */
#define KMSG_ACT_SYNC_CFG            130

/*! \brief Internal */
#define KMSG_ACT_END_CMDLINE         131

/*@}*/

/*! \defgroup kmq_msg_cred KMSG_CRED subtypes
  @{*/
/*! \brief Root credential set changed

    This message is issued when the root credential set successfully
    collected credentials from another credential set.

    \a uparam of the message is set to a bitmask indicating the change
    that occured.  It is a combination of ::KCDB_DELTA_ADD,
    ::KCDB_DELTA_DEL and ::KCDB_DELTA_MODIFY.
 */
#define KMSG_CRED_ROOTDELTA 1

/*! \brief Re-enumerate credentials

    A notice to all credential providers to re-enumerate their
    respective credentials.

    \note May be sent to individual credential subscriptions.
 */
#define KMSG_CRED_REFRESH   2

/*! \brief Change the password

    This message notifies credentials providers that a password change
    request has been received.

    A plug-in handling this message that wishes to participate in the
    password change operation is expected to add a
    ::khui_new_creds_by_type to the list of participants in the
    ::khui_new_creds structure by calling khui_cw_add_type().

    The password change operation requires user interaction.  Any
    plug-ins that are participating in the operation need to provide a
    user-interface.

    Message parameters:
    - \b vparam : pointer to a ::khui_new_creds structure

    \see khui_cw_add_type(), ::khui_new_creds, ::khui_new_creds_by_type
 */
#define KMSG_CRED_PASSWORD  16

/*! \brief Initiate the process of obtaining new credentials

    The UI sends this message to start the process of obtaining new
    credentials.  See \ref cred_acq for more information about
    handling this message.

    A plug-in handling this message that wishes to participate in the
    new credentials acquisition operation is expected to add a
    ::khui_new_creds_by_type to hte list of participants in the
    ::khui_new_creds structure by calling khui_cw_add_type().

    Message parameters:
    - \b vparam : pointer to a ::khui_new_creds structure

    \see \ref cred_acq, khui_cw_add_type(), ::khui_new_creds,
    ::khui_new_creds_by_type
 */
#define KMSG_CRED_NEW_CREDS 17

/*! \brief Renew credentials

    This is a notification sent to individual credentials providers
    that a specified identity's credentials should be renewed.

    A plug-in handling this message that wishes to participate in the
    renew credentials operation is expected to add a
    ::khui_new_creds_by_type to the list of participants in the
    ::khui_new_creds structure by calling khui_cw_add_type().

    Message parameters:
    - \b vparam : Pointer to a khui_new_creds object

    \see khui_cw_add_type(), ::khui_new_creds,
    ::khui_new_creds_by_type
 */
#define KMSG_CRED_RENEW_CREDS       18

/*! \brief Dialog setup

    Once ::KMSG_CRED_NEW_CREDS has been responded to by all the
    credential types, the UI creates the dialog windows using the data
    supplied in the ::khui_new_creds_by_type structures and issues
    this message.  Each credentials provider is expected to respond by
    finalizing dialog creation operations.

    Message parameters:
    - \b vparam : pointer to a ::khui_new_creds structure

    \note May be sent to individual credential subscriptions.
 */
#define KMSG_CRED_DIALOG_SETUP      19

/*! \brief Dialog pre-start

    Sent after all the credentials providers have responded to
    ::KMSG_CRED_DIALOG_SETUP and all the initialization has been
    completed.  Credentials providers are expected to respond to this
    message by loading any default data into the dialog controls for
    each credential type.

    Message parameters:
    - \b vparam : pointer to a ::khui_new_creds structure

    \note May be sent to individual credential subscriptions.
 */
#define KMSG_CRED_DIALOG_PRESTART   20

/*! \brief Dialog start

    A notification that the dialog is now in progress.

    Message parameters:
    - \b vparam : pointer to a ::khui_new_creds structure

    \note May be sent to individual credential subscriptions.
 */
#define KMSG_CRED_DIALOG_START      21

/*! \brief The primary identity of the new credentials dialog has changed

    This message is not sent out by the UI, but is reserved here for
    use by individual credentials providers.  The message may be sent
    from the dialog procedure to the plugin.

    Message parameters:
    - \b vparam : pointer to a ::khui_new_creds structure

    \note Be careful when sending this message.  All messages that are
        not sent by the system should not be sent via broadcast.
        Instead, create a subscription using kmq_create_subscription()
        for the individual plugin that you want to send the message
        and use one of the per-subscription message functions to send
        the actual message.
 */
#define KMSG_CRED_DIALOG_NEW_IDENTITY 22

/*! \brief New credentials options have changed.

    This message is not sent out by the UI, but is reserved here for
    use by individual credentials providers.  The message may be sent
    from the dialog procedure to the plugin.

    Message parameters:
    - \b vparam : pointer to a ::khui_new_creds structure

    \note Be careful when sending this message.  All messages that are
        not sent by the system should not be sent via broadcast.
        Instead, create a subscription using kmq_create_subscription()
        for the individual plugin that you want to send the message
        and use one of the per-subscription message functions to send
        the actual message.
 */
#define KMSG_CRED_DIALOG_NEW_OPTIONS  23

/*! \brief Process dialog

    Sent to all the credential providers to look at the contents of
    the given ::khui_new_creds structure and do any required
    processing.

    If the \a result field in the structure is set to
    ::KHUI_NC_RESULT_PROCESS, then new credentials should be
    obtained using the given data.

    Set the \a response field in the structure to indicate how the UI
    should proceed from here.

    Message parameters:
    - \b vparam : pointer to a ::khui_new_creds structure

    \note May be sent to individual credential subscriptions.
 */
#define KMSG_CRED_PROCESS             24

/*! \brief End a credentials acquisition operation

    A notification that the credentials acquisition operation has
    ended.

    Message parameters:
    - \b vparam : pointer to a ::khui_new_creds structure

    \note May be sent to individual credential subscriptions.
 */
#define KMSG_CRED_END                 25

/*! \brief Import credentials from the operating system

    Notification to all credentials providers to import any available
    credentials from the operating system.

    Message parameters:
    - This message does not have any parameters
*/
#define KMSG_CRED_IMPORT              26

/*! \brief Destroy credentials

    Notification that the specified credentials should be destroyed.
    Once this message has completed processing a ::KMSG_CRED_REFRESH
    message will be issued.

    The credentials that should be destroyed are specified by a
    ::khui_action_context structure.  The context that should be used
    is the selection context.  Hence, the credentials that must be
    destroyed are the ones lised in the credential set (\a credset).

    Message parameters:

    - \b upram : Unused. Zero.

    - \b vparam : pointer to a ::khui_action_context structure which
      describes which credentials need to be destroyed.

 */
#define KMSG_CRED_DESTROY_CREDS     32

#if 0
/*! \brief Parse an identity

    \note May be sent to individual credential subscriptions.
 */
#define KMSG_CRED_IDENT_PARSE       65
#endif

/*! \brief A property page is being launced

    Handlers of this message should determine whether or not they
    should participate in the property sheet and if so, add a
    ::khui_property_page structure to the property sheet.

    Message parameters:
    - \b vparam : pointer to a ::khui_property_sheet structure
 */
#define KMSG_CRED_PP_BEGIN          128

/*! \brief A property page is about to be created

    Message parameters:
    - \b vparam : pointer to a ::khui_property_sheet structure

    \note This message is merely a notification that the property
        sheet is being created.  Handlers should not modify the state
        of the property sheet or pages at this time.
 */
#define KMSG_CRED_PP_PRECREATE      129

/*! \brief A property page has finished processing

    Handlers of this message should remove any ::khui_property_page
    structures they added when processing ::KMSG_CRED_PP_BEGIN.

    Message parameters:
    - \b vparam : pointer to a ::khui_property_sheet structure
 */
#define KMSG_CRED_PP_END            130

/*! \brief A property page has been destroyed

    Message parameters:
    - \b vparam : pointer to a ::khui_property_sheet structure

    \note This is a notification that the property sheet processing
        has been completed and that the property sheet data structures
        should be freed.  Any property page data structures should
        have already been freed while processing KMSG_CRED_PP_END.
        The validity of the ::khui_property_sheet structure should not
        be relied upon while processing this message.
 */
#define KMSG_CRED_PP_DESTROY        131

/*! \brief An IP address change occurred

    There are no parameters for this message.  The NetIDMgr
    application handles this message and depending on configuration,
    posts message for the individual credentials providers to either
    obtain new credentials or renew old ones.
 */
#define KMSG_CRED_ADDR_CHANGE        140

/*! \brief Check if a KMSG_CRED subtype is a credentials acquisition message

    Dialog messages are those that deal with the new or initial
    credentials acquisition dialog, from initial announcement to
    dialog completion.

    Currently, the dialog messages are:
    - ::KMSG_CRED_NEW_CREDS
    - ::KMSG_CRED_RENEW_CREDS
    - ::KMSG_CRED_DIALOG_SETUP
    - ::KMSG_CRED_DIALOG_PRESTART
    - ::KMSG_CRED_DIALOG_START
    - ::KMSG_CRED_DIALOG_NEW_IDENTITY
    - ::KMSG_CRED_DIALOG_NEW_OPTIONS
    - ::KMSG_CRED_PROCESS
    - ::KMSG_CRED_END

    All dialog message numbers are allocated in a contigous block.

    Note that while ::KMSG_CRED_PROCESS and ::KMSG_CRED_END are not
    specific to dialogs, they are still included in this predicate
    because they are also part of the dialog message sequence.
 */
#define IS_CRED_ACQ_MSG(msg) ((msg) >= 16 && (msg) <=31)

/*@}*/ /* /KMSG_CRED subtypes */

/*! \defgroup kmq_msg_alert KMSG_ALERT Subtypes
  @{*/

/*! \brief Show an alert

    Message parameters:
    - \b vparam : held pointer to a ::khui_alert object

    \note The ::khui_alert object will be released when the processing
        of this message completes.
 */
#define KMSG_ALERT_SHOW 1

/*! \brief Add an alert to the alert queue

    Message parameters:
    - \b vparam : held pointer to a ::khui_alert object

    \note the ::khui_alert object will be released when the queued
        messages are displayed.
 */
#define KMSG_ALERT_QUEUE 2

/*! \brief Show the next queued alert

    There are no message parameters
 */
#define KMSG_ALERT_SHOW_QUEUED 3

/*! \brief Check if there are any queued messages and, if so, update the statusbar

    There are no message parameters
 */
#define KMSG_ALERT_CHECK_QUEUE 4

/*! \brief Show a modal alert

    Message parameters:
    - \b vparam : held pointer to a ::khui_alert object.

    \note the ::khui_alert object will be released when the queued
        messages are displayed.
 */
#define KMSG_ALERT_SHOW_MODAL 5

/*@}*/

/*! \defgroup kmq_msg_ident KMSG_IDENT Subtypes
  @{*/

/*! \brief Initialize and start the identity provider


    Sent by the KCDB to notify the identity provider that it is now
    the current identity provider.

    Note that unlike regular plugins, an identity provider can be
    loaded and inert (not provide any services).  Also, the user may
    switch between multiple identity providers on the fly.
 */
#define KMSG_IDENT_INIT                 1

/*! \brief Stop the identity provider

    Sent by the KCDB as notificaton that the identity provider is no
    longer the current provider.
 */
#define KMSG_IDENT_EXIT                 2

/*! \brief Check if an identity name is valid

    This message is sent to the identity provider to verify the syntax
    of an identity name.  Note that only the syntax of the name is to
    be verfied and not the actual physical existence of said identity.

    Message parameters:

    - \b vparam : pointer to ::kcdb_ident_name_xfer object.  The
        name to be validated will be in the \a name_src member.  The
        buffer will be NULL terminated with a maximum limit of
        KCDB_IDENT_MAXCCH_NAME characters including the terminating
        NULL, consisting only of characters in KCDB_IDENT_VALID_CHARS
        The \a result member should be set to one of the following
        depending on the result of the validation:

        - KHM_ERROR_SUCCESS : The name was valid
        - KHM_ERROR_INVALID_NAME : The name was invalid
 */
#define KMSG_IDENT_VALIDATE_NAME        3

/*! \brief Check if an identity is valid

    Sent to the identity provider to verify the validity of the given
    identity.  The provider should verify that the identity exists and
    is in a state where it can be actively used.

    Depending on the result of the validation, the flags of the
    identity should be updated.

    Message parameters:
    - \b vparam : Handle to an identity cast as a void pointer.
 */
#define KMSG_IDENT_VALIDATE_IDENTITY    4

/*! \brief Canonicalize identity name

    The identity provider will be given a name, which it should put in
    canonical form, adjusting case and any character replacement or
    doing any relevant expansions if applicable, and place it in the
    supplied buffer.

    Message parameters:

    - \b vparam : Pointer to a ::kcdb_ident_name_xfer structure
          which provides the identity name to canonicalize in the \a
          name_src member, and the buffer to store the canonical name
          in the \a name_dest member.  The \a name_dest buffer is
          guaranteed to be at least KCDB_IDENT_MAXCCH_NAME characters
          in size.

    If the name cannot be canonicalized for some reason, the
    destination buffer should be set to a zero-length string and the
    \a result member of the ::kcdb_ident_name_xfer structure should be
    set to the error code.  If the destination buffer is set to a
    zero-length string and \a result is KHM_ERROR_SUCCESS, then the
    original name provided in \a name_src is assumed to be already in
    canonical form.
 */
#define KMSG_IDENT_CANON_NAME           5

/*! \brief Compare names

    Compare two identity names.  The names that are given aren't
    guaranteed to be in canonical form.  The return value should be
    akin to strcmp().

    Message parameters:

    - \b vparam : A pointer to a ::kcdb_ident_name_xfer structure.
        The \a name_src member points at the first name, and the \a
        name_alt member specifies the second name.  The result of the
        comparison should be place in \a result.
 */
#define KMSG_IDENT_COMPARE_NAME         6

/*! \brief Set the default identity

    Set or unset the default identity.  To set the default identity,
    the \a uparam parameter will be set to a non-zero value and a
    handle to the identity will be specified in \a vparam.  To unset
    the default identity (i.e. not have a default identity), a zero
    value will be specified in \a uparam and no identities will be
    specified in \a vparam.

    When setting a default identity, the identity provider will
    receive this message prior to the ::KCDB_IDENT_FLAG_DEFAULT bit
    being set or reset on any identity.  It should return
    KHM_ERROR_SUCCESS if the requested operation can be performed.
    Returning any other value will abort the operation and will leave
    the default identity unchanged.

    When resetting the default identity, this message should be
    treated only as a notification.

    Message parameters:

    - \a uparam : Is non-zero if an identity is being made default.  If
      this is zero, then identity should be the default.

    - \a vparam : A handle to the identity to be made default if \a
      uparam is non-zero.  NULL otherwise.

    Return value:

    - KHM_ERROR_SUCCESS : The identity should be marked as default
    - Any other value : The identity should not be marked as default

 */
#define KMSG_IDENT_SET_DEFAULT          7

/*! \brief Set an identity as searchable

    Set or reset the searchable bit on an identity.  If the \a uparam
    parameter is non-zero, then the searchable bit is being set.
    Otherwise it is being reset.  The identity provider should return
    KHM_ERROR_SUCCESS in order to indicate that the identity should be
    marked as searchable.  Any other value will result in the
    searchable bit being reset on the identity.

    Message parameters:

    - \a uparam : Is non-zero if the searchable bit is being set.  Zero
      otherwise.

    - \a vparam : Handle to the identity

    Return value:

    - KHM_ERROR_SUCCESS: The identity should be marked as searchable
    - Any other value : The identity should not be marked as default
 */
#define KMSG_IDENT_SET_SEARCHABLE       8

/*! \brief Get information about an identity

 */
#define KMSG_IDENT_GET_INFO             9

/*! \brief Enumerate known and accessible identities
 */
#define KMSG_IDENT_ENUM_KNOWN           10

/*! \brief Update information about an identity
 */
#define KMSG_IDENT_UPDATE               11

/*! \brief Retrieve the user interface callback function

    When obtaining new credentials, the user interface needs to obtain
    a callback function which will provide identity selection
    controls.

    Message parameters:

    - \a uparam : Not used

    - \a vparam : pointer to a ::khui_ident_new_creds_cb which will
         receive the call back.
 */
#define KMSG_IDENT_GET_UI_CALLBACK      12

/*! \brief Notification of the creation of an identity

    This should be considered just a notification.  The identit
    provider does not have an opportunity to veto the creation of an
    identity whose name has been found to be valid.  However, when
    handing this notification, the identity provider can:

    - Change the flags of the identity and/or marking the identity as
      invalid.

    - Change the default identity.

    Note that this notification is sent before the general :;KMSG_KCDB
    notification of the identity creation is sent.

    Message parameters:

    - \a uparam : Not used.

    - \p vparam : handle to the identity
 */
#define KMSG_IDENT_NOTIFY_CREATE        13

/*@}*/ /* /KMSG_IDENT subtypes */

/*@}*/ /* / message types */
/*@}*/ /* / kmq */

#endif