NetIDMgr Module Manager


Modules

 Registration
 Internationalization support
 NetIDMgr Plugin Callbacks

Data Structures

struct  tag_kmm_plugin_reg
 Plugin registration. More...
struct  tag_kmm_plugin_info
 Plugin information. More...
struct  tag_kmm_module_reg
 Module registration. More...
struct  tag_kmm_module_info
 Module information record. More...

Limits

#define KMM_MAXCCH_NAME   256
 Maximum number of characters in a name in KMM including the terminating NULL.
#define KMM_MAXCB_NAME   (sizeof(wchar_t) * KMM_MAXCCH_NAME)
 Maximum number of bytes in a name in KMM including the terminating NULL.
#define KMM_MAXCCH_DESC   512
 Maximum number of characters in a description in KMM including the terminating NULL.
#define KMM_MAXCB_DESC   (sizeof(wchar_t) * KMM_MAXCCH_NAME)
 Maximum number of bytes in a description in KMM including the terminating NULL.
#define KMM_MAXCCH_VENDOR   256
 Maximum number of characters in a vendor string in KMM including the terminating NULL.
#define KMM_MAXCB_VENDOR   (sizeof(wchar_t) * KMM_MAXCCH_VENDOR)
 Maximum number of bytes in a vendor string in KMM including the terminating NULL.
#define KMM_MAXCCH_SUPPORT   256
 Maximum number of characters in a support URI in KMM including the terminating NULL.
#define KMM_MAXCB_SUPPORT   (sizeof(wchar_t) * KMM_MAXCCH_SUPPORT)
 Maximum number of bytes in a vendor string in KMM including the terminating NULL.
#define KMM_MAX_DEPENDENCIES   8
 Maximum number of dependencies per plugin.
#define KMM_MAX_DEPENDANTS   32
 Maximum number of dependants per plugin.
#define KMM_MAXCCH_DEPS   (KMM_MAXCCH_NAME * KMM_MAX_DEPENDENCIES + 1)
 Maximum number of characters a dependency string including trailing double NULL.
#define KMM_MAXCB_DEPS   (sizeof(wchar_t) * KMM_MAXCCH_DEPS)
 Maximum number of bytes in a dependency string including trailing double NULL.

Plugin types

#define KHM_PITYPE_CRED   1
 A credentials provider.
#define KHM_PITYPE_IDENT   2
 A identity provider.
#define KHM_PITYPE_CONFIG   3
 A configuration provider.
#define KHM_PITYPE_MISC   4
 Undefined plugin type.

Flags for kmm_load_module()

#define KMM_LM_FLAG_SYNC   1
 Load synchronously.
#define KMM_LM_FLAG_NOLOAD   2
 Do not load.

Defines

#define KMM_PLUGIN_FLAG_DISABLED   0x00000400
 The plugin is disabled.

Typedefs

typedef khm_handle kmm_module
 A handle to a module.
typedef khm_handle kmm_plugin
 A handle to a plugin.
typedef tag_kmm_plugin_reg kmm_plugin_reg
 Plugin registration.
typedef tag_kmm_plugin_info kmm_plugin_info
 Plugin information.
typedef tag_kmm_module_reg kmm_module_reg
 Module registration.
typedef tag_kmm_module_info kmm_module_info
 Module information record.

Enumerations

enum  _kmm_plugin_states {
  KMM_PLUGIN_STATE_FAIL_INIT = -6, KMM_PLUGIN_STATE_FAIL_UNKNOWN = -5, KMM_PLUGIN_STATE_FAIL_MAX_FAILURE = -4, KMM_PLUGIN_STATE_FAIL_NOT_REGISTERED = -3,
  KMM_PLUGIN_STATE_FAIL_DISABLED = -2, KMM_PLUGIN_STATE_FAIL_LOAD = -1, KMM_PLUGIN_STATE_NONE = 0, KMM_PLUGIN_STATE_PLACEHOLDER,
  KMM_PLUGIN_STATE_REG, KMM_PLUGIN_STATE_PREINIT, KMM_PLUGIN_STATE_HOLD, KMM_PLUGIN_STATE_INIT,
  KMM_PLUGIN_STATE_RUNNING, KMM_PLUGIN_STATE_EXITED
}
 Plugin states. More...
