pull up r19620 from trunk

 r19620@cathode-dark-space:  jaltman | 2007-06-22 14:50:26 -0400
 ticket: 5584
 
 Update developer documentation.
 
 These updates reflect changes that were made to the new credentials
 acquisition process and add information to incomplete API
 documentation.
 
 

ticket: 5584

git-svn-id: svn://anonsvn.mit.edu/krb5/branches/krb5-1-6@19778 dc483132-0cff-0310-8789-dd5450dbe970

11 files changed, 777 insertions, 176 deletions

diff --git a/src/windows/identity/doc/cred_aquisition.h b/src/windows/identity/doc/cred_aquisition.h
index bce826d..613d5a0 100644
--- a/src/windows/identity/doc/cred_aquisition.h
+++ b/src/windows/identity/doc/cred_aquisition.h
@@ -82,10 +82,7 @@
       ::khui_new_creds structure. (See khui_cw_add_type()).
 
     - <::KMSG_CRED, ::KMSG_CRED_DIALOG_PRESTART> is sent to all the
-      credentials providers.  Credentials providers should use this
-      message to finialize initialization in preparation of showing
-      the credentials acquisition window, such as by initializing the
-      controls of the individual panels.
+      credentials providers.
 
     - <::KMSG_CRED, ::KMSG_CRED_DIALOG_START> is sent to all the
       credentials providers.
@@ -102,12 +99,21 @@
       <::KMSG_CRED,::KMSG_CRED_DIALOG_PROCESS> message to all the
       credentials providers.  Each provider should check if the user
       cancelled the dialog or indicated that the new credentials
-      should be obtained and act accordingly.  The \a result field of
+      should be obtained and act accordingly.  The \c result field of
       the ::khui_new_creds structure will be set to either
       ::KHUI_NC_RESULT_PROCESS or ::KHUI_NC_RESULT_CANCEL to indicate
       whether the user wishes to acquire credentials or cancel the
       operation.
 
+    - Once all the plug-ins have processed the <::KMSG_CRED,
+      ::KMSG_CRED_DIALOG_PROCESS> message, the application checks
+      whether the new credentials dialog should continue processing,
+      or whether the dialog should be closed.  If the dialog should
+      continue processing, then the dialog returns to the state it was
+      in prior to the ::WMNC_DIALOG_PREPROCESS message was sent.  If
+      the dialog should be closed, then a <::KMSG_CRED,
+      ::KMSG_CRED_END> message is sent.
+
     - A <::KMSG_CRED, ::KMSG_CRED_END> message signals the end of the
       credentials acquisition process.  Each credentials provider is
       responsible for removing the ::khui_new_creds_by_type structre
@@ -117,6 +123,8 @@
 
     \section cred_acq_handle Responding to credential acquisition messages
 
+    \subsection cred_acq_handle_init <::KMSG_CRED,::KMSG_CRED_NEW_CREDS> and <::KMSG_CRED,::KMSG_CRED_RENEW_CREDS> Messages
+
     The credential acquisition messages are
     <::KMSG_CRED,::KMSG_CRED_NEW_CREDS> and <::KMSG_CRED,
     ::KMSG_CRED_RENEW_CREDS>.  They are structured as follows:
@@ -136,7 +144,7 @@
     how the credentials of this type are to be obtained.  The panel is
     described by the ::khui_new_creds_by_type structure.
 
-    \subsection cred_acq_panel_spec Specifying the credentials type panel
+    \subsubsection cred_acq_panel_spec Specifying the credentials type panel
 
     The credentials type panel is used by the user to customize how
     credentials of the specified type are to be obtained.  The
