Registration
[NetIDMgr Module Manager]


Detailed Description

The functions for managing plugin and module registration. These functions are also available as static linked libraries for use by external applications which must register or unregister plugins or modules.


Functions

KHMEXP khm_int32 KHMAPI kmm_get_plugin_config (wchar_t *plugin, khm_int32 flags, khm_handle *result)
 Obtain the configuration space for a named plugin.
KHMEXP khm_int32 KHMAPI kmm_get_module_config (wchar_t *module, khm_int32 flags, khm_handle *result)
 Obtain the configuration space or a named module.
KHMEXP khm_int32 KHMAPI kmm_get_plugins_config (khm_int32 flags, khm_handle *result)
 Retrieve a handle to the configuration space for plugins.
KHMEXP khm_int32 KHMAPI kmm_get_modules_config (khm_int32 flags, khm_handle *result)
 Retrieve the handle to the configuration space for modules.
KHMEXP khm_int32 KHMAPI kmm_get_module_info (wchar_t *module_name, khm_int32 flags, kmm_module_info *buffer, khm_size *cb_buffer)
 Return information about a loaded module.
KHMEXP khm_int32 KHMAPI kmm_get_module_info_i (kmm_module module, kmm_module_info *info)
 Get information about a module.
KHMEXP khm_int32 KHMAPI kmm_release_module_info_i (kmm_module_info *info)
 Release module information.
KHMEXP khm_int32 KHMAPI kmm_get_plugin_info (wchar_t *plugin_name, kmm_plugin_info *buffer, khm_size *cb_buffer)
 Obtain information about a plugin.
KHMEXP khm_int32 KHMAPI kmm_get_plugin_info_i (kmm_plugin p, kmm_plugin_info *info)
 Obtain information about a plugin using a plugin handle.
KHMEXP khm_int32 KHMAPI kmm_release_plugin_info_i (kmm_plugin_info *info)
 Release plugin information returned by kmm_get_plugin_info_i.
KHMEXP khm_int32 KHMAPI kmm_get_next_plugin (kmm_plugin p, kmm_plugin *p_next)
 Enumerates plugins.
KHMEXP khm_int32 KHMAPI kmm_enable_plugin (kmm_plugin p, khm_boolean enable)
 Enables or disables a plugin.
KHMEXP khm_int32 KHMAPI kmm_register_plugin (kmm_plugin_reg *plugin, khm_int32 config_flags)
 Register a plugin.
KHMEXP khm_int32 KHMAPI kmm_register_module (kmm_module_reg *module, khm_int32 config_flags)
 Register a module.
KHMEXP khm_int32 KHMAPI kmm_unregister_plugin (wchar_t *plugin, khm_int32 config_flags)
 Unregister a plugin.
KHMEXP khm_int32 KHMAPI kmm_unregister_module (wchar_t *module, khm_int32 config_flags)
 Unregister a module.


Function Documentation

KHMEXP khm_int32 KHMAPI kmm_enable_plugin ( kmm_plugin  p,
khm_boolean  enable 
)

Enables or disables a plugin.

This function currently does not take effect immediately. However it marks the plugin as enabled or disabled so that the next time NetIDMgr starts, the module manager will act accordingly.

Parameters:
[in] p Handle to the plugin
[in] enable If non-zero, the plugin will be marked as enabled. Otherwise the plugin will be marked as disabled.

KHMEXP khm_int32 KHMAPI kmm_get_module_config ( wchar_t *  module,
khm_int32  flags,
khm_handle result 
)

Obtain the configuration space or a named module.

The named module does not have to actually exist. Configuration spaces for modules are based on the basename of the module (including the extension).

Parameters:
[in] module Name of the module.
[in] flags The flags used to call khc_open_space(). You can use this to specify a particular configuration store if needed.
[out] result Receives the handle to a configuration space if successful. Call khc_close_space() to close the handle.
See also:
khc_open_space()

khc_close_space()

KHMEXP khm_int32 KHMAPI kmm_get_module_info ( wchar_t *  module_name,
khm_int32  flags,
kmm_module_info buffer,
khm_size cb_buffer 
)

Return information about a loaded module.

The retrieves a block of information about a module. Refer to kmm_module_info for information about the format of the returned data.

Note that the size of the required buffer is actually greater than the size of the kmm_module_info structure and accomodates the kmm_plugin_info structures and strings required to complete the information block.

Call the function with buffer set to NULL and cb_buffer pointing at a khm_size variable to obtain the required size of the buffer.