enum  KMM_MODULE_STATES {
  KMM_MODULE_STATE_FAIL_INCOMPAT = -12, KMM_MODULE_STATE_FAIL_INV_MODULE = -11, KMM_MODULE_STATE_FAIL_UNKNOWN = -10, KMM_MODULE_STATE_FAIL_MAX_FAILURE = -9,
  KMM_MODULE_STATE_FAIL_DUPLICATE = -8, KMM_MODULE_STATE_FAIL_NOT_REGISTERED = -7, KMM_MODULE_STATE_FAIL_NO_PLUGINS = -6, KMM_MODULE_STATE_FAIL_DISABLED = -5,
  KMM_MODULE_STATE_FAIL_LOAD = -4, KMM_MODULE_STATE_FAIL_INVALID = -3, KMM_MODULE_STATE_FAIL_SIGNATURE = -2, KMM_MODULE_STATE_FAIL_NOT_FOUND = -1,
  KMM_MODULE_STATE_NONE = 0, KMM_MODULE_STATE_PREINIT, KMM_MODULE_STATE_INIT, KMM_MODULE_STATE_INITPLUG,
  KMM_MODULE_STATE_RUNNING, KMM_MODULE_STATE_EXITPLUG, KMM_MODULE_STATE_EXIT, KMM_MODULE_STATE_EXITED
}
 Module states. More...

Functions

KHMEXP void KHMAPI kmm_init (void)
 Start the Module Manager.
KHMEXP void KHMAPI kmm_exit (void)
 Stop the Module Manager.
KHMEXP kmm_plugin KHMAPI kmm_this_plugin (void)
 Return the plugin handle for the current plugin.
KHMEXP kmm_module KHMAPI kmm_this_module (void)
 Return the module handle for the current module.
KHMEXP khm_int32 KHMAPI kmm_load_module (wchar_t *modname, khm_int32 flags, kmm_module *result)
 Load a module.
KHMEXP khm_int32 KHMAPI kmm_hold_module (kmm_module module)
 Hold a handle to a module.
KHMEXP khm_int32 KHMAPI kmm_release_module (kmm_module m)
 Release a handle to a module.
KHMEXP khm_int32 KHMAPI kmm_get_module_state (kmm_module m)
 Query the state of a module.
KHMEXP khm_int32 KHMAPI kmm_unload_module (kmm_module module)
 Unload a module.
KHMEXP khm_int32 KHMAPI kmm_load_default_modules (void)
 Loads the default modules as specified in the configuration.
KHMEXP khm_boolean KHMAPI kmm_load_pending (void)
 Checks whether there are any pending loads.
KHMEXP HMODULE KHMAPI kmm_get_hmodule (kmm_module m)
 Returns the Windows module handle from a handle to a NetIDMgr module. Although it is possible to obtain the Windows module handle and use it to call Windows API functions, it is not recommended to do so. This is because that might cause the state of the module to change in ways which are inconsistent from the internal data structures that kmm maintains.
KHMEXP khm_int32 KHMAPI kmm_hold_plugin (kmm_plugin p)
 Hold a plugin.
KHMEXP khm_int32 KHMAPI kmm_release_plugin (kmm_plugin p)
 Release a plugin.
KHMEXP khm_int32 KHMAPI kmm_provide_plugin (kmm_module module, kmm_plugin_reg *plugin)
 Provide a plugin.
KHMEXP khm_int32 KHMAPI kmm_get_plugin_state (wchar_t *plugin)
 Query the state of a plugin.


Define Documentation

#define KHM_PITYPE_CONFIG   3

A configuration provider.

See also:
pi_pt_conf for more information.

#define KHM_PITYPE_CRED   1