@@ -209,5 +217,109 @@
 
 /*! \page cred_acq_dlgproc Writing the dialog procedure for a cred type panel
 
-    
+    Once each credentials provider has had a chance to add a
+    credentials type panel for the new credentials dialog, the
+    application will attempt to create all the dialog panels.  It will
+    use the dialog template and the dialog procedure specified in the
+    \c dlg_proc and \c dlg_template members of the
+    ::khui_new_creds_by_type structure.
+
+    The credentials type panel will be an ordinary dialog that is
+    created as a child of the new credentials window.  Therefore, the
+    dialog template should have the WS_CHILD style and the
+    WS_EX_CONTROLPARENT extended style set so that the main dialog
+    procedure can correctly navigate the child dialog.
+
+    \section cred_acq_dlgmsg Handling Messages
+
+    \subsection cred_acq_dlg_WM_INITDIALOG WM_INITDIALOG
+
+    When the application creates a credentials type panel dialog, it
+    passes a pointer to the ::khui_new_creds structure as the \c
+    LPARAM parameter.  This can be used to query for the credentials
+    type panel for the plug-in, as follows:
+
+    \code
+
+    // Handler for WM_INITDIALOG:
+    // HWND hwnd, WPARAM wParam and LPARAM lParam
+
+    khui_new_creds *         nc = NULL;
+    khui_new_creds_by_type * nct = NULL;
+
+    // We can define and use a structure like the following to
+    // maintain the data that will be used to drive the dialog user
+    // interface and to store credentials type settings:
+    struct nc_dialog_data *  d = NULL;
+
+    nc = (khui_new_creds *) lParam;
+
+    // Now we can use nc to query for our credentials type structure
+    khui_cw_find_type(nc, credtype_id, &nct);
+
+    assert(nct);
+
+    // The dialog data structure should live until we receive
+    // WM_DESTROY.
+    d = malloc(sizeof(*d));
+    ZeroMemory(d, sizeof(*d));
+
+    d->nc = nc;
+    d->nct = nct;
+
+    // Store it as our user data for the dialog.
+    SetWindowLongPtr(hwnd, DWLP_USER, (LPARAM) d);
+
+    // The aux member of the khui_new_creds_by_type structure is
+    // reserved for use by the credentials provider.  We can use it to
+    // store our dialog data.  This way, the dialog procedure and the
+    // plug-in thread can both access it and use it to store
+    // credential options for use when obtaining credentials.  The
+    // dialog and the dialog data exist until KMSG_CRED_END is sent.
+    nct->aux = (LPARAM) d;
+
+    // We should return FALSE here to indicate that we don't want to
+    // set keyboard focus to this dialog yet.  The application will
+    // attempt to create all the credentials type panels as well as
+    // the other child dialogs used for the new credentials opeartion.
+    return FALSE;
+
+    \endcode
+
+    \subsection cred_acq_dlg_WM_NC_NOTIFY WM_NC_NOTIFY
+
+    ::WM_NC_NOTIFY is a special window message that Network Identity
+    Manager uses to communicate with credentials type panels.  The
+    messages are listed in the ::khui_wm_nc_notifications enumeration.
+    The format of the message is as follows:
+
+    - uMsg : KHUI_WM_NC_NOTIFY
+    - HIWORD(wParam) : one of ::khui_wm_nc_notifications
+    - LPARAM : pointer to the ::khui_new_creds structure (except where noted)
+
+    The ::WM_NC_NOTIFY notifications that a credentials provider is
+    expected to handle are the following:
+
+    - ::WMNC_IDENTITY_CHANGE
+
+    \copydoc WMNC_IDENTITY_CHANGE
+
+    - ::WMNC_DIALOG_MOVE
+
+    \copydoc WMNC_DIALOG_MOVE
+
+    - ::WMNC_UPDATE_CREDTEXT
+
+    \copydoc WMNC_UPDATE_CREDTEXT
+
+    - ::WMNC_CREDTEXT_LINK
+
+    \copydoc WMNC_CREDTEXT_LINK
+
+    - ::WMNC_DIALOG_PREPROCESS
+
+    \copydoc WMNC_DIALOG_PREPROCESS
+
+    \section cred_acq_other Other notes
+
 */
diff --git a/src/windows/identity/doc/cred_main.h b/src/windows/identity/doc/cred_main.h
index 97ac0c2..cbd88bb 100644
--- a/src/windows/identity/doc/cred_main.h
+++ b/src/windows/identity/doc/cred_main.h
@@ -25,12 +25,12 @@
 
 /* $Id$ */
 
-/*! \page cred Credentials Providers 
+/*! \page cred Credentials Providers
 
     \section cred_contents Contents
 
     - \subpage cred_data_types
+    - \subpage cred_msgs
     - \subpage cred_acq
     - \subpage cred_prop_pages
-    - \subpage cred_msgs
 */
diff --git a/src/windows/identity/doc/cred_msgs.h b/src/windows/identity/doc/cred_msgs.h
index 405acef..a60b883 100644
--- a/src/windows/identity/doc/cred_msgs.h
+++ b/src/windows/identity/doc/cred_msgs.h
@@ -31,6 +31,14 @@ A credentials provider plug-in receives a number of messages during the
 course of execution.  This section describes the appropriate ways of
 handling these messages.
 
+  - \ref pi_credmsg_system
+  - \ref pi_credmsg_cred
+    - \ref pi_credmsg_list
+    - \ref pi_credmsg_credacq
+    - \ref pi_credmsg_destroy
+    - \ref pi_credmsg_import
+    - \ref pi_credmsg_prop
+
 \section pi_credmsg_system System mesages
 
 There are only two system messages that a credentials provider needs
@@ -43,6 +51,73 @@ two sections for details on handling these messages.
 
 \section pi_credmsg_cred Credential messages
 
+\subsection pi_credmsg_list Listing Credentials
+
+When the Network Identity Manager application needs to refresh the
+list of credentials that credentials providers are aware of, it sends
+out a <::KMSG_CRED, ::KMSG_CRED_REFRESH> message.
+
+Each credentials provider is expected to populate a credential set
+with the credentials that it is aware of and call
+kcdb_credset_collect() or kcdb_credset_collect_filtered() to merge the
+credentials into the root credentials set.
+
+In addition to responding to <::KMSG_CRED, ::KMSG_CRED_REFRESH>, each
+credentials provider is expected to list and merge their credentials
+during the following events:
+
+- When the plug-in is initialized, during <::KMSG_SYSTEM, ::KMSG_SYSTEM_INIT>
+
+- When the plug-in obtains new credentials during the new credentials
+  acquisition sequence and whenever the plug-in becomes aware of new
+  credentials.
+
+\subsection pi_credmsg_credacq Credential Acquisition Message Sequence
+
+The aquisition of new or renewed credentials is conducted via a
+sequence of messages.  Details of handling this sequence is explained
+in the section \ref cred_acq .
+
+\subsection pi_credmsg_destroy Destroying Credentials
+
+When a request is received to destroy credentials, Network Identity
+Manager sends out a <::KMSG_CRED, ::KMSG_CRED_DESTROY_CRED> message.
+The \c vparam member of the message will point to a
+::khui_action_context structure that describes which credentials are
+being destroyed.  The plug-in is expected to destroy any credentials
+that were provided by the plug-in which are included in the user
+interface context.
+
+\see \ref khui_context_using
+
+\subsection pi_credmsg_import Importing Credentials
+
+The import action is typically used to request that plug-ins import
+any relevant credentials from the Windows LSA cache.  This typically
+only applies to plug-ins that provide Kerberos credentials and is not
+discussed in detail.
+
+\subsection pi_credmsg_prop Property Pages
+
+Credentials providers are also expected to participate in the user
+interface when the user makes a request to view the properties of a
+credential or identity.
+
+  - <::KMSG_CRED, ::KMSG_CRED_PP_BEGIN>
+  - <::KMSG_CRED, ::KMSG_CRED_PP_PRECREATE>
+  - <::KMSG_CRED, ::KMSG_CRED_PP_END>
+  - <::KMSG_CRED, ::KMSG_CRED_PP_DESTROY>
+
+Details about handling this sequence of messages is discussed in \ref
+cred_prop_pages .
+
+\subsection pi_credmsg_addrchange Address Change Notification
 
