/*!\r
\page pi_framework Plug-in Framework\r
\r
-\section pi_fw_pnm Plug-ins and Modules\r
+\section pi_fw_pnm Introduction to Plug-ins, Modules and Messages\r
\r
\subsection pi_fw_pnm_p Plug-ins\r
\r
-A Network Identity Manager plug-in is a package that implements a defined API that will\r
-perform credentials management or related tasks on behalf of Network Identity Manager.\r
-The core Network Identity Manager codebase does not interact directly with Kerberos v5 or\r
-AFS or any other external entity directly. Instead, plug-ins are used.\r
+A plug-in is a package that implements a defined API that will perform\r
+credentials management or related tasks on behalf of Network Identity\r
+Manager.\r
\r
-Each plug-in has a name. The name should be unique among the loaded\r
-plug-ins, or the plug-in will fail to load.\r
+The Network Identity Manager architecture is message based. The core\r
+of each plug-in is a message handler. The plug-in integrates with the\r
+application by subscribing to, and handling specific types of\r
+messages.\r
\r
-The method in which Network Identity Manager communicates with a plug-in depends on the\r
-plug-in type. For more information on each plug-in type, please refer\r
-to \ref pi_pt.\r
-\r
-Most plug-in types rely on a message processor for communication.\r
-During plug-in registration, the module specifies the message processor\r
-for the plug-in, which acts as the only point of contact between the\r
-Network Identity Manager core and the plug-in. Some other plug-ins require exporting\r
-specific functions.\r
+The plug-in message handler runs in its own thread and receive\r
+asynchronous messages. There are exceptions, such as when one plug-in\r
+requires another plug-in to handle a specific message before it can\r
+handle the message. In addition, during certain operations that\r
+require user interaction, each plug-in can delegate code that will run\r
+in the main application thread (the user interface thread) to process\r
+window messages.\r
\r
\subsection pi_fw_pnw_m Modules\r
\r
One or more plug-ins can be bundled together into a module. A module\r
-is a dynamically loadable library which exports a specific\r
-set of callbacks. Currently, the only two required callbacks for a\r
-module are :\r
+is a dynamically loadable library which exports a specific set of\r
+callbacks. Currently, the only two required callbacks for a module\r
+are :\r
\r
- init_module(), and\r
- exit_module()\r
\r
-\section pi_fw_pm Plug-in/Module Manager\r
+For more information about how a module is structured, see \ref\r
+pi_structure .\r
+\r
+\subsection pi_fw_pnm_msg Messages and Message Queues\r
+\r
+An integral part of this framework is the messaging system. Most of\r
+the communication between the Network Identity Manager application and\r
+plug-ins is conducted through passing messages.\r
+\r
+A message has a type and subtype and is denoted in this documentation\r
+as \< \e message_type, \e message_subtype\>. For example, when a\r
+plug-in is loaded, the first message it receives is \< ::KMSG_SYSTEM,\r
+::KMSG_SYSTEM_INIT \>.\r
+\r
+Each thread in the application, specially threads that were created\r
+for individual plug-in messages handlers, has an associated message\r
+queue that stores and manages all the messages that have been sent to\r
+subscribers in that thread.\r
+\r
+The most common recipient of a message is a message callback function\r
+(see ::kmq_callback_t ). The message handler for a plug-in is one such\r
+example. A message callback function receives the message type,\r
+subtype and two optional parameters for the message.\r
+\r
+Any acceptable recipient can subscribe to broadcast messages of any\r
+type. Once subscribed, whenever a message of that type is broadcast,\r
+the message will get queued on the corresponding message queue. Then,\r
+one of the dispatch functions can dispatch the message to the correct\r
+callback function. (see ::kmq_dispatch).\r
+\r
+Next \subpage pi_fw_pm ...\r
\r
-The plug-in manager maintains a separate thread for loading and\r
-registering modules. When a module is successfully loaded and it\r
+*/\r
+\r
+/*!\r
+\r
+\page pi_fw_pm Module Manager\r
+\r
+The module manager is tasked with loading, unloading and managing the\r
+plug-in message processing. It maintains a separate thread for loading\r
+and registering modules. When a module is successfully loaded and it\r
registers one or more plug-ins, a new thread is created for each\r
plug-in. Plug-in specific initialization and other callback functions\r
-are called from within this new thread. This is to prevent one plug-in\r
-from "hanging" other plug-ins and the main Network Identity Manager \r
-user interface threads.\r
+are called from within this new thread. This is to prevent one\r
+plug-in from "hanging" other plug-ins and the main Network Identity\r
+Manager user interface threads.\r
\r
Read more :\r
- \ref pi_structure\r
\r
\subsection pi_fw_pm_load Load sequence\r
\r
-When kmm_load_module() is called, the following sequence of events\r
-occur:\r
+When kmm_load_module() is called to load a specific module, the\r
+following sequence of events occur:\r
\r
-- The standard system search path is used to locate the binary.\r
+- The registration information for the module is located on the\r
+ registry key \c\r
+ \Software\MIT\NetIDMgr\PluginManager\Modules\[ModuleName].\r
\r
-- The binary is loaded into the address space of Network Identity Manager along with\r
- any dependencies not already loaded.\r
+- The \c ImagePath value from the registration information is used to\r
+ locate the module binary. If it is not an absolute path, then the\r
+ binary is located using the standard system search path starting\r
+ from the directory in which Network Identity Manager binaries are\r
+ located.\r
\r
-- If the Network Identity Manager core binary is signed, then the signature is checked\r
- against the system and user certificate stores. If this fails, the\r
- module is unloaded. See \ref pi_fw_pm_unload.\r
+- The binary is loaded into the address space of Network Identity\r
+ Manager along with any dependencies not already loaded.\r
\r
-- init_module() for the loaded module is called. If this function\r
- returns an error or if no plug-ins are registered, then the module is\r
- unloaded. See \ref pi_fw_pm_unload.\r
+- If the Network Identity Manager core binary is signed, then the\r
+ signature is checked against the system and user certificate stores.\r
+ If this fails, the module is unloaded. See \ref pi_fw_pm_unload.\r
+\r
+- The init_module() entry point for the loaded module is called. If\r
+ this function returns an error or if no plug-ins are registered,\r
+ then the module is immediately unloaded. See \ref pi_fw_pm_unload.\r
\r
- During processing of init_module(), if any localized resource\r
libraries are specified using kmm_set_locale_info(), then one of the\r
localized libraries will be loaded. See \ref pi_localization\r
\r
- During processing of init_module(), the module registers all the\r
- plug-ins that it is implementing by calling kmm_register_plug-in() for\r
+ plug-ins that it is implementing by calling kmm_register_plugin() for\r
each.\r
\r
- Once init_module() returns, each plug-in is initialized. The method\r
- During normal operation, any registered plug-ins for a module can be\r
unloaded explicitly, or the plug-in itself may signal that it should\r
be unloaded. If at anytime, all the plug-ins for the module are\r
- unloaded, then the module itself is also unloaded unless the NoUnload\r
- registry value is set in the module key.\r
+ unloaded, then the module itself is also unloaded unless the \c\r
+ NoUnload registry value is set in the module key.\r
\r
\subsection pi_fw_pm_unload Unload sequence\r
\r
- For each of the plug-ins that are registered for a module, the exit\r
code is invoked. The method by which this happens depends on the\r
- plug-in type. The plug-in is not given a chance to object to the\r
+ plug-in type. The plug-in is not given a chance to veto the\r
decision to unload. Each plug-in is responsible for performing\r
cleanup tasks, freeing resources and unsubscribing from any message\r
classes that it has subscribed to.\r
\r
-- exit_module() is called for the module.\r
+- The exit_module() entry point is called for the module.\r
\r
- If any localized resource libraries were loaded for the module, they\r
are unloaded.\r
\r
- The module is unloaded.\r
\r
+The following diagram illustrates the relationship between modules and\r
+plug-ins as implemented in the Kerberos 5 plug-in distributed with\r
+Network Identity Manager.\r
+\r
+\image html modules_plugins_krb5.png\r
+\r
*/\r
\r
\page plug-ins Network Identity Manager Modules and Plug-ins\r
\r
-Plug-ins and localization are handled by the Network Identity Manager Module Manager\r
-API. Each plug-in consists of a dynamically loadable library and zero\r
-or more associated resource libraries.\r
+ The Network Identity Manager application does not include any\r
+ ability to manage any specific type of credential. Instead it\r
+ exposes a framework on which plug-ins can be implemented to manage\r
+ credentials.\r
\r
-For more information about Network Identity Manager Plug-ins, see the following\r
-sections:\r
+ Plug-ins and localization are handled by the Network Identity\r
+ Manager Module Manager API.\r
\r
-- \subpage pi_framework\r
-- \subpage pi_pt\r
-- \subpage pi_structure\r
-- \subpage pi_localization\r
+ The following sections describe plug-ins in detail:\r
+\r
+ - \subpage pi_framework\r
+ - \subpage pi_pt\r
+ - \subpage pi_structure\r
+ - \subpage pi_localization\r
*/\r
\r
/*! \page pi_pt Plug-in Types\r
\r
-The types of plug-ins that are currently supported by Network Identity Manager are :\r
+The types of plug-ins that are currently supported by Network Identity\r
+Manager are :\r
\r
\section pi_pt_cred Credential Provider\r
\r
A credential provider plug-in essentially acts as an interface between\r
-Network Identity Manager and some entity which defines the credentials for the purpose\r
-of managing those credentials.\r
+Network Identity Manager and some entity which defines the credentials\r
+for the purpose of managing those credentials.\r
\r
There can be more than one credential provider in a module.\r
\r
\subsection pi_pt_cred_comm Communication\r
\r
-Communication between Network Identity Manager and a credential provider occurs\r
-through a message processor. When registering a credential provider,\r
-the module initialization code in init_module() specifies\r
-::KHM_PITYPE_CRED as the \a type member and sets \a msg_proc member to\r
-a valid message processor in the ::khm_plug-in record.\r
+Communication between Network Identity Manager and a credential\r
+provider occurs through a message processor. When registering a\r
+credential provider, the module initialization code in init_module()\r
+specifies ::KHM_PITYPE_CRED as the \a type member and sets \a msg_proc\r
+member to a valid message processor in the ::khm_plugin record.\r
\r
\subsection pi_pt_cred_init Initialization\r
\r
\r
The callback function should return KHM_ERROR_SUCCESS if it\r
initializes properly or some other value otherwise. If the return\r
-value signals an error, then the plug-in is assume to not be loaded and\r
-immediately unregistered.\r
+value signals an error, then the plug-in is assumed to have failed\r
+initialization and is immediately unloaded.\r
\r
The message processor is automatically subscribed to the following\r
message types:\r
on the new credential messages may not be loaded at this time. See the\r
section on \ref cred_msgs for more information.\r
\r
-\r
\subsection pi_pt_cred_exit Uninitialization\r
\r
When the plug-in is to be removed, the module manager sends a\r
Since credential managers may receive privileged information, the\r
signature requirements for credential managers are specially strict.\r
\r
-\section pi_pt_conf Configuration Provider\r
-\r
-Provides configuration information.\r
-[TODO: fill in]\r
-\r
-\subsection pi_pt_conf_comm Communication\r
-[TODO: fill in]\r
-\r
-\subsection pi_pt_conf_init Initialization\r
-[TODO: fill in]\r
-\r
-\subsection pi_pt_conf_exit Uninitialization\r
-[TODO: fill in]\r
-\r
-\subsection pi_pt_conf_other Other Notes\r
-\r
*/\r
\r
\r
projects / krb5.git / commitdiff