A credentials provider.

See also:
Credential Provider for more information.

#define KHM_PITYPE_IDENT   2

A identity provider.

See also:
Credential Provider for more information

#define KHM_PITYPE_MISC   4

Undefined plugin type.

The plugin doesn't provide any credential type.

#define KMM_LM_FLAG_NOLOAD   2

Do not load.

Indicates that the module shouldn't actually be loaded. If the specified module name identifies a module that has already been loaded, then the function returns a held handle to the existing module (use kmm_release_module() to free the handle). Otherwise, the function returns KHM_ERROR_NOT_FOUND.

#define KMM_LM_FLAG_SYNC   1

Load synchronously.

If this flag is set, then the function waits for the module to be loaded. The default is to load the module asynchronously.

When loading a module asynchronously, the kmm_load_module() function returns KHM_ERROR_SUCCESS and exits without waiting for the module to load. If result is not NULL, it will receive a valid handle to the module.

When loading a module synchronously, kmm_load_module() will wait for the module to completely load. If it fails to load properly, it will return an error code and set result to NULL.

#define KMM_PLUGIN_FLAG_DISABLED   0x00000400

The plugin is disabled.

This flag will be set in the flags field of the kmm_plugin_info structure for a plugin that has been marked as disabled. If the plugin is currently running, but marked as disabled for future sessions, then this bit will be set in flags , but the state of the plugin will indicate that the plugin is running.


Typedef Documentation

typedef struct tag_kmm_plugin_reg kmm_plugin_reg

Plugin registration.

See also:
khm_cred_provider


Enumeration Type Documentation

enum _kmm_plugin_states

Plugin states.

Enumerator:
KMM_PLUGIN_STATE_FAIL_INIT  Failed to initialize
KMM_PLUGIN_STATE_FAIL_UNKNOWN  Failed due to unknown reasons
KMM_PLUGIN_STATE_FAIL_MAX_FAILURE  The plugin has reached the maximum number of failures and cannot be initialized until the failure count is reset
KMM_PLUGIN_STATE_FAIL_NOT_REGISTERED  Failed because the plugin was not registered and automatic registration failed.
KMM_PLUGIN_STATE_FAIL_DISABLED  Failed because plugin was disabled by the user.
KMM_PLUGIN_STATE_FAIL_LOAD  The plugin failed to load due to some unknown reason.
KMM_PLUGIN_STATE_NONE  Unknown state
KMM_PLUGIN_STATE_PLACEHOLDER  Placeholder. The plugin hasn't been provided by anyone yet, but the plugin record has been created to keep track of dependencies.
KMM_PLUGIN_STATE_REG  The plugin is registered but not initialized
KMM_PLUGIN_STATE_PREINIT  The plugin is in the process of being initialized
KMM_PLUGIN_STATE_HOLD  On hold. One or more dependencies of this plugin has not been resolved
KMM_PLUGIN_STATE_INIT  The plugin was initialized
KMM_PLUGIN_STATE_RUNNING  The plugin is running
KMM_PLUGIN_STATE_EXITED  The plugin has been stopped.

enum KMM_MODULE_STATES

Module states.