+When the Network Identity Manager detects that that IP address of the
+machine has changed, it will issue a <::KMSG_CRED,
+::KMSG_CRED_ADDR_CHANGE>.  Handling this notification is optional and
+is only necessary for credentials providers which are affected by IP
+address changes.  This is just a notification and the plug-in is not
+expected to take any special action.
 
 */
diff --git a/src/windows/identity/doc/cred_prop_pages.h b/src/windows/identity/doc/cred_prop_pages.h
index ac82e1c..1942623 100644
--- a/src/windows/identity/doc/cred_prop_pages.h
+++ b/src/windows/identity/doc/cred_prop_pages.h
@@ -46,27 +46,93 @@
      the structure is populated with the property context obtained
      through khui_context_get().
 
+     In addition to the \c ctx member, depending on the scope of the
+     context, other fields of the ::khui_property_sheet structure
+     could also be set:
+
+     - For ::KHUI_SCOPE_IDENT, the \c identity field will be set to
+       the selected identity.
+
+     - For ::KHUI_SCOPE_CREDTYPE, the \c identity field will be set to
+       the selected identity, and the \c credtype field will be set to
+       the selected credential type.
+
+     - For ::KHUI_SCOPE_CRED, in addition to the \c identity and \c
+       credtype fields being set as above, the \c cred field will be
+       set to a handle to the credential.
+
    - A global message is broadcast of type
      <::KMSG_CRED,::KMSG_CRED_PP_BEGIN> with the parameter blob that
      is a pointer to the ::khui_property_sheet structure.
 
-   - Subscribers to <::KMSG_CRED> messages handle the message, check
-     the \a ctx member of the structure and determine whether or not
-     and what type property pages to add to the property sheet.  New
-     property sheets are added by calling khui_ps_add_page().
+     - Subscribers to <::KMSG_CRED> messages handle the message, check
+       the ::khui_property_sheet structure and determine whether or
+       not and what type property pages to add to the property sheet.
+       New property sheets are added by calling khui_ps_add_page().
+
+       The following code shows how this message might be handled.
+
+       \code
+
+       // Message handler code for KMSG_CRED_PP_BEGIN
+
+       khui_property_sheet * ps;
+       PROPSHEETPAGE       * psp;     // from prsht.h
+
+       if (ps->credtype == credtype_id &&
+           ps->cred) {
+
+           // We have been requested to show a property sheet for one of
+           // our credentials.
+
+           // The PROPSHEETPAGE structure has to exist until we remove the
+           // property sheet page when we are handling KMSG_CRED_PP_END.
+
+           psp = malloc(sizeof(*psp));
+           ZeroMemory(p, sizeof(*psp));
+
+           psp->dwSize = sizeof(*psp);
+           psp->dwFlags = 0;
+
+           // hResModule is the handle to the resource module
+           psp->hInstance = hResModule;
+
+           // IDD_PP_CRED is the dialog template for our property page
+           psp->pszTemplate = MAKEINTRESOURCE(IDD_PP_CRED);
+
+           // pp_cred_dlg_proc is the message handler for our property
+           // page.  See the Platform SDK for details.
+           psp->pfnDlgProc = pp_cred_dlg_proc;
 
-   - Once all the pages are added, a
-     <::KMSG_CRED,::KMSG_CRED_PP_PRECREATE> message is broadcast.
-     This is a chance for the property page providers to do any
-     processing before the property page is created.
+           // We can pass the khui_property_sheet structure as the
+           // lParam for the message handler so it knows the scope of
+           // the property sheet.
+           psp->lParam = (LPARAM) ps;
+
+           // Finally, add a property page for our credential type
+           // stored in credtype_id.  Note that only one property page
+           // can be added per credential type.
+
+           khui_ps_add_page(ps, credtype_id, 0, psp, NULL);
+
+           return KHM_ERROR_SUCCESS;
+       }
+
+       \endcode
+
+   - Once all the plug-ins have had a chance to add their property
+     sheets, a <::KMSG_CRED,::KMSG_CRED_PP_PRECREATE> message is
+     broadcast.  This is a chance for the property page providers to
+     do any processing before the property page is created.
 
    - The property sheet is created and made visible with a call to
      khui_ps_show_sheet().
 
-   - The Network Identity Manager message loop takes over.  Further interaction
-     including notifications of 'Ok','Cancel','Apply' and other
-     property sheet related actions are handled through WIN32
-     messages.
+   - The Network Identity Manager message loop takes over.  Further
+     interaction including notifications of 'Ok','Cancel','Apply' and
+     other property sheet related actions are handled through WIN32
+     messages to the window procedure of the property sheet and the
+     message handlers for the individual property pages.
 
    - Once the user closes the property sheet, a
      <::KMSG_CRED,::KMSG_CRED_PP_END> message is sent to all
@@ -74,11 +140,41 @@
      property sheet must free up any associated resources at this
      point.
 
