pull up r19490 from trunk

 r19490@cathode-dark-space:  jaltman | 2007-04-18 17:45:22 -0400
 ticket: new
 subject: More NIM Developer documentation updates
 
 Revisions to the plug-in architecture documentation.
 
 Adds a graphic showing the plug-in architecture
 
 Defines "ALIASES" in the Makefile so that the current
 NIM API Version number will be used within the docs
 at build time.
 
 

ticket: 5535
version_fixed: 1.6.1

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

5 files changed, 124 insertions, 80 deletions

diff --git a/src/windows/identity/doc/Makefile b/src/windows/identity/doc/Makefile
index 39b20a5..89380af 100644
--- a/src/windows/identity/doc/Makefile
+++ b/src/windows/identity/doc/Makefile
@@ -1,5 +1,6 @@
 #

 # Copyright (c) 2004 Massachusetts Institute of Technology

+# Copyright (c) 2007 Secure Endpoints Inc.

 #

 # Permission is hereby granted, free of charge, to any person

 # obtaining a copy of this software and associated documentation files

@@ -53,6 +54,8 @@ INPUT += "$(SRC)\kmm"
 INPUT += "$(SRC)\kherr"

 !ifdef BUILD_AFS

 INPUT += "$(SRC)\plugins\afs"

+

+ALIASES =  "apiversion=$(NETIDMGR_VERSION_API)"

 !endif

 

 IMAGE_PATH = "$(SRC)\doc\images"

diff --git a/src/windows/identity/doc/images/modules_plugins_krb5.png b/src/windows/identity/doc/images/modules_plugins_krb5.png
new file mode 100644
index 0000000..127e89e
--- /dev/null
+++ b/src/windows/identity/doc/images/modules_plugins_krb5.png
diff --git a/src/windows/identity/doc/plugin_framework.h b/src/windows/identity/doc/plugin_framework.h
index 39d6ac1..a10af2a 100644
--- a/src/windows/identity/doc/plugin_framework.h
+++ b/src/windows/identity/doc/plugin_framework.h
@@ -28,75 +28,119 @@
 /*!

 \page pi_framework Plug-in Framework

 

-\section pi_fw_pnm Plug-ins and Modules

+\section pi_fw_pnm Introduction to Plug-ins, Modules and Messages

 

 \subsection pi_fw_pnm_p Plug-ins

 

-A Network Identity Manager plug-in is a package that implements a defined API that will

-perform credentials management or related tasks on behalf of Network Identity Manager.

-The core Network Identity Manager codebase does not interact directly with Kerberos v5 or

-AFS or any other external entity directly.  Instead, plug-ins are used.

+A plug-in is a package that implements a defined API that will perform

+credentials management or related tasks on behalf of Network Identity

+Manager.

 

-Each plug-in has a name.  The name should be unique among the loaded

-plug-ins, or the plug-in will fail to load.

+The Network Identity Manager architecture is message based.  The core

+of each plug-in is a message handler.  The plug-in integrates with the

+application by subscribing to, and handling specific types of

+messages.

 

-The method in which Network Identity Manager communicates with a plug-in depends on the

-plug-in type.  For more information on each plug-in type, please refer

-to \ref pi_pt.

-

-Most plug-in types rely on a message processor for communication.

-During plug-in registration, the module specifies the message processor

-for the plug-in, which acts as the only point of contact between the

-Network Identity Manager core and the plug-in.  Some other plug-ins require exporting

-specific functions.

+The plug-in message handler runs in its own thread and receive

+asynchronous messages.  There are exceptions, such as when one plug-in

+requires another plug-in to handle a specific message before it can

+handle the message.  In addition, during certain operations that

+require user interaction, each plug-in can delegate code that will run

+in the main application thread (the user interface thread) to process

+window messages.

 

 \subsection pi_fw_pnw_m Modules

 

 One or more plug-ins can be bundled together into a module.  A module

-is a dynamically loadable library which exports a specific

-set of callbacks.  Currently, the only two required callbacks for a

-module are :

+is a dynamically loadable library which exports a specific set of

+callbacks.  Currently, the only two required callbacks for a module

+are :

 

 - init_module(), and

 - exit_module()

 

-\section pi_fw_pm Plug-in/Module Manager

+For more information about how a module is structured, see \ref

+pi_structure .

+

+\subsection pi_fw_pnm_msg Messages and Message Queues

+

+An integral part of this framework is the messaging system.  Most of

+the communication between the Network Identity Manager application and

+plug-ins is conducted through passing messages.

+

+A message has a type and subtype and is denoted in this documentation

+as \< \e message_type, \e message_subtype\>.  For example, when a

+plug-in is loaded, the first message it receives is \< ::KMSG_SYSTEM,

+::KMSG_SYSTEM_INIT \>.

+

+Each thread in the application, specially threads that were created

+for individual plug-in messages handlers, has an associated message

+queue that stores and manages all the messages that have been sent to

+subscribers in that thread.

+

+The most common recipient of a message is a message callback function

+(see ::kmq_callback_t ). The message handler for a plug-in is one such

+example. A message callback function receives the message type,

+subtype and two optional parameters for the message.

+

+Any acceptable recipient can subscribe to broadcast messages of any

+type.  Once subscribed, whenever a message of that type is broadcast,

+the message will get queued on the corresponding message queue.  Then,

+one of the dispatch functions can dispatch the message to the correct

+callback function. (see ::kmq_dispatch).

+

+Next \subpage pi_fw_pm ...

 

-The plug-in manager maintains a separate thread for loading and

-registering modules.  When a module is successfully loaded and it

+*/

+

+/*!

+

+\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.

+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.

 

 Read more :

 - \ref pi_structure

 

 \subsection pi_fw_pm_load Load sequence

 

-When kmm_load_module() is called, the following sequence of events

-occur:

+When kmm_load_module() is called to load a specific module, the

+following sequence of events occur:

 

-- The standard system search path is used to locate the binary.

+- The registration information for the module is located on the

+  registry key \c

+  \Software\MIT\NetIDMgr\PluginManager\Modules\[ModuleName].

 

-- The binary is loaded into the address space of Network Identity Manager along with

-  any dependencies not already loaded.

+- 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.

 

-- 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.

+- The binary is loaded into the address space of Network Identity

+  Manager along with any dependencies not already loaded.

 

-- init_module() for the loaded module is called.  If this function

-  returns an error or if no plug-ins are registered, then the module is

-  unloaded. See \ref pi_fw_pm_unload.

+- 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.

+

+- 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_plug-in() for

+  plug-ins that it is implementing by calling kmm_register_plugin() for

   each.

 

 - Once init_module() returns, each plug-in is initialized.  The method

@@ -111,23 +155,29 @@ occur:
 - 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 NoUnload

-  registry value is set in the module key.

+  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

 

 - 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 object to 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.

 

-- exit_module() is called for the module.

+- The exit_module() entry point is called for the module.

 

 - If any localized resource libraries were loaded for the module, they

   are unloaded.

 

 - The module is unloaded.

 

+The following diagram illustrates the relationship between modules and

+plug-ins as implemented in the Kerberos 5 plug-in distributed with

+Network Identity Manager.

+

+\image html modules_plugins_krb5.png

+

  */

diff --git a/src/windows/identity/doc/plugin_main.h b/src/windows/identity/doc/plugin_main.h
index feb4a25..70040b2 100644
--- a/src/windows/identity/doc/plugin_main.h
+++ b/src/windows/identity/doc/plugin_main.h
@@ -29,38 +29,42 @@
 

 \page plug-ins Network Identity Manager Modules and Plug-ins

 

-Plug-ins and localization are handled by the Network Identity Manager Module Manager

-API.  Each plug-in consists of a dynamically loadable library and zero

-or more associated resource libraries.

+  The Network Identity Manager application does not include any

+  ability to manage any specific type of credential.  Instead it