Enumerator:
KMM_MODULE_STATE_FAIL_INCOMPAT  The library containing the module was not compatible with this version of NetIDMgr.
KMM_MODULE_STATE_FAIL_INV_MODULE  The library containing the module was invalid.
KMM_MODULE_STATE_FAIL_UNKNOWN  Module could not be loaded due to unknown reasons.
KMM_MODULE_STATE_FAIL_MAX_FAILURE  The module has failed too many times already. Not attempting to restart it again
KMM_MODULE_STATE_FAIL_DUPLICATE  An attempt was made to load the same module twice.
KMM_MODULE_STATE_FAIL_NOT_REGISTERED  The module is not found among the registered module list
KMM_MODULE_STATE_FAIL_NO_PLUGINS  The module provided no plugins, or all the plugins that are provided are disabled
KMM_MODULE_STATE_FAIL_DISABLED  Module is disabled and cannot be loaded
KMM_MODULE_STATE_FAIL_LOAD  The module failed to initialize
KMM_MODULE_STATE_FAIL_INVALID  The module was invalid. Typically caused by the required entrypoints not being present
KMM_MODULE_STATE_FAIL_SIGNATURE  The module failed to load due to an unverifiable signature
KMM_MODULE_STATE_FAIL_NOT_FOUND  The module was not found
KMM_MODULE_STATE_NONE  Unknown state. The handle is possibly invalid
KMM_MODULE_STATE_PREINIT  The module is being loaded. init_module() hasn't been called yet
KMM_MODULE_STATE_INIT  In init_module()
KMM_MODULE_STATE_INITPLUG  Initializing plugins
KMM_MODULE_STATE_RUNNING  Running
KMM_MODULE_STATE_EXITPLUG  Currently exiting plugins
KMM_MODULE_STATE_EXIT  Currently exiting
KMM_MODULE_STATE_EXITED  Exited


Function Documentation

KHMEXP void KHMAPI kmm_exit ( void   ) 

Stop the Module Manager.

Note:
Only called by the NetIDMgr core.

KHMEXP khm_int32 KHMAPI kmm_get_module_state ( kmm_module  m  ) 

Query the state of a module.

When loading a module asynchronously you can query the state of the loading process using this. The return value is a status indicator.

Returns:
The return value is one of the KMM_MODULE_STATES enumerations.

KHMEXP khm_int32 KHMAPI kmm_get_plugin_state ( wchar_t *  plugin  ) 

Query the state of a plugin.

Returns:
One of _kmm_plugin_states

KHMEXP khm_int32 KHMAPI kmm_hold_module ( kmm_module  module  ) 

Hold a handle to a module.

Use kmm_release_module() to release the hold.

KHMEXP khm_int32 KHMAPI kmm_hold_plugin ( kmm_plugin  p  ) 

Hold a plugin.

Obtains a hold on a plugin. The plugin handle will remain valid until the hold is released with a call to kmm_release_plugin(). No guarantees are made on the handle once the handle is released.

KHMEXP void KHMAPI kmm_init ( void   ) 

Start the Module Manager.

Note:
Only called by the NetIDMgr core.

KHMEXP khm_int32 KHMAPI kmm_load_default_modules ( void   ) 

Loads the default modules as specified in the configuration.

The configuration can specify the default set of modules to load. This function dispatches the necessary message for loading these modules and reutnrs.

KHMEXP khm_int32 KHMAPI kmm_load_module ( wchar_t *  modname,
khm_int32  flags,
kmm_module result 
)

Load a module.

The modulename parameter specifies a module to load. Depending on the configuration, not all of the plugins that are provided by the module may be loaded. If no plugins are successfully loaded, the module will be immediately unloaded.

If the module is currently loaded or is being loaded, then a valid handle to the existing module is returned.

When called with KMM_LM_FLAG_SYNC, the function does not return until the module and the associated plugins are all initialized, or an error occurs.

If the KMM_LM_FLAG_NOLOAD flag is set, then a handle to an existing instance of the module will be returned. If the module hasn't been loaded yet, then no handle is returned and the function returns KHM_ERROR_NOT_FOUND.

See the associated NetIDMgr Module Manager documentation on the sequence of events associated with loading a module.