Parameters:
[in] module_name Name of a module
[in] flags Flags indicating which types of information to return
[out] buffer Points to a buffer that recieves information. Set this to NULL if only the size of the buffer is required.
[in,out] On entry, contains the size of the buffer pointed to by buffer if buffer is not NULL. On exit, contains the required size of the buffer or the number of actual bytes copied.
Return values:
KHM_ERROR_SUCCESS The requested information was copied
KHM_ERROR_INVALID_PARAM One of the parameters was invalid
KHM_ERROR_TOO_LONG The buffer was not large enough or was NULL. The number of bytes requied is in cb_buffer.
KHM_ERROR_NOT_FOUND The specified module is not a registered module.

KHMEXP khm_int32 KHMAPI kmm_get_module_info_i ( kmm_module  module,
kmm_module_info info 
)

Get information about a module.

Similar to kmm_get_module_info(), but uses a module handle instead of a name, and uses internal buffers for providing string fields.

The information that is returned should be freed using a call to kmm_release_module_info_i().

See also:
kmm_release_module_info_i()

KHMEXP khm_int32 KHMAPI kmm_get_modules_config ( khm_int32  flags,
khm_handle result 
)

Retrieve the handle to the configuration space for modules.

The configuration space for modules is a container which hold the configuration subspaces for all the modules. Each module registration ends up in this subspace.

Parameters:
[in] flags The flags to pass in to the call to khc_open_space(). The flags can be used to select a specific configuration store if needed.
[out] result Receives a handle to the configuration space. Call khc_close_space() to close the handle.
See also:
khc_open_space()

khc_close_space()

KHMEXP khm_int32 KHMAPI kmm_get_next_plugin ( kmm_plugin  p,
kmm_plugin p_next 
)

Enumerates plugins.

Enumerates through known plugins. This list may not include plugins which were not loaded by NetIDMgr in this session.

If the call is successful, a handle to the next plugin in the list will be placed in p_next. The returned handle must be freed with a call to kmm_release_plugin().

If the p parameter is set to NULL, then the first plugin handle will be placed in p_next. The handles will not be returned in any specific order. In addition, the enumeration may not include all known plugins if the list of plugins changes during enumeration.

KHMEXP khm_int32 KHMAPI kmm_get_plugin_config ( wchar_t *  plugin,
khm_int32  flags,
khm_handle result 
)

Obtain the configuration space for a named plugin.

Note that the named plugin does not have to actually exist. Configuration spaces for plugins are based solely on the plugin name and hence can be accessed regardless of whether the specific plugin is loaded or not.

Parameters:
[in] flags Controls the options for opening the configuration space. If KHM_FLAG_CREATE is specified, then the configuration space for the plugin named plugin wil be created if it doesn't already exist. The flags parameter is directly passed into a call to khc_open_space().
[in] plugin Name of the plugin. The name can not contain slashes.
[out] result Receives a configuration space handle. The calling application should free the handle using khc_close_space().
See also:
khc_open_space()

khc_close_space()

KHMEXP khm_int32 KHMAPI kmm_get_plugin_info ( wchar_t *  plugin_name,
kmm_plugin_info buffer,
khm_size cb_buffer 
)

Obtain information about a plugin.

Retrieve a block of information about a plugin. See kmm_plugin_info for details about what information can be returned. Note that some fields may not be available if the module is not loaded.

Note that the size of the required buffer is greater than the size of the kmm_plugin_info structure and accounts for strings as well. Call kmm_get_plugin_info() with buffer set to NULL and cb_buffer set to point to a variable of type khm_size to obtain the required size of the structure.

Parameters:
[in] plugin_name Name of the plugin
[out] buffer The buffer to receive the plugin information. Set to NULL if only the size of the buffer is required.
[in,out] cb_buffer On entry, points to variable that specifies the size of the buffer pointed to by buffer is buffer is not NULL. On exit, holds the number of bytes copied or the required size of the buffer.
Return values:
KHM_ERROR_SUCCESS The requested information was successfully copied to the buffer
KHM_ERROR_TOO_LONG The buffer was either NULL or insufficient to hold the requested information. The required size of the buffer was stored in cb_buffer
KHM_ERROR_INVALID_PARAM One or more parameters were invlaid.
KHM_ERROR_NOT_FOUND The specified plugin was not found among the registered plugins.

KHMEXP khm_int32 KHMAPI kmm_get_plugin_info_i ( kmm_plugin  p,
kmm_plugin_info info 
)

Obtain information about a plugin using a plugin handle.

Similar to kmm_get_plugin_info() but uses a plugin handle instead of a plugin name. If the call is successful, the info structure will be filled with information about the plugin. The returned info should not be modified in any way and may contain pointers to internal buffers.

The returned information must be released with a call to kmm_release_plugin_info_i().

KHMEXP khm_int32 KHMAPI kmm_get_plugins_config ( khm_int32  flags,
khm_handle result 
)

Retrieve a handle to the configuration space for plugins.

The configuration space for plugins is a container which holds the configuration subspaces for all the plugins. This is the config space which must be used to load a configuration space for a plugin.

Parameters:
[in] flags The flags to pass in to the call to khc_open_space(). The flags can be used to select a specific configuration store if needed.
[out] result Receives a handle to the configuration space. Call khc_close_space() to close the handle
See also:
khc_open_space()

khc_close_space()

KHMEXP khm_int32 KHMAPI kmm_register_module ( kmm_module_reg module,
khm_int32  config_flags 
)

Register a module.

The module parameter specifies the parameters for the module registration.

The plugin_info member should point to an array of kmm_plugin_info structures unless the n_plugins member is zero, in which case plugin_info can be NULL. Plugins can be registered separately using kmm_register_plugin().

Parameters:
[in] module Information about the module. The name and path fields are required. The plugin_info field can only be NULL if n_plugins is zero.
[in] config_flags Flags used to call khc_open_space(). This can be used to choose the configuration store in which the module registration will be performed.

KHMEXP khm_int32 KHMAPI kmm_register_plugin ( kmm_plugin_reg plugin,
khm_int32  config_flags 
)

Register a plugin.

The plugin member defines the plugin to be registered. The msg_proc and icon members of the structure are ignored.

At the time kmm_register_plugin() is called, the module specified by module member of the plugin parameter must have been already registered. Otherwise the function call fails.

If the plugin has already been registered, then all the fields in the plugin registration will be updated to be in sync with the information provided in the plugin parameter. The failure counts and associated statistics will not be reset when the configuration information is updated.

If the plugin has not been registered, the a new registration entry is created in the configuration space indicated by the config_flags parameter. In addition, the plugin will be added to the list of plugins associated with the owning module.

Note that the module that owns the plugin must be registered in the same configuration store as the plugin.

Parameters:
[in] plugin Registration info for the plugin. The msg_proc and icon members are ignored. All other fields are required. The description member should be localized to the system locale when registering a plugin in the machine configuration store and should be localized to the user locale when registering a plugin in the user configuration store.
[in] config_flags Flags for the configuration provider. These flags are used verbatim to call khc_open_space(), hence they may be used to pick whether or not the registration is per machine or per user.
See also:
kmm_register_module()

KHMEXP khm_int32 KHMAPI kmm_release_module_info_i ( kmm_module_info info  ) 

Release module information.

Releases the information returned by a previous call to kmm_get_module_info_i(). The contents of the kmm_module_info structure should not have been modified in any way between calling kmm_get_module_info_i() and kmm_release_module_info_i().

KHMEXP khm_int32 KHMAPI kmm_release_plugin_info_i ( kmm_plugin_info info  ) 

Release plugin information returned by kmm_get_plugin_info_i.

The information returned by kmm_get_plugin_info_i() should not be modified in any way before calling kmm_release_plugin_info_i(). Once the call completes, the contents of info will be initialized to zero.

KHMEXP khm_int32 KHMAPI kmm_unregister_module ( wchar_t *  module,
khm_int32  config_flags 
)

Unregister a module.

Registration information associated with the module as well as all the plugins provided by the module will be removed from the configuration store.

Parameters:
[in] module Names the module to be removed
[in] config_flags Flags used to call khc_open_space(). Can be used to choose the configuration store affected by the call.
Note:
kmm_unregister_module() has no effect on the loaded state of the module. The caller should make sure that the module is unloaded and in a state where it can be unregistered.

KHMEXP khm_int32 KHMAPI kmm_unregister_plugin ( wchar_t *  plugin,
khm_int32  config_flags 
)

Unregister a plugin.

Registration information associated with the plugin will be removed. In addtion, the plugin will be removed from the list of plugins provided by the owner module.

Parameters:
[in] plugin Names the plugin to be removed
[in] config_flags Flags used to call khc_open_space(). Can be used to choose the configuraiton store that is affected by the call.
Note:
kmm_unregister_plugin() has no effect on whether the plugin is loaded or not. The caller must make sure that the plugin is unloaded and the associated module is either also unloaded or in a state where the plugin can be unregistered.


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