+     Continuing our example from above, the following code could be
+     used to handle this message:
+
+     \code
+
+     // Handler for KMSG_CRED_PP_END
+
+     khui_property_page * p = NULL;
+
+     // If a property sheet was added by us, this call would get
+     // a handle to the property page structure.
+
+     if (KHM_SUCCEEDED(khui_ps_find_page(ps, credtype_id, &p))) {
+
+         // It is safe to assume that the property page window has
+         // been destroyed by the time we receive KMSG_CRED_PP_END.
+         // So we can free the PROPSHEETPAGE structure we allocated
+         // above.
+
+         if (p->p_page)
+             free(p->p_page);
+         p->p_page = NULL;
+
+         // The property page structure we added will automatically
+         // be removed and freed by the application.
+     }
+
+     return KHM_ERROR_SUCCESS;
+     \endcode
+
    - All the ::khui_property_page structures that were allocated as
      well as the ::khui_property_sheet structure are freed up with a
      call to khui_ps_destroy_sheet().
 
-The maximum number of property sheets that can be open at one time is
-currently set to 256.  Each property sheet can have a maximum of 16
-property pages.
+\note The maximum number of property sheets that can be open at one
+time is currently set to 256.  Each property sheet can have a maximum
+of 16 property pages.
  */
diff --git a/src/windows/identity/doc/main_page.h b/src/windows/identity/doc/main_page.h
index 58aece3..7c2e2ab 100644
--- a/src/windows/identity/doc/main_page.h
+++ b/src/windows/identity/doc/main_page.h
@@ -114,6 +114,11 @@
     The Network Identity Manager version number is set as the file and
     product version of <tt>nidmgr32.dll</tt>.
 
+    The API version refers to the version of the API exposed by
+    <tt>nidmgr32.dll</tt>.  A plug-in that was built against a
+    particular API version will be compatible with any version of
+    Network Identity Manager whose API version is the same.
+
     - <b>1.2.0.2</b> Kerberos for Windows 3.2 Beta 2 <em>Apr 11, 2007</em>\n
       API version : <b>8</b>
 
diff --git a/src/windows/identity/doc/plugin_framework.h b/src/windows/identity/doc/plugin_framework.h
index 5f225b8..cfe40e4 100644
--- a/src/windows/identity/doc/plugin_framework.h
+++ b/src/windows/identity/doc/plugin_framework.h
@@ -97,82 +97,140 @@ Next \subpage pi_fw_pm ...
 
 \page pi_fw_pm Module Manager
 
-The module manager is tasked with loading, unloading and managing the
-plug-in message processing. It maintains a separate thread for loading
-and registering modules.  When a module is successfully loaded and it
-registers one or more plug-ins, a new thread is created for each
-plug-in.  Plug-in specific initialization and other callback functions
-are called from within this new thread.  This is to prevent one
-plug-in from "hanging" other plug-ins and the main Network Identity
-Manager user interface threads.
+The Module Manager is tasked with loading and unloading modules as
+well as managing the plug-in message processing.
+
+When a module is successfully loaded, it registers one or more
+plug-ins.  The Module Manager creates a new thread for each of these
+plug-ins.  Then the initialization message to the plug-in is sent and
+the message dispatch loop is started in this new thread.  Having each
+plug-in in a separate thread prevents one plug-in from "hanging" other
+plug-ins and the user interface.
+
+\note For compatibility with future versions of Network Identity
+Manager, a plug-in should not depend on the fact that it is running in
+its own thread.
 
 Read more :
 - \ref pi_structure
 
-\subsection pi_fw_pm_load Load sequence
+\section pi_fw_pm_load Module Load Sequence
 
 When kmm_load_module() is called to load a specific module, the
 following sequence of events occur:
 
-- The registration information for the module is located on the
-  registry key \c
-  \Software\MIT\NetIDMgr\PluginManager\Modules\[ModuleName].
+<ul>
 
-- The \c ImagePath value from the registration information is used to
+ <li>
+  The registration information for the module is located on the
+  registry key \c
+  \\Software\\MIT\\NetIDMgr\\PluginManager\\Modules\\[ModuleName]. \see
+  \ref config
+ </li>
+
+ <li> The module will not be loaded if one of the following conditions are
+  true:
+
+  <ul>
+   <li>
+    The \c Disabled value is defined and non-zero.
+   </li>
+
+   <li>
+    The \c FailureCount value is defined and exceeds the maximum
+    failure count.  By default, the maximum failure count is three,
+    although it can be set by adding the registry value \c
+    ModuleMaxFailureCount in registry key \c
+    Software\\MIT\\NetIDMgr\\PluginManager\\Modules .
+   </li>
+  </ul>
+ </li>
+
+ <li>
+  The \c ImagePath value from the registration information is used to
   locate the module binary.  If it is not an absolute path, then the
   binary is located using the standard system search path starting
   from the directory in which Network Identity Manager binaries are
   located.
+ </li>
 
-- The binary is loaded into the address space of Network Identity
+ <li>
+  The binary is loaded into the address space of Network Identity
   Manager along with any dependencies not already loaded.
+ </li>
 
-- If the Network Identity Manager core binary is signed, then the
+ <li>
+  If the Network Identity Manager core binary is signed, then the
   signature is checked against the system and user certificate stores.
   If this fails, the module is unloaded. See \ref pi_fw_pm_unload.
+ </li>
 
-- The init_module() entry point for the loaded module is called.  If
+ <li>
+  The init_module() entry point for the loaded module is called.  If
   this function returns an error or if no plug-ins are registered,
   then the module is immediately unloaded. See \ref pi_fw_pm_unload.
 
-- During processing of init_module(), if any localized resource
-  libraries are specified using kmm_set_locale_info(), then one of the
-  localized libraries will be loaded. See \ref pi_localization
-
-- During processing of init_module(), the module registers all the
-  plug-ins that it is implementing by calling kmm_register_plugin() for
-  each.
-
-- Once init_module() returns, each plug-in is initialized.  The method
+  <ul>
+   <li>
+    During processing of init_module(), if any localized resource
+    libraries are specified using kmm_set_locale_info(), then one of the
+    localized libraries will be loaded. See \ref pi_localization
+   </li>
+
+   <li> 
+    During processing of init_module(), the module registers all the
+    plug-ins that it is implementing by calling kmm_provide_plugin()
+    for each.
+   </li>
+  </ul>
+ </li>
+
+ <li>
+  Once init_module() returns, each plug-in is initialized.  The method
   by which a plug-in is initialized depends on the plug-in type.  The
   initialization code for the plug-in may indicate that it didn't
   initialize properly, in which case the plug-in is immediately
   unregistered.  No further calls are made to the plug-in.
+ </li>
 
-- If no plug-in is successfully loaded, the module is unloaded. See
+ <li>
+  If no plug-in is successfully loaded, the module is unloaded. See
   \ref pi_fw_pm_unload.
+ </li>
+</ul>
 
-- During normal operation, any registered plug-ins for a module can be
+  During normal operation, any registered plug-ins for a module can be
   unloaded explicitly, or the plug-in itself may signal that it should
   be unloaded.  If at anytime, all the plug-ins for the module are
   unloaded, then the module itself is also unloaded unless the \c
   NoUnload registry value is set in the module key.
 
-\subsection pi_fw_pm_unload Unload sequence
+\section pi_fw_pm_unload Unload sequence
 
-- For each of the plug-ins that are registered for a module, the exit
+<ul>
+ <li>
+  For each of the plug-ins that are registered for a module, the exit
   code is invoked.  The method by which this happens depends on the
   plug-in type.  The plug-in is not given a chance to veto the
   decision to unload. Each plug-in is responsible for performing
   cleanup tasks, freeing resources and unsubscribing from any message
   classes that it has subscribed to.
+ </li>
 
-- The exit_module() entry point is called for the module.
+ <li>
+  Once all the plug-ins have been unloaded, the exit_module() entry
+  point is called for the module.
+ </li>
 
-- If any localized resource libraries were loaded for the module, they
+ <li>
+  If any localized resource libraries were loaded for the module, they
   are unloaded.
+ </li>
 
-- The module is unloaded.
+ <li>
+  The module is unloaded.
+ </li>
+</ul>
 
 The following diagram illustrates the relationship between modules and
 plug-ins as implemented in the Kerberos 5 plug-in distributed with
diff --git a/src/windows/identity/doc/stylesheet.css b/src/windows/identity/doc/stylesheet.css
index ddc3d1f..d5af4e9 100644
--- a/src/windows/identity/doc/stylesheet.css
+++ b/src/windows/identity/doc/stylesheet.css
@@ -6,14 +6,28 @@ BODY,TD {
 }

 H1 {

 	text-align: center;

-       font-size: 160%;

+        font-size: 160%;

+        border-bottom: 1px solid #88b7c8;

+        margin-bottom: 1em;

+        padding-top: 0.5em;

+        padding-bottom: 0.5em;

+        background-color: #e8eef2;

 }

 H2 {

-       font-size: 120%;

+        margin-top: 1em;

+        font-size: 120%;

+        padding: 0.5em;

+        background-color: #f0f0f0;

+        border-bottom: 1px solid #888888;

 }

 H3 {

        font-size: 100%;

 }

+

+H4 {

+       font-size: 100%;

+}