Parameters:
[in] modulename Name of the module. The module should have been registered under this name prior to the call.
[in] flags Combination of KMM_LM_FLAG_*
[out] result Receives a handle to the loaded module. If the result is not required, set this to NULL. If result is not NULL, and km_load_module() returns KHM_ERROR_SUCCESS, then kmm_release_module() must be called to release the handle to the module. Otherwise, result receives NULL. If a handle is returned, it will be valid regardless of whether the module fails to load or not. You can use kmm_get_module_state() to query the progress of the loading process. See KMM_LM_FLAG_SYNC.
Return values:
KHM_ERROR_SUCCESS The call succeeded. If KMM_LM_FLAG_SYNC was specified, this means that the module was successfully loaded. Otherwise, it only means that the module has been queued up for loading. Use kmm_get_module_state() to determine if it was successfully loaded. If result is not NULL, a valid handle is returned.
KHM_ERROR_EXISTS The module is already loaded or has been already queued for loading. If result is not NULL, a valid handle to the existing module instance is returned.
KHM_ERROR_NOT_FOUND If called with KMM_LM_FLAG_NOLOAD, indicates that the module has not been loaded. Otherwise only returned when called with KMM_LM_FLAG_SYNC. The module image was not found. No handle is returned.
KHM_ERROR_INVALID_SIGNATURE Only returned when called with KMM_LM_FLAG_SYNC. The module was signed with an invalid certificate. No handle is returned.
KHM_ERROR_UNKNOWN Only returned when called with KMM_LM_FLAG_SYNC. Some other error has occured. No handle is returned.
See also:
Module Load Sequence

KMM_LM_FLAG_SYNC, KMM_LM_FLAG_NOLOAD

KHMEXP khm_boolean KHMAPI kmm_load_pending ( void   ) 

Checks whether there are any pending loads.

Returns TRUE if there are modules still waiting to be loaded.

KHMEXP khm_int32 KHMAPI kmm_provide_plugin ( kmm_module  module,
kmm_plugin_reg plugin 
)

Provide a plugin.

This function must be called for each plugin that the module provides.

Note that this function returns immediately and does not initialize the plugin. All plugins that are provided by a module will be initialized once the init_module() function returns. If the plugin has dependencies, it will be kept in a held state until the plugins that it depends on are successfully initialized. If the dependencies are not resolved (the dependent plugins are not loaded), then plugin will not be initialized.

If the plugin is not registered and plugin contains enough information to perform the registration, then it will be automatically registered. However, if the plugin is not registered and cannot be registered using the provided information, the plugin will not be initialized properly. Note that automatic registration will always register the plugin in the user configuration store.

The name and msg_proc members of plugin are required to have valid values. The icon member may optionally be specified. The other fields can be specified if the plugin should be automatically registered, however, the module field will be ignored and will be determined by the module handle.

Parameters:
[in] module Handle to this module that is providing the plugin.
[in] plugin A plugin descriptor.
Return values:
KHM_ERROR_SUCCESS Succeeded.
KHM_ERROR_INVALID_OPERATION The function was not called during init_module()
KHM_ERROR_INVALID_PARAM One or more parameters were invalid
KHM_ERROR_DUPLICATE The plugin was already provided
Note:
This can only be called when handing init_module()

KHMEXP khm_int32 KHMAPI kmm_release_module ( kmm_module  m  ) 

Release a handle to a module.

Release a held referece to a module that was returned in a call to kmm_load_module().

KHMEXP khm_int32 KHMAPI kmm_release_plugin ( kmm_plugin  p  ) 

Release a plugin.

Releases a hold on a plugin obtained through a call to kmm_hold_plugin(). The plugin handle should no longer be considered valied once this is called.

KHMEXP kmm_module KHMAPI kmm_this_module ( void   ) 

Return the module handle for the current module.

The returned handle represents the module which owns the current thread. The returned handle must be released by calling kmm_release_module()

KHMEXP kmm_plugin KHMAPI kmm_this_plugin ( void   ) 

Return the plugin handle for the current plugin.

The returned handle represents the plugin which owns the current thread. The returned handle must be released by calling kmm_release_plugin(). Returns NULL if the current thread is not owned by any plugin.

KHMEXP khm_int32 KHMAPI kmm_unload_module ( kmm_module  module  ) 

Unload a module.

See the associated NetIDMgr Module Manager documentation on the sequence of events associated with unloading a module.

See also:
Unload sequence


Generated on Fri Aug 3 08:27:14 2007 for Network Identity Manager by Doxygen 1.5.2
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu