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

---