+

 CAPTION { font-weight: bold }

 DIV.qindex {

 	width: 100%;

@@ -357,3 +371,17 @@ HR { height: 1px;
 .directory p { margin: 0px; white-space: nowrap; }

 .directory div { display: none; margin: 0px; }

 .directory img { vertical-align: -30%; }

+

+DL.note {

+  background-color: #eeeeee;

+  width: 100%;

+  border-width: 1px;

+  border-style: solid;

+  border-color: #bbbbbb;

+  -moz-border-radius: 4px 4px 4px 4px;

+}

+

+DL.note DT {

+  font-size: 75%;

+}

+

diff --git a/src/windows/identity/help/html/nidmgr.css b/src/windows/identity/help/html/nidmgr.css
index 9ace122..99a50d1 100644
--- a/src/windows/identity/help/html/nidmgr.css
+++ b/src/windows/identity/help/html/nidmgr.css
@@ -1,72 +1,122 @@
-BODY {

-   font-family:helvetica,sans-serif;

-   font-size:8pt; 

-   font-style:normal; 

-   background-color:white;

-   margin-top: 0;

-   margin-left: 0;

-   margin-right: 0;

-   }

-

-H1 {

-   font-size: 10pt;

-   border-bottom:1px solid black;

-   padding:5px;

-   background-color:#eeeeee;

-   }

-

-H2 {

-   }

-

-H3 {

-   font-size: 9pt;

-   border-bottom: 1px solid lightgrey;

-   padding: 5px;

-   }

-

-H4 {

-   font-size: 9pt;

-   font-style: italic;

-   border-bottom: 1px dashed lightgrey;

-   margin-left: 10px;

-   }

-

-P  {

-   margin-left: 5px;

-   margin-right: 5px;

-   }

-

-P.caption {

-   margin-left: 5px;

-   margin-right: 5px;

-   font-style: italic;

-}

-

-DIV.inline {

-   float: left;

-}

-

-DIV.sidebar {

-   float: right;

-   background-color:#ffffb9;

-   border: 1px solid #ffff00;

-}

-

-A.external {

-}

-

-A.mail {

-}

-

-IMG {

-   border: 0;

-}

-

-SPAN.pre {

-   font-family: courier;

-}

-

-SPAN.title {

-   font-weight: bold;

-}

+  body {

+    font-family: helvetica,sans-serif;

+    font-size: 9pt;

+    font-style: normal;

+    background-color: white;

+    margin-top: 0pt;

+    margin-left: 0pt;

+    margin-right: 0pt;

+    }

+

+  h1 { border-bottom: 1px solid black;

+    padding: 1em;

+    font-size: 12pt;

+    background-color: rgb(247, 247, 247);

+    }

+

+  h2 {  }

+

+  h3 { border-bottom: 1px solid lightgrey;

+    padding: 1em;

+    font-size: 11pt;

+    }

+

+  h4 { border-bottom: 1px dashed lightgrey;

+    font-size: 10pt;

+    font-style: italic;

+    margin-left: 2em;

+    }

+

+  p { margin-left: 1em;

+    margin-right: 1em;

+    }

+

+  p.caption { margin-left: 1em;

+    margin-right: 1em;

+    font-style: italic;

+    }

+

+  div.inline { float: left;

+    }

+

+  div.sidebar { border: 1px solid rgb(255, 255, 0);

+    float: right;

+    background-color: rgb(255, 255, 185);

+    }

+

+  a.external {  }

+

+  a.mail {  }

+

+  img { border: 0pt none ;

+    }

+

+  span.pre { font-family: monospace;

+    }

+

+  span.title { font-weight: bold;

+    }

+

+  div.schema-space { border-left: 1px solid rgb(230, 206, 142);

+    padding: 0pt;

+    margin-left: 1em;

+    margin-top: 0.5em;

+    margin-bottom: 0.5em;

+    }

+

+  div.schema-templ { border-left: 1px solid rgb(98, 161, 143);

+    background-color: rgb(208, 242, 233);

+    }

+

+  div.schema-space-doc { margin: 1em 3em;

+    }

+

+  p.schema-space { border-top: 1px solid rgb(230, 206, 142);

+    margin: 0pt;

+    padding: 1em;

+    font-weight: bold;

+    font-size: 10pt;

+    background-color: rgb(242, 233, 208);

+    }

+

+  p.schema-reg { margin: 0pt;

+    padding-top: 0.4em;

+    padding-bottom: 0.4em;

+    background-color: rgb(247, 247, 247);

+    }

+

+  span.schema-label { display: block;

+    float: left;

+    margin-left: 2em;

+    width: 10em;

+    }

+

+  span.schema-value { width: 100%;

+    background-color: rgb(255, 255, 255);

+    padding-top: 0.3em;

+    padding-bottom: 0.3em;

+    }

+

+  div.schema-value { border: 1px solid rgb(153, 171, 94);

+    background-color: rgb(234, 242, 208);

+    margin-left: 1em;

+    margin-right: 1em;

+    margin-bottom: 1em;

+    }

+

+  p.schema-value-name { margin: 0.5em 1em;

+    padding: 0.5em 1em;

+    }

+

+  span.schema-value-name { font-size: 10pt;

+    font-weight: bold;

+    }

+

+  p.schema-value-type {  }

+

+  p.schema-value-def {  }

+

+  div.schema-value-doc { padding: 1em;

+    }

+

 

diff --git a/src/windows/identity/kherr/kherr.h b/src/windows/identity/kherr/kherr.h
index fff3d50..50e8764 100644
--- a/src/windows/identity/kherr/kherr.h
+++ b/src/windows/identity/kherr/kherr.h
@@ -911,10 +911,39 @@ KHMEXP void KHMAPI kherr_set_progress(khm_ui_4 num, khm_ui_4 denom);
 #define _progress(num,denom) kherr_set_progress((num),(denom))
 
 /*! \brief Get the progress meter of the current error context
+
+    This is equivalent to calling kherr_get_progress_i() for the
+    current error context.  I.e. :
+
+    \code
+    kherr_context * ctx;
+
+    ctx = kherr_peek_context();
+    kherr_get_progress_i(ctx, &num, &denom);
+    kherr_release_context(ctx);
+    \endcode
+
+    \see kherr_get_progress_i()
  */
 KHMEXP void KHMAPI kherr_get_progress(khm_ui_4 * num, khm_ui_4 * denom);
 
 /*! \brief Get the progress meter of an error context
+
+    The progress meter for the current context can be set by calling
+    kherr_set_progress() (or using the ::_progress macro).  The
+    progress value returned by this function is as follows:
+
+    If one or more of the following conditions are true, then the
+    returned progress values are the values set for the context using
+    the most recent call to kherr_set_progress():
+
+    - if the numerator and the denominator are non-zero
+
+    - if the ::KHERR_CF_OWN_PROGRESS flag is set for the context.
+
+    Otherwise, the function will calculate the progress by enumerating
+    all the child context for the context and summing up the
+    normalized numerators and the denominators for them.
  */
 KHMEXP void KHMAPI kherr_get_progress_i(kherr_context * c, khm_ui_4 * num, khm_ui_4 * denom);
 
diff --git a/src/windows/identity/kmq/kmq.h b/src/windows/identity/kmq/kmq.h
index d1a3db3..7ea9450 100644
--- a/src/windows/identity/kmq/kmq.h
+++ b/src/windows/identity/kmq/kmq.h
@@ -27,7 +27,14 @@
 #ifndef __KHIMAIRA_KMQ_H__
 #define __KHIMAIRA_KMQ_H__
 
-/*! \defgroup kmq NetIDMgr Message Queue */
+/*! \defgroup kmq NetIDMgr Message Queue 
+
+    The Network Identity Manager Message Queue handles all the
+    messaging within the application and all loaded plug-ins.
+
+    For information about the messaging system and how it is used,
+    please see \ref pi_fw_pnm_msg .
+*/
 /*@{*/
 
 #include<khdefs.h>
diff --git a/src/windows/identity/uilib/khnewcred.h b/src/windows/identity/uilib/khnewcred.h
index c3ef5da..6349fc7 100644
--- a/src/windows/identity/uilib/khnewcred.h
+++ b/src/windows/identity/uilib/khnewcred.h
@@ -47,7 +47,7 @@
     The format of the message is :
     - uMsg : KHUI_WM_NC_NOTIFY
     - HIWORD(wParam) : one of ::khui_wm_nc_notifications
-    - LPARAM : pointer to the ::khui_new_creds structure
+    - LPARAM : pointer to the ::khui_new_creds structure (except where noted)
 */
 #define KHUI_WM_NC_NOTIFY (WM_APP + 0x101)
 
@@ -64,80 +64,221 @@
 /*! \brief Credentials dialog notifications
 
     These notifications will be sent to the individual dialog
-    procedures of the credential type panels as a ::KHUI_WM_NC_NOTIFY
-    message.
+    procedures of the credential type panels or to the new credentials
+    window as a ::KHUI_WM_NC_NOTIFY message.
 */
 enum khui_wm_nc_notifications {
     WMNC_DIALOG_EXPAND = 1, 
     /*!< The dialog is switching from basic to advanced mode or vice
       versa.
 
-      This message is sent to the new creds dialog to set the dialog
-      to expanded mode.  In expanded mode, all credentials type panels
-      are visible as opposed to the compressed mode where they are not
-      visible.  The message is not sent to credentials type panels.*/
+      In expanded mode, all credentials type panels are visible as
+      opposed to the compressed mode where they are not visible.  The
+      message is not sent to credentials type panels.
 
-    WMNC_DIALOG_SETUP,      
-    /*!< Sent by NetIDMgr to the new creds window to notify it that
-      the dialog should create all the type configuration panels.
+      Only sent to the new credentials window.
+    */
+
+    WMNC_DIALOG_SETUP,
+    /*!< Sent to the new creds window to notify it that the dialog
+      should create all the type configuration panels.
         
       Until this message is issued, none of the credentials type
       panels exist.  The credentials type panels will receive
-      WM_INITDIALOG etc as per the normal dialog creation process. */
+      WM_INITDIALOG etc as per the normal dialog creation process.
+
+      Only sent to the new credentials window.
+    */
+
+    WMNC_DIALOG_ACTIVATE,
+    /*!< Sent to the new creds window to notify it that the dialog
+      should do final initialization work and activate.
+
+      Only sent to the new credentials window.
+    */
 
-    WMNC_DIALOG_ACTIVATE,   
-    /*!< Sent by NetIDMgr to the new creds window to notify it that
-      the dialog should do final initialization work and activate. */
+    WMNC_DIALOG_MOVE,
+    /*!< The new credentials window has moved.
 
-    WMNC_DIALOG_MOVE,       
-    /*!< Sent by the new creds widnow to all the panels notifying them
-      that the NC window is moving. */
+      This message is sent to all the credentials type panels when the
+      new credentials window is being moved.  It will be sent
+      continuously if the user is dragging the window.  Plug-ins
+      rarely need to know their position on the screen.  However, if
+      there are any other windows that were created by the plug-in,
+      such as floating controls or tooltips, they may need to be
+      repositioned in response to this message.
 
-    WMNC_DIALOG_SWITCH_PANEL, 
+      Sent to all the credentials type panels.
+     */
+
+    WMNC_DIALOG_SWITCH_PANEL,
     /*!< Sent to the new creds window to cause it to switch to the
       panel identified by LOWORD(wParam).
 
       Does nothing if the specified panel is already the current
       panel.  If the dialog is in compact mode and making the
       specified panel visible requires switching to expanded mode, the
-      dialog will do so. */
+      dialog will do so.
+
+      Only sent to the new credentials window.
+    */
+
+    WMNC_UPDATE_CREDTEXT,
+    /*!< Update the credentials text associated with a panel.
+
+      During the new credentials operation, each plug-in is expected
+      to maintain a textual representation of the credentials that the
+      plug-in expects to obtain for the selected identity.  It can,
+      alternatively, be used to indicate the state of the credentials
+      type in respect to the selected identity (for example, whether
+      the credentials type is disabled for the identity and why).
+
+      This text is not visible when the new credentials window is in
+      basic mode, but it is visible when the window is in advanced
+      mode.  The following image shows the expanded new credentials
+      window including the credentials text from a several plug-ins:
+
+      \image html new_creds_expanded.png
+
+      Once this message is received, each plug-in should construct its
+      credentials text string and store it in the \c credtext member
+      of its ::khui_new_creds_by_type structure as shown in the sample
+      code below:
+
+      \code
+      // Handler for window message WM_NC_NOTIFY with
+      // HWND hwnd, WPARAM wParam and LPARAM lParam
+
+      // This structure holds the dialog data for the panel.  We
+      // assume it has 'nc' and 'nct' fields that point to the
+      // khui_new_creds and khui_new_creds_by_type structures
+      // respectively.
+
+      ...
+      struct nc_dialog_data * d;
+      ...
+
+      // Retrieve the data structure from the dialog user data.
+      d = (struct nc_dialog_data *) GetWindowLongPtr(hwnd, DWLP_USER);
+
+      switch (HIWORD(wParam)) {
+      case WMNC_UPDATE_CREDTEXT:
+        {
+          wchar_t buffer[KHUI_MAXCCH_LONG_DESC];
+          size_t cb_size;
+
+          // we are being requested to update the credentials text. We
+          // already allocated a buffer when we created the nct
+          // structure.  So we can just set the text here.
+
+          // The credentials text should reflect the credentials that
+          // will be obtained when the new credentials operation
+          // completes.
+
+          assert(d && d->nc && d->nct);
+
+          if (d->nct->credtext) {
+              free(d->nct->credtext);
+              d->nct->credtext = NULL;
+          }
+
+          // We only display something if there is a selected identity
+          if (d->nc->n_identities > 0) {
+            StringCbPrintf(buffer, sizeof(buffer),
+                           L"<p>My Credentials<tab>: %s</p>",
+                           get_credential_name(d));
+            StringCbLength(buffer, sizeof(buffer), &cb_size);
+            cb_size += sizeof(wchar_t); // account for the terminating NULL
+
+            d->nct->credtext = malloc(cb_size);
+            if (d->nct->credtext) {
+               StringCbCopy(d->nct->credtext, cb_size, buffer);
+            }
+          }
+
+          break;
+        }
+
+      ... // Handler other notifications
+      }
+      \endcode
+
+      The text that is specified as the credentials text is formatted
+      hypertext.  For more information about support for formatting
+      and hypertext and handling hyperlinks, see \ref khui_htwnd.
+
+      \note When this message is sent to the new credentials window,
+      the application will send the ::WMNC_UPDATE_CREDTEXT message to
+      all the credential type panels and update the credential text
+      window. */
+
+    WMNC_CREDTEXT_LINK,
+    /*!< A hyperlink was activated.
+
+      Sent to a panel dialog procedure when a user clicks an embedded
+      link in the credentials text that belongs to that panel.  The \a
+      lParam parameter of the message is a pointer to a
+      ::khui_htwnd_link structure describing the link.
 
-    WMNC_UPDATE_CREDTEXT,   
-    /*!< Sent to all the credential type panels for a credentials
-      window to request them to update the credential text.
+      \see \ref khui_htwnd
+
+      \note The \a lParam parameter does not point to a
+      ::khui_new_creds structure for this message.
+    */
+
+    WMNC_IDENTITY_CHANGE,
+    /*!< The primary identity has changed.
+
+      The ::khui_new_creds structure contains a list of identities to
+      which the current operation should be applied.  In its current
+      implementation, only the first identity in this list is used.
+      Therefore, the list will contain at most one identity.  It is
+      possible for the list to be empty (for example, if the user
+      hasn't selected an identity yet).
 
-      When sent to the new credentials window, causes it to send the
-      WMNC_UPDATE_CREDTEXT message to all the credential type panels
-      and update the cred text window.*/
+      When handling this notification, the plug-in should check the \c
+      n_identities member of the ::khui_new_creds structure to see
+      whether there are any identities selected.  This value would be
+      either zero or one.  If it is non-zero, then a handle to the
+      selected identity will be in \c khui_new_creds::identities[0].
+
+      Plug-ins typically use this notfication to load identity
+      specific settings when a new identity is selected.
 
-    WMNC_CREDTEXT_LINK,    
-    /*!< Sent to a panel dialog proc when a user clicks a credtext
-      embedded link that belongs to that panel.  The \a lParam
-      parameter of the message is a pointer to a ::khui_htwnd_link
-      structure describing the link. */
+      This notification is sent to all the credentials type panels.
+     */
 
-    WMNC_IDENTITY_CHANGE,   
-    /*!< The primary identity has changed */
+    WMNC_CLEAR_PROMPTS,
+    /*!< Sent to the new creds window to clear any custom prompts.
+
+      Only sent to the new credentials window.
+     */
 
-    WMNC_CLEAR_PROMPTS,     
-    /*!< Sent to the new creds window to clear any custom prompts */
+    WMNC_SET_PROMPTS,
+    /*!< Sent to the new creds window to set custom prompts.
 
-    WMNC_SET_PROMPTS,       
-    /*!< Sent to the new creds window to set custom prompts */
+      Only sent to the new credentials window. */
     
-    WMNC_DIALOG_PREPROCESS, 
-    /*!< Sent to all the credentials type panels to notify them that
-      the dialog is about to be processed */
-
-    WMNC_DIALOG_PROCESS,    
-    /*!< Process the dialog and signal whether to exit the dialog or
-      not */
-
-    WMNC_DIALOG_PROCESS_COMPLETE, 
+    WMNC_DIALOG_PREPROCESS,
+    /*!< The credentials acquisition process is about to start.
+
+      Sent to all the credentials type panels to notify them that the
+      credentials acquisition process will start.  Once all plug-ins
+      have handled the notification, the application will start
+      sending out <::KMSG_CRED, ::KMSG_CRED_PROCESS> messages to the
+      credentials providers which are participating in the new
+      credentials operation.
+    */
+
+    WMNC_DIALOG_PROCESS,
+    /*!< This notification is no longer used. */
+#pragma deprecated(WMNC_DIALOG_PROCESS)
+
+    WMNC_DIALOG_PROCESS_COMPLETE,
     /*!< Sent to the new creds window to indicate that the all the
       threads have completed processing.*/
 
-    WMNC_TYPE_STATE,        
+    WMNC_TYPE_STATE,
     /*!< Sent to the new creds window as notification that a
       particular credentials type has changed state from enabled to
       disabled or vice versa.  The LPARAM member of the message