+  exposes a framework on which plug-ins can be implemented to manage

+  credentials.

 

-For more information about Network Identity Manager Plug-ins, see the following

-sections:

+  Plug-ins and localization are handled by the Network Identity

+  Manager Module Manager API.

 

-- \subpage pi_framework

-- \subpage pi_pt

-- \subpage pi_structure

-- \subpage pi_localization

+  The following sections describe plug-ins in detail:

+

+  - \subpage pi_framework

+  - \subpage pi_pt

+  - \subpage pi_structure

+  - \subpage pi_localization

 */

 

 /*! \page pi_pt Plug-in Types

 

-The types of plug-ins that are currently supported by Network Identity Manager are :

+The types of plug-ins that are currently supported by Network Identity

+Manager are :

 

 \section pi_pt_cred Credential Provider

 

 A credential provider plug-in essentially acts as an interface between

-Network Identity Manager and some entity which defines the credentials for the purpose

-of managing those credentials.

+Network Identity Manager and some entity which defines the credentials

+for the purpose of managing those credentials.

 

 There can be more than one credential provider in a module.

 

 \subsection pi_pt_cred_comm Communication

 

-Communication between Network Identity Manager and a credential provider occurs

-through a message processor.  When registering a credential provider,

-the module initialization code in init_module() specifies

-::KHM_PITYPE_CRED as the \a type member and sets \a msg_proc member to

-a valid message processor in the ::khm_plug-in record.

+Communication between Network Identity Manager and a credential

+provider occurs through a message processor.  When registering a

+credential provider, the module initialization code in init_module()

+specifies ::KHM_PITYPE_CRED as the \a type member and sets \a msg_proc

+member to a valid message processor in the ::khm_plugin record.

 

 \subsection pi_pt_cred_init Initialization

 

@@ -72,8 +76,8 @@ guaranteed to be the first message it receives.
 

 The callback function should return KHM_ERROR_SUCCESS if it

 initializes properly or some other value otherwise.  If the return

-value signals an error, then the plug-in is assume to not be loaded and

-immediately unregistered.

+value signals an error, then the plug-in is assumed to have failed

+initialization and is immediately unloaded.

 

 The message processor is automatically subscribed to the following

 message types:

@@ -86,7 +90,6 @@ obtain new credentials.  This is because other plug-ins that may depend
 on the new credential messages may not be loaded at this time. See the

 section on \ref cred_msgs for more information.

 

-

 \subsection pi_pt_cred_exit Uninitialization

 

 When the plug-in is to be removed, the module manager sends a

@@ -107,22 +110,6 @@ unsubscribed from as they are automatically removed.
 Since credential managers may receive privileged information, the

 signature requirements for credential managers are specially strict.

 

-\section pi_pt_conf Configuration Provider

-

-Provides configuration information.

-[TODO: fill in]

-

-\subsection pi_pt_conf_comm Communication

-[TODO: fill in]

-

-\subsection pi_pt_conf_init Initialization

-[TODO: fill in]

-

-\subsection pi_pt_conf_exit Uninitialization

-[TODO: fill in]

-

-\subsection pi_pt_conf_other Other Notes

-

 */

 

 

diff --git a/src/windows/identity/doc/plugin_structure.h b/src/windows/identity/doc/plugin_structure.h
index c82af7b..452029e 100644
--- a/src/windows/identity/doc/plugin_structure.h
+++ b/src/windows/identity/doc/plugin_structure.h
@@ -29,9 +29,13 @@
 

 \page pi_structure Structure of a module

 

-A Network Identity Manager module is a dynamically loadable library with a

-specific set of exported symbols.  Each export symbol and general

-notes about writing a plug-in module are documented below.

+A Network Identity Manager module is a dynamically loadable library

+with a specific set of exported symbols.  Each export symbol and

+general notes about writing a plug-in module are documented below.

+

+\section pi_str_reg  Registration and Version Information

+

+[TODO]

 

 \section pi_str_init Initialization