src/WINNT/kfw/inc/netidmgr/kmm.h

   1 /*
   2  * Copyright (c) 2005 Massachusetts Institute of Technology
   3  *
   4  * Permission is hereby granted, free of charge, to any person
   5  * obtaining a copy of this software and associated documentation
   6  * files (the "Software"), to deal in the Software without
   7  * restriction, including without limitation the rights to use, copy,
   8  * modify, merge, publish, distribute, sublicense, and/or sell copies
   9  * of the Software, and to permit persons to whom the Software is
  10  * furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  19  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  20  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24
  25 /* $Id$ */
  26
  27 #ifndef __KHIMAIRA_KMM_H
  28 #define __KHIMAIRA_KMM_H
  29
  30 #include<khdefs.h>
  31 #include<kmq.h>
  32
  33 /*! \defgroup kmm NetIDMgr Module Manager
  34 @{*/
  35
  36 /*! \brief A handle to a module.
  37 */
  38 typedef khm_handle kmm_module;
  39
  40 /*! \brief A handle to a plugin.
  41  */
  42 typedef khm_handle kmm_plugin;
  43
  44 /*! \name Limits
  45   @{*/
  46
  47 /*! \brief Maximum number of characters in a name in KMM including the terminating NULL */
  48 #define KMM_MAXCCH_NAME 256
  49
  50 /*! \brief Maximum number of bytes in a name in KMM including the terminating NULL */
  51 #define KMM_MAXCB_NAME (sizeof(wchar_t) * KMM_MAXCCH_NAME)
  52
  53 /*! \brief Maximum number of characters in a description in KMM including the terminating NULL */
  54 #define KMM_MAXCCH_DESC 512
  55
  56 /*! \brief Maximum number of bytes in a description in KMM including the terminating NULL */
  57 #define KMM_MAXCB_DESC (sizeof(wchar_t) * KMM_MAXCCH_NAME)
  58
  59 /*! \brief Maximum number of characters in a vendor string in KMM including the terminating NULL */
  60 #define KMM_MAXCCH_VENDOR 256
  61
  62 /*! \brief Maximum number of bytes in a vendor string in KMM including the terminating NULL */
  63 #define KMM_MAXCB_VENDOR (sizeof(wchar_t) * KMM_MAXCCH_VENDOR)
  64
  65 /*! \brief Maximum number of characters in a support URI in KMM including the terminating NULL */
  66 #define KMM_MAXCCH_SUPPORT 256
  67
  68 /*! \brief Maximum number of bytes in a vendor string in KMM including the terminating NULL */
  69 #define KMM_MAXCB_SUPPORT (sizeof(wchar_t) * KMM_MAXCCH_SUPPORT)
  70
  71 /*! \brief Maximum number of dependencies per plugin
  72 */
  73 #define KMM_MAX_DEPENDENCIES    8
  74
  75 /*! \brief Maximum number of dependants per plugin
  76  */
  77 #define KMM_MAX_DEPENDANTS      32
  78
  79 /*! \brief Maximum number of characters a dependency string including trailing double NULL */
  80 #define KMM_MAXCCH_DEPS (KMM_MAXCCH_NAME * KMM_MAX_DEPENDENCIES + 1)
  81
  82 /*! \brief Maximum number of bytes in a dependency string including trailing double NULL */
  83 #define KMM_MAXCB_DEPS (sizeof(wchar_t) * KMM_MAXCCH_DEPS)
  84 /*@}*/ /* Limits */
  85
  86 /*! \brief Plugin registration
  87
  88     \see ::khm_cred_provider
  89 */
  90 typedef struct tag_kmm_plugin_reg {
  91     wchar_t *   name;           /*!< Name of the plugin.  Maximum of
  92                                      KMM_MAXCCH_NAME characters
  93                                      including the terminating
  94                                      NULL. Required. */
  95
  96     wchar_t *   module;         /*!< Name of module that owns the
  97                                      plugin. Maximum of
  98                                      KMM_MAXCCH_NAME characters
  99                                      including terminating NULL.
 100                                      Required. */
 101
 102     khm_int32   type;           /*!< Type plugin type.  One of
 103                                      KHM_PITYPE_*. Required. */
 104     khm_int32   flags;          /*!< Unused. Set to 0 */
 105     kmq_callback_t msg_proc;    /*!< Message processor.  Required. */
 106     wchar_t *   dependencies;   /*!< Dependencies.  Note that this is
 107                                      a multi string.  (you can use the
 108                                      KHC multi string functions to
 109                                      manipulate multi strings or to
 110                                      convert a comma separated list of
 111                                      dependencies to a multi string).
 112                                      Each string in the multi string
 113                                      is a name of a plugin that this
 114                                      plugin depends on.  Optional (set
 115                                      to NULL if this plugin has no
 116                                      dependencies). Maximum of
 117                                      KMM_MAXCCH_DEPS characters
 118                                      including terminating double
 119                                      NULL.*/
 120
 121     wchar_t *   description;    /*!< Description of the plugin.
 122                                      Maximum of KMM_MAXCCH_DESC
 123                                      characters including the
 124                                      terminating
 125                                      NULL. Localized. Optional (set to
 126                                      NULL if not provided) */
 127 #ifdef _WIN32
 128     HICON       icon;           /*!< Icon used to represent the
 129                                      plugin. Optional. (set to NULL if
 130                                      not provided) */
 131 #endif
 132 } kmm_plugin_reg;
 133
 134 /*! \brief Plugin information
 135 */
 136 typedef struct tag_kmm_plugin_info {
 137     kmm_plugin_reg reg;         /*!< Registration info */
 138
 139     khm_int32   state;          /*!< Current status of the plugin.
 140                                   One of ::_kmm_plugin_states */
 141
 142     khm_int32   failure_count;  /*!< Number of recorded failures in
 143                                      the plugin */
 144     FILETIME    failure_time;   /*!< Time of first recorded failure */
 145     khm_int32   failure_reason; /*!< The reason for the first recorded
 146                                      failure */
 147
 148     kmm_plugin  h_plugin;       /*!< Handle to plugin */
 149
 150     khm_int32   flags;          /*!< Flags for the plugin. Currently
 151                                   this can only specify
 152                                   ::KMM_PLUGIN_FLAG_DISABLED. */
 153 } kmm_plugin_info;
 154
 155 /*! \brief The plugin is disabled
 156
 157     This flag will be set in the \a flags field of the
 158     ::kmm_plugin_info structure for a plugin that has been marked as
 159     disabled.  If the plugin is currently running, but marked as
 160     disabled for future sessions, then this bit will be set in \a
 161     flags , but the \a state of the plugin will indicate that the
 162     plugin is running.
 163  */
 164 #define KMM_PLUGIN_FLAG_DISABLED    0x00000400
 165
 166 /*! \name Plugin types
 167 @{*/
 168 /*! \brief A credentials provider
 169
 170     \see \ref pi_pt_cred for more information.
 171  */
 172 #define KHM_PITYPE_CRED     1
 173
 174 /*! \brief A identity provider
 175
 176     \see \ref pi_pt_cred for more information
 177  */
 178 #define KHM_PITYPE_IDENT    2
 179
 180 /*! \brief A configuration provider
 181
 182     \see \ref pi_pt_conf for more information.
 183  */
 184 #define KHM_PITYPE_CONFIG   3
 185
 186 /*! \brief Undefined plugin type
 187
 188     The plugin doesn't provide any credential type.
 189  */
 190 #define KHM_PITYPE_MISC     4
 191
 192 /*@}*/
 193
 194 /*! \brief Plugin states */
 195 enum _kmm_plugin_states {
 196     KMM_PLUGIN_STATE_FAIL_INIT = -6,    /*!< Failed to initialize */
 197     KMM_PLUGIN_STATE_FAIL_UNKNOWN = -5, /*!< Failed due to unknown
 198                                           reasons */
 199     KMM_PLUGIN_STATE_FAIL_MAX_FAILURE = -4, /*!< The plugin has
 200                                           reached the maximum number
 201                                           of failures and cannot be
 202                                           initialized until the
 203                                           failure count is reset */
 204     KMM_PLUGIN_STATE_FAIL_NOT_REGISTERED = -3, /*!< Failed because the
 205                                           plugin was not registered
 206                                           and automatic registration
 207                                           failed. */
 208     KMM_PLUGIN_STATE_FAIL_DISABLED = -2,/*!< Failed because plugin was
 209                                           disabled by the user. */
 210     KMM_PLUGIN_STATE_FAIL_LOAD = -1,    /*!< The plugin failed to load
 211                                           due to some unknown
 212                                           reason. */
 213     KMM_PLUGIN_STATE_NONE = 0,          /*!< Unknown state */
 214     KMM_PLUGIN_STATE_PLACEHOLDER,       /*!< Placeholder.  The plugin
 215                                           hasn't been provided by
 216                                           anyone yet, but the plugin
 217                                           record has been created to
 218                                           keep track of
 219                                           dependencies. */
 220     KMM_PLUGIN_STATE_REG,               /*!< The plugin is registered
 221                                           but not initialized */
 222     KMM_PLUGIN_STATE_PREINIT,           /*!< The plugin is in the
 223                                           process of being
 224                                           initialized */
 225     KMM_PLUGIN_STATE_HOLD,              /*!< On hold.  One or more
 226                                           dependencies of this plugin
 227                                           has not been resolved */
 228     KMM_PLUGIN_STATE_INIT,              /*!< The plugin was initialized */
 229     KMM_PLUGIN_STATE_RUNNING,           /*!< The plugin is running */
 230     KMM_PLUGIN_STATE_EXITED             /*!< The plugin has been stopped. */
 231 };
 232
 233 /*! \brief Module registration */
 234 typedef struct tag_kmm_module_reg {
 235     wchar_t *   name;               /*!< Identifier for the module */
 236     wchar_t *   path;               /*!< Full pathname to module
 237                                          binary */
 238
 239     wchar_t *   description;        /*!< Description of module */
 240
 241     wchar_t *   vendor;             /*!< Vendor/copyright string */
 242
 243     wchar_t *   support;            /*!< Support URL/contact */
 244
 245     khm_int32   n_plugins;          /*!< Number of plugins that are
 246                                          active */
 247     kmm_plugin_reg * plugin_reg_info;  /*!< Array of kmm_plugin_reg
 248                                          records for each active
 249                                          plugin */
 250 } kmm_module_reg;
 251
 252 /*! \brief Module information record */
 253 typedef struct tag_kmm_module_info {
 254     kmm_module_reg reg;             /*!< Registration info */
 255
 256     khm_ui_4    language;           /*!< Currently loaded langugage */
 257
 258     khm_int32   state;              /*!< Current status of the
 259                                          module */
 260
 261     khm_version file_version;       /*!< File version for the
 262                                          module */
 263     khm_version product_version;    /*!< Product version for the
 264                                          module */
 265
 266     khm_int32   failure_count;      /*!< Number of times the module
 267                                          has failed to load */
 268     FILETIME    failure_time;       /*!< Time of first recorded
 269                                          failure */
 270     khm_int32   failure_reason;     /*!< Reason for first failure.
 271                                          One of the module status
 272                                          values */
 273
 274     kmm_module  h_module;           /*!< Handle to the module. */
 275 } kmm_module_info;
 276
 277 /*! \brief Module states
 278 */
 279 enum KMM_MODULE_STATES {
 280     KMM_MODULE_STATE_FAIL_INCOMPAT=-12, /*!< The library containing
 281                                           the module was not
 282                                           compatible with this version
 283                                           of NetIDMgr. */
 284     KMM_MODULE_STATE_FAIL_INV_MODULE=-11, /*!< The library containing
 285                                             the module was invalid. */
 286     KMM_MODULE_STATE_FAIL_UNKNOWN=-10,   /*!< Module could not be
 287                                           loaded due to unknown
 288                                           reasons. */
 289     KMM_MODULE_STATE_FAIL_MAX_FAILURE=-9,/*!< The module has failed
 290                                           too many times already.  Not
 291                                           attempting to restart it
 292                                           again */
 293     KMM_MODULE_STATE_FAIL_DUPLICATE=-8, /*!< An attempt was made to
 294                                           load the same module
 295                                           twice. */
 296     KMM_MODULE_STATE_FAIL_NOT_REGISTERED=-7, /*!< The module is not
 297                                           found among the registered
 298                                           module list */
 299     KMM_MODULE_STATE_FAIL_NO_PLUGINS=-6,/*!< The module provided no
 300                                           plugins, or all the plugins
 301                                           that are provided are
 302                                           disabled */
 303     KMM_MODULE_STATE_FAIL_DISABLED=-5,  /*!< Module is disabled and
 304                                           cannot be loaded */
 305     KMM_MODULE_STATE_FAIL_LOAD=-4,      /*!< The module failed to
 306                                           initialize */
 307     KMM_MODULE_STATE_FAIL_INVALID=-3,   /*!< The module was invalid.
 308                                           Typically caused by the
 309                                           required entrypoints not
 310                                           being present */
 311     KMM_MODULE_STATE_FAIL_SIGNATURE=-2, /*!< The module failed to load
 312                                           due to an unverifiable
 313                                           signature */
 314     KMM_MODULE_STATE_FAIL_NOT_FOUND=-1, /*!< The module was not
 315                                           found */
 316     KMM_MODULE_STATE_NONE=0,            /*!< Unknown state. The handle
 317                                           is possibly invalid */
 318     KMM_MODULE_STATE_PREINIT,           /*!< The module is being
 319                                           loaded. init_module() hasn't
 320                                           been called yet */
 321     KMM_MODULE_STATE_INIT,              /*!< In init_module() */
 322     KMM_MODULE_STATE_INITPLUG,          /*!< Initializing plugins */
 323     KMM_MODULE_STATE_RUNNING,           /*!< Running */
 324     KMM_MODULE_STATE_EXITPLUG,          /*!< Currently exiting plugins */
 325     KMM_MODULE_STATE_EXIT,              /*!< Currently exiting */
 326     KMM_MODULE_STATE_EXITED             /*!< Exited */
 327 };
 328
 329 /*! \brief Start the Module Manager
 330
 331     \note Only called by the NetIDMgr core.
 332 */
 333 KHMEXP void KHMAPI
 334 kmm_init(void);
 335
 336 /*! \brief Stop the Module Manager
 337
 338     \note Only called by the NetIDMgr core.
 339 */
 340 KHMEXP void KHMAPI
 341 kmm_exit(void);
 342
 343 /*! \brief Return the plugin handle for the current plugin
 344
 345     The returned handle represents the plugin which owns the current
 346     thread.  The returned handle must be released by calling
 347     kmm_release_plugin().  Returns NULL if the current thread is not
 348     owned by any plugin.
 349  */
 350 KHMEXP kmm_plugin KHMAPI
 351 kmm_this_plugin(void);
 352
 353 /*! \brief Return the module handle for the current module
 354
 355     The returned handle represents the module which owns the current
 356     thread.  The returned handle must be released by calling
 357     kmm_release_module()
 358 */
 359 KHMEXP kmm_module KHMAPI
 360 kmm_this_module(void);
 361
 362 /*! \name Flags for kmm_load_module()
 363 @{*/
 364 /*!\brief Load synchronously
 365
 366     If this flag is set, then the function waits for the module to be
 367     loaded.  The default is to load the module asynchronously.
 368
 369     When loading a module asynchronously, the kmm_load_module()
 370     function returns KHM_ERROR_SUCCESS and exits without waiting for
 371     the module to load.  If \a result is not NULL, it will receive a
 372     valid handle to the module.
 373
 374     When loading a module synchronously, kmm_load_module() will wait
 375     for the module to completely load.  If it fails to load properly,
 376     it will return an error code and set \a result to NULL.
 377 */
 378 #define KMM_LM_FLAG_SYNC    1
 379
 380 /*! \brief Do not load
 381
 382     Indicates that the module shouldn't actually be loaded.  If the
 383     specified module name identifies a module that has already been
 384     loaded, then the function returns a held handle to the existing
 385     module (use kmm_release_module() to free the handle).  Otherwise,
 386     the function returns KHM_ERROR_NOT_FOUND.
 387 */
 388 #define KMM_LM_FLAG_NOLOAD  2
 389 /*@}*/
 390
 391 /*! \brief Load a module
 392
 393     The \a modulename parameter specifies a module to load.  Depending
 394     on the configuration, not all of the plugins that are provided by
 395     the module may be loaded.  If no plugins are successfully loaded,
 396     the module will be immediately unloaded.
 397
 398     If the module is currently loaded or is being loaded, then a valid
 399     handle to the existing module is returned.
 400
 401     When called with KMM_LM_FLAG_SYNC, the function does not return
 402     until the module and the associated plugins are all initialized,
 403     or an error occurs.
 404
 405     If the KMM_LM_FLAG_NOLOAD flag is set, then a handle to an
 406     existing instance of the module will be returned.  If the module
 407     hasn't been loaded yet, then no handle is returned and the
 408     function returns KHM_ERROR_NOT_FOUND.
 409
 410     See the associated NetIDMgr Module Manager documentation on the
 411     sequence of events associated with loading a module.
 412
 413     \param[in] modulename Name of the module.  The module should have
 414         been registered under this name prior to the call.
 415     \param[in] flags Combination of KMM_LM_FLAG_*
 416     \param[out] result Receives a handle to the loaded module.  If the
 417         result is not required, set this to NULL. If \a result is not
 418         NULL, and km_load_module() returns KHM_ERROR_SUCCESS, then
 419         kmm_release_module() must be called to release the handle to
 420         the module.  Otherwise, \a result receives NULL.  If a handle
 421         is returned, it will be valid regardless of whether the module
 422         fails to load or not.  You can use kmm_get_module_state() to
 423         query the progress of the loading process.  See
 424         ::KMM_LM_FLAG_SYNC.
 425
 426     \retval KHM_ERROR_SUCCESS The call succeeded.  If \a
 427         KMM_LM_FLAG_SYNC was specified, this means that the module was
 428         successfully loaded.  Otherwise, it only means that the module
 429         has been queued up for loading.  Use kmm_get_module_state() to
 430         determine if it was successfully loaded.  If \a result is not
 431         NULL, a valid handle is returned.
 432     \retval KHM_ERROR_EXISTS The module is already loaded or has been
 433         already queued for loading.  If \a result is not NULL, a valid
 434         handle to the existing module instance is returned.
 435     \retval KHM_ERROR_NOT_FOUND If called with KMM_LM_FLAG_NOLOAD,
 436         indicates that the module has not been loaded.  Otherwise only
 437         returned when called with KMM_LM_FLAG_SYNC.  The module image
 438         was not found.  No handle is returned.
 439     \retval KHM_ERROR_INVALID_SIGNATURE Only returned when called with
 440         KMM_LM_FLAG_SYNC.  The module was signed with an invalid
 441         certificate.  No handle is returned.
 442     \retval KHM_ERROR_UNKNOWN Only returned when called with
 443         KMM_LM_FLAG_SYNC.  Some other error has occured.  No handle is
 444         returned.
 445
 446     \see \ref pi_fw_pm_load
 447     \see ::KMM_LM_FLAG_SYNC, ::KMM_LM_FLAG_NOLOAD
 448 */
 449 KHMEXP khm_int32   KHMAPI
 450 kmm_load_module(wchar_t * modname, khm_int32 flags, kmm_module * result);
 451
 452 /*! \brief Hold a handle to a module
 453
 454     Use kmm_release_module() to release the hold.
 455 */
 456 KHMEXP khm_int32   KHMAPI
 457 kmm_hold_module(kmm_module module);
 458
 459 /*! \brief Release a handle to a module
 460
 461     Release a held referece to a module that was returned in a call to
 462     kmm_load_module().
 463 */
 464 KHMEXP khm_int32   KHMAPI
 465 kmm_release_module(kmm_module m);
 466
 467 /*! \brief Query the state of a module
 468
 469     When loading a module asynchronously you can query the state of
 470     the loading process using this.  The return value is a status
 471     indicator.
 472
 473     \return The return value is one of the ::KMM_MODULE_STATES
 474         enumerations.
 475 */
 476 KHMEXP khm_int32   KHMAPI
 477 kmm_get_module_state(kmm_module m);
 478
 479 /*! \brief Unload a module
 480
 481     See the associated NetIDMgr Module Manager documentation on the
 482     sequence of events associated with unloading a module.
 483
 484     \see \ref pi_fw_pm_unload
 485 */
 486 KHMEXP khm_int32   KHMAPI
 487 kmm_unload_module(kmm_module module);
 488
 489 /*! \brief Loads the default modules as specified in the configuration
 490
 491     The configuration can specify the default set of modules to load.
 492     This function dispatches the necessary message for loading these
 493     modules and reutnrs.
 494 */
 495 KHMEXP khm_int32   KHMAPI
 496 kmm_load_default_modules(void);
 497
 498 /*! \brief Checks whether there are any pending loads
 499
 500     Returns TRUE if there are modules still waiting to be loaded.
 501 */
 502 KHMEXP khm_boolean  KHMAPI
 503 kmm_load_pending(void);
 504
 505 #ifdef _WIN32
 506
 507 /*! \brief Returns the Windows module handle from a handle to a NetIDMgr module.
 508     Although it is possible to obtain the Windows module handle and
 509     use it to call Windows API functions, it is not recommended to do
 510     so.  This is because that might cause the state of the module to
 511     change in ways which are inconsistent from the internal data
 512     structures that kmm maintains.
 513  */
 514 KHMEXP HMODULE     KHMAPI
 515 kmm_get_hmodule(kmm_module m);
 516 #endif
 517
 518 /*! \brief Hold a plugin
 519
 520     Obtains a hold on a plugin.  The plugin handle will remain valid
 521     until the hold is released with a call to kmm_release_plugin().
 522     No guarantees are made on the handle once the handle is released.
 523  */
 524 KHMEXP khm_int32   KHMAPI
 525 kmm_hold_plugin(kmm_plugin p);
 526
 527 /*! \brief Release a plugin
 528
 529     Releases a hold on a plugin obtained through a call to
 530     kmm_hold_plugin().  The plugin handle should no longer be
 531     considered valied once this is called.
 532  */
 533 KHMEXP khm_int32   KHMAPI
 534 kmm_release_plugin(kmm_plugin p);
 535
 536 /*! \brief Provide a plugin
 537
 538     This function must be called for each plugin that the module
 539     provides.
 540
 541     Note that this function returns immediately and does not
 542     initialize the plugin.  All plugins that are provided by a
 543     module will be initialized once the init_module() function
 544     returns.  If the plugin has dependencies, it will be kept in a
 545     held state until the plugins that it depends on are successfully
 546     initialized.  If the dependencies are not resolved (the dependent
 547     plugins are not loaded), then plugin will not be initialized.
 548
 549     If the plugin is not registered and \a plugin contains enough
 550     information to perform the registration, then it will be
 551     automatically registered.  However, if the plugin is not
 552     registered and cannot be registered using the provided
 553     information, the plugin will not be initialized properly.  Note
 554     that automatic registration will always register the plugin in the
 555     user configuration store.
 556
 557     The \a name and \a msg_proc members of \a plugin are required to
 558     have valid values.  The \a icon member may optionally be
 559     specified.  The other fields can be specified if the plugin should
 560     be automatically registered, however, the \a module field will be
 561     ignored and will be determined by the \a module handle.
 562
 563     \param[in] module Handle to this module that is providing the plugin.
 564     \param[in] plugin A plugin descriptor.
 565
 566     \retval KHM_ERROR_SUCCESS Succeeded.
 567     \retval KHM_ERROR_INVALID_OPERATION The function was not called
 568         during init_module()
 569     \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid
 570     \retval KHM_ERROR_DUPLICATE The plugin was already provided
 571
 572     \note This can only be called when handing init_module()
 573 */
 574 KHMEXP khm_int32   KHMAPI
 575 kmm_provide_plugin(kmm_module module, kmm_plugin_reg * plugin);
 576
 577 /*! \brief Query the state of a plugin.
 578
 579     \return One of ::_kmm_plugin_states
 580 */
 581 KHMEXP khm_int32   KHMAPI
 582 kmm_get_plugin_state(wchar_t * plugin);
 583
 584 /*! \defgroup kmm_reg Registration
 585
 586     The functions for managing plugin and module registration.  These
 587     functions are also available as static linked libraries for use by
 588     external applications which must register or unregister plugins or
 589     modules.
 590 @{*/
 591
 592 /*! \brief Obtain the configuration space for a named plugin
 593
 594     Note that the named plugin does not have to actually exist.
 595     Configuration spaces for plugins are based solely on the plugin
 596     name and hence can be accessed regardless of whether the specific
 597     plugin is loaded or not.
 598
 599     \param[in] flags Controls the options for opening the
 600         configuration space.  If KHM_FLAG_CREATE is specified, then
 601         the configuration space for the plugin named \a plugin wil be
 602         created if it doesn't already exist.  The \a flags parameter
 603         is directly passed into a call to khc_open_space().
 604
 605     \param[in] plugin Name of the plugin.  The name can not contain
 606         slashes.
 607
 608     \param[out] result Receives a configuration space handle.  The
 609         calling application should free the handle using
 610         khc_close_space().
 611
 612     \see khc_open_space()
 613     \see khc_close_space()
 614  */
 615 KHMEXP khm_int32   KHMAPI
 616 kmm_get_plugin_config(wchar_t * plugin, khm_int32 flags, khm_handle * result);
 617
 618 /*! \brief Obtain the configuration space or a named module
 619
 620     The named module does not have to actually exist.  Configuration
 621     spaces for modules are based on the basename of the module
 622     (including the extension).
 623
 624     \param[in] module Name of the module.
 625
 626     \param[in] flags The flags used to call khc_open_space().  You can
 627         use this to specify a particular configuration store if
 628         needed.
 629
 630     \param[out] result Receives the handle to a configuration space if
 631         successful.  Call khc_close_space() to close the handle.
 632
 633     \see khc_open_space()
 634     \see khc_close_space()
 635 */
 636 KHMEXP khm_int32   KHMAPI
 637 kmm_get_module_config(wchar_t * module, khm_int32 flags, khm_handle * result);
 638
 639 /*! \brief Retrieve a handle to the configuration space for plugins
 640
 641     The configuration space for plugins is a container which holds the
 642     configuration subspaces for all the plugins.  This is the config
 643     space which must be used to load a configuration space for a
 644     plugin.
 645
 646     \param[in] flags The flags to pass in to the call to
 647         khc_open_space().  The flags can be used to select a specific
 648         configuration store if needed.
 649
 650     \param[out] result Receives a handle to the configuration
 651         space. Call khc_close_space() to close the handle
 652
 653     \see khc_open_space()
 654     \see khc_close_space()
 655  */
 656 KHMEXP khm_int32   KHMAPI
 657 kmm_get_plugins_config(khm_int32 flags, khm_handle * result);
 658
 659 /*! \brief Retrieve the handle to the configuration space for modules
 660
 661     The configuration space for modules is a container which hold the
 662     configuration subspaces for all the modules.  Each module
 663     registration ends up in this subspace.
 664
 665     \param[in] flags The flags to pass in to the call to
 666         khc_open_space().  The flags can be used to select a specific
 667         configuration store if needed.
 668
 669     \param[out] result Receives a handle to the configuration space.
 670         Call khc_close_space() to close the handle.
 671
 672     \see khc_open_space()
 673     \see khc_close_space()
 674  */
 675 KHMEXP khm_int32   KHMAPI
 676 kmm_get_modules_config(khm_int32 flags, khm_handle * result);
 677
 678 /*! \brief Return information about a loaded module
 679
 680     The retrieves a block of information about a module.  Refer to
 681     ::kmm_module_info for information about the format of the returned
 682     data.
 683
 684     Note that the size of the required buffer is actually greater than
 685     the size of the ::kmm_module_info structure and accomodates the
 686     ::kmm_plugin_info structures and strings required to complete the
 687     information block.
 688
 689     Call the function with \a buffer set to NULL and \a cb_buffer
 690     pointing at a khm_size variable to obtain the required size of the
 691     buffer.
 692
 693     \param[in] module_name Name of a module
 694     \param[in] flags Flags indicating which types of information to
 695         return
 696     \param[out] buffer Points to a buffer that recieves information.
 697         Set this to NULL if only the size of the buffer is required.
 698     \param[in,out] On entry, contains the size of the buffer pointed
 699         to by \a buffer if \a buffer is not NULL. On exit, contains
 700         the required size of the buffer or the number of actual bytes
 701         copied.
 702
 703     \retval KHM_ERROR_SUCCESS The requested information was copied
 704     \retval KHM_ERROR_INVALID_PARAM One of the parameters was invalid
 705     \retval KHM_ERROR_TOO_LONG The buffer was not large enough or was
 706         NULL.  The number of bytes requied is in \a cb_buffer.
 707     \retval KHM_ERROR_NOT_FOUND The specified module is not a
 708         registered module.
 709  */
 710 KHMEXP khm_int32   KHMAPI
 711 kmm_get_module_info(wchar_t *  module_name, khm_int32 flags,
 712                     kmm_module_info * buffer, khm_size * cb_buffer);
 713
 714 /*! \brief Get information about a module
 715
 716     Similar to kmm_get_module_info(), but uses a module handle instead
 717     of a name, and uses internal buffers for providing string fields.
 718
 719     The information that is returned should be freed using a call to
 720     kmm_release_module_info_i().
 721
 722     \see kmm_release_module_info_i()
 723  */
 724 KHMEXP khm_int32   KHMAPI
 725 kmm_get_module_info_i(kmm_module module, kmm_module_info * info);
 726
 727 /*! \brief Release module information
 728
 729     Releases the information returned by a previous call to
 730     kmm_get_module_info_i().  The contents of the ::kmm_module_info
 731     structure should not have been modified in any way between calling
 732     kmm_get_module_info_i() and kmm_release_module_info_i().
 733  */
 734 KHMEXP khm_int32   KHMAPI
 735 kmm_release_module_info_i(kmm_module_info * info);
 736
 737 /*! \brief Obtain information about a plugin
 738
 739     Retrieve a block of information about a plugin.  See
 740     ::kmm_plugin_info for details about what information can be
 741     returned.  Note that some fields may not be available if the
 742     module is not loaded.
 743
 744     Note that the size of the required buffer is greater than the size
 745     of the ::kmm_plugin_info structure and accounts for strings as
 746     well.  Call kmm_get_plugin_info() with \a buffer set to NULL and
 747     \a cb_buffer set to point to a variable of type \a khm_size to
 748     obtain the required size of the structure.
 749
 750     \param[in] plugin_name Name of the plugin
 751     \param[out] buffer The buffer to receive the plugin information.
 752         Set to \a NULL if only the size of the buffer is required.
 753     \param[in,out] cb_buffer On entry, points to variable that
 754         specifies the size of the buffer pointed to by \a buffer is \a
 755         buffer is not \a NULL.  On exit, holds the number of bytes
 756         copied or the required size of the buffer.
 757
 758     \retval KHM_ERROR_SUCCESS The requested information was
 759         successfully copied to the \a buffer
 760     \retval KHM_ERROR_TOO_LONG The buffer was either \a NULL or
 761         insufficient to hold the requested information.  The required
 762         size of the buffer was stored in \a cb_buffer
 763     \retval KHM_ERROR_INVALID_PARAM One or more parameters were
 764         invlaid.
 765     \retval KHM_ERROR_NOT_FOUND The specified plugin was not found
 766         among the registered plugins.
 767 */
 768 KHMEXP khm_int32   KHMAPI
 769 kmm_get_plugin_info(wchar_t * plugin_name,
 770                     kmm_plugin_info * buffer,
 771                     khm_size * cb_buffer);
 772
 773 /*! \brief Obtain information about a plugin using a plugin handle
 774
 775     Similar to kmm_get_plugin_info() but uses a plugin handle instead
 776     of a plugin name.  If the call is successful, the \a info
 777     structure will be filled with information about the plugin.  The
 778     returned info should not be modified in any way and may contain
 779     pointers to internal buffers.
 780
 781     The returned information must be released with a call to
 782     kmm_release_plugin_info_i().
 783  */
 784 KHMEXP khm_int32   KHMAPI
 785 kmm_get_plugin_info_i(kmm_plugin p, kmm_plugin_info * info);
 786
 787 /*! \brief Release plugin information returned by kmm_get_plugin_info_i
 788
 789     The information returned by kmm_get_plugin_info_i() should not be
 790     modified in any way before calling kmm_release_plugin_info_i().
 791     Once the call completes, the contents of \a info will be
 792     initialized to zero.
 793  */
 794 KHMEXP khm_int32   KHMAPI
 795 kmm_release_plugin_info_i(kmm_plugin_info * info);
 796
 797 /*! \brief Enumerates plugins
 798
 799     Enumerates through known plugins.  This list may not include
 800     plugins which were not loaded by NetIDMgr in this session.
 801
 802     If the call is successful, a handle to the next plugin in the list
 803     will be placed in \a p_next.  The returned handle must be freed
 804     with a call to kmm_release_plugin().
 805
 806     If the \a p parameter is set to NULL, then the first plugin handle
 807     will be placed in \a p_next.  The handles will not be returned in
 808     any specific order.  In addition, the enumeration may not include
 809     all known plugins if the list of plugins changes during
 810     enumeration.
 811  */
 812 KHMEXP khm_int32   KHMAPI
 813 kmm_get_next_plugin(kmm_plugin p, kmm_plugin * p_next);
 814
 815 /*! \brief Enables or disables a plugin
 816
 817     This function currently does not take effect immediately.  However
 818     it marks the plugin as enabled or disabled so that the next time
 819     NetIDMgr starts, the module manager will act accordingly.
 820
 821     \param[in] p Handle to the plugin
 822
 823     \param[in] enable If non-zero, the plugin will be marked as
 824         enabled.  Otherwise the plugin will be marked as disabled.
 825  */
 826 KHMEXP khm_int32   KHMAPI
 827 kmm_enable_plugin(kmm_plugin p, khm_boolean enable);
 828
 829 /*! \brief Register a plugin
 830
 831     The \a plugin member defines the plugin to be registered.  The \a
 832     msg_proc and \a icon members of the structure are ignored.
 833
 834     At the time kmm_register_plugin() is called, the module specified
 835     by \a module member of the \a plugin parameter must have been already
 836     registered.  Otherwise the function call fails.
 837
 838     If the plugin has already been registered, then all the fields in
 839     the plugin registration will be updated to be in sync with the
 840     information provided in the \a plugin parameter.  The failure
 841     counts and associated statistics will not be reset when the
 842     configuration information is updated.
 843
 844     If the plugin has not been registered, the a new registration
 845     entry is created in the configuration space indicated by the \a
 846     config_flags parameter.  In addition, the plugin will be added to
 847     the list of plugins associated with the owning module.
 848
 849     Note that the module that owns the plugin must be registered in
 850     the same configuration store as the plugin.
 851
 852     \param[in] plugin Registration info for the plugin.  The \a
 853         msg_proc and \a icon members are ignored.  All other fields
 854         are required.  The \a description member should be localized
 855         to the system locale when registering a plugin in the machine
 856         configuration store and should be localized to the user locale
 857         when registering a plugin in the user configuration store.
 858     \param[in] config_flags Flags for the configuration provider.
 859         These flags are used verbatim to call khc_open_space(), hence
 860         they may be used to pick whether or not the registration is
 861         per machine or per user.
 862
 863     \see kmm_register_module()
 864  */
 865 KHMEXP khm_int32   KHMAPI
 866 kmm_register_plugin(kmm_plugin_reg * plugin, khm_int32 config_flags);
 867
 868 /*! \brief Register a module
 869
 870     The \a module parameter specifies the parameters for the module
 871     registration.
 872
 873     The \a plugin_info member should point to an array of
 874     ::kmm_plugin_info structures unless the \a n_plugins member is
 875     zero, in which case \a plugin_info can be \a NULL.  Plugins can be
 876     registered separately using kmm_register_plugin().
 877
 878     \param[in] module Information about the module.  The name and path
 879         fields are required. The \a plugin_info field can only be \a
 880         NULL if \a n_plugins is zero.
 881
 882     \param[in] config_flags Flags used to call khc_open_space().  This
 883         can be used to choose the configuration store in which the
 884         module registration will be performed.
 885   */
 886 KHMEXP khm_int32   KHMAPI
 887 kmm_register_module(kmm_module_reg * module, khm_int32 config_flags);
 888
 889 /*! \brief Unregister a plugin
 890
 891     Registration information associated with the plugin will be
 892     removed.  In addtion, the plugin will be removed from the list of
 893     plugins provided by the owner module.
 894
 895     \param[in] plugin Names the plugin to be removed
 896     \param[in] config_flags Flags used to call khc_open_space(). Can
 897         be used to choose the configuraiton store that is affected by
 898         the call.
 899
 900     \note kmm_unregister_plugin() has no effect on whether the plugin
 901         is loaded or not.  The caller must make sure that the plugin
 902         is unloaded and the associated module is either also unloaded
 903         or in a state where the plugin can be unregistered.
 904  */
 905 KHMEXP khm_int32   KHMAPI
 906 kmm_unregister_plugin(wchar_t * plugin, khm_int32 config_flags);
 907
 908 /*! \brief Unregister a module
 909
 910     Registration information associated with the module as well as all
 911     the plugins provided by the module will be removed from the
 912     configuration store.
 913
 914     \param[in] module Names the module to be removed
 915
 916     \param[in] config_flags Flags used to call khc_open_space().  Can
 917         be used to choose the configuration store affected by the
 918         call.
 919
 920     \note kmm_unregister_module() has no effect on the loaded state of
 921         the module.  The caller should make sure that the module is
 922         unloaded and in a state where it can be unregistered.
 923  */
 924 KHMEXP khm_int32   KHMAPI
 925 kmm_unregister_module(wchar_t * module, khm_int32 config_flags);
 926
 927 /*@}*/ /* kmm_reg */
 928
 929 /*! \defgroup kmm_loc Internationalization support
 930
 931     See \ref pi_localization for more information about
 932     internationalization.
 933
 934 @{*/
 935
 936 /*! \brief Locale descriptor record
 937
 938     See kmm_set_locale()
 939 */
 940 typedef struct tag_kmm_module_locale {
 941     khm_ui_4    language; /*!< A language ID.  On Windows, you can use the
 942                             MAKELANGID macro to generate this value. */
 943     wchar_t *   filename; /*!< The filename corresponding to this language.
 944                             Use NULL to indicate that resources for this
 945                             language are to be found in the main module. */
 946     khm_int32   flags;    /*!< Flags.  Combination of KMM_MLOC_FLAG_* */
 947 } kmm_module_locale;
 948
 949 #define LOCALE_DEF(language_id, filename, flags) {language_id, filename, flags}
 950
 951 /*! \brief Default (fallback) locale
 952 */
 953 #define KMM_MLOC_FLAG_DEFAULT 1
 954
 955
 956 /*! \brief Sets the locale for a loaded module.
 957
 958     The given locale records are searched in the given order until a
 959     locale that matches the current user locale is found.  If no
 960     locales match, then the first locale with the
 961     ::KMM_MLOC_FLAG_DEFAULT flag set will be loaded.  If no locales
 962     have that flag set, then the first locale is loaded.
 963
 964     You can obtain a handle to the loaded library using
 965     kmm_get_resource_hmodule().  This function does not return until a
 966     matched library is loaded.
 967
 968     Note that the ::kmm_module_locale structure only specifies a
 969     module name for the resource module.  This resource module must
 970     exist in the same directory as the \a module.
 971
 972     \param[in] module The module handle
 973     \param[in] locales An array of ::kmm_module_locale objects
 974     \param[in] n_locales The number of objects in the array pointed to by \a locales
 975
 976     \retval KHM_ERROR_SUCCESS Succeeded.
 977     \retval KHM_ERROR_NOT_FOUND A matching locale resource library was not found.
 978     \retval KHM_ERROR_INVALID_OPERATION The function was called on a module which is currently not being initalized.
 979
 980     \see \ref pi_localization
 981     \see kmm_get_resource_hmodule()
 982
 983     \note This can only be called when handing init_module()
 984 */
 985 KHMEXP khm_int32   KHMAPI
 986 kmm_set_locale_info(kmm_module module,
 987                     kmm_module_locale * locales,
 988                     khm_int32 n_locales);
 989
 990 #ifdef _WIN32
 991
 992 /*! \brief Return the Windows module handle of the resource library of a NetIDMgr module.
 993
 994     NetIDMgr allows the specification of an alternate resource library
 995     that will be used to load localized resources from.  This function
 996     returns a handle to this library.
 997
 998     While you can use the convenience macros to access resources in a
 999     localization library using the module handle, it is recommended,
1000     for performance reasons, to use this function to obtain the handle
1001     to the resource library and then use that handle in calls to
1002     LoadString, LoadImage etc. directly.
1003 */
1004 KHMEXP HMODULE     KHMAPI
1005 kmm_get_resource_hmodule(kmm_module m);
1006
1007 /*! \name Convenience Macros
1008 @{*/
1009 /*! \brief Convenience macro for using calling LoadAccelerators using a module handle
1010
1011     \param[in] module A handle to a loaded module.  The corresponding resource
1012         module will be located through a call to kmm_get_resource_hmodule()
1013 */
1014 #define kmm_LoadAccelerators(module, lpTableName) \
1015     (LoadAccelerators(kmm_get_resource_hmodule(module), lpTableName))
1016
1017 /*! \brief Convenience macro for using calling LoadBitmap using a module handle
1018
1019     \param[in] module A handle to a loaded module.  The corresponding resource
1020         module will be located through a call to kmm_get_resource_hmodule()
1021 */
1022 #define kmm_LoadBitmap(module, lpBitmapName) \
1023     (LoadBitmap(kmm_get_resource_hmodule(module), lpBitmapName))
1024
1025 /*! \brief Convenience macro for using calling LoadImage using a module handle
1026
1027     \param[in] module A handle to a loaded module.  The corresponding resource
1028         module will be located through a call to kmm_get_resource_hmodule()
1029 */
1030 #define kmm_LoadImage(module, lpszName, uType, cxDesired, cyDesired, fuLoad) \
1031     (LoadImage(kmm_get_resource_hmodule(module), lpszName, uType, cxDesired, cyDesired, fuLoad))
1032
1033 /*! \brief Convenience macro for using calling LoadCursor using a module handle
1034
1035     \param[in] module A handle to a loaded module.  The corresponding resource
1036         module will be located through a call to kmm_get_resource_hmodule()
1037 */
1038 #define kmm_LoadCursor(module, lpCursorName) \
1039     (LoadCursor(kmm_get_resource_hmodule(module), lpCursorName))
1040
1041 /*! \brief Convenience macro for using calling LoadIcon using a module handle
1042
1043     \param[in] module A handle to a loaded module.  The corresponding resource
1044         module will be located through a call to kmm_get_resource_hmodule()
1045 */
1046 #define kmm_LoadIcon(module, lpIconName) \
1047     (LoadIcon(kmm_get_resource_hmodule(module), lpIconName))
1048
1049 /*! \brief Convenience macro for using calling LoadMenu using a module handle
1050
1051     \param[in] module A handle to a loaded module.  The corresponding resource
1052         module will be located through a call to kmm_get_resource_hmodule()
1053 */
1054 #define kmm_LoadMenu(module, lpMenuName) \
1055     (LoadMenu(kmm_get_resource_hmodule(module), lpMenuName))
1056
1057 /*! \brief Convenience macro for using calling LoadString using a module handle
1058
1059     \param[in] module A handle to a loaded module.  The corresponding resource
1060         module will be located through a call to kmm_get_resource_hmodule()
1061 */
1062 #define kmm_LoadString(module, uID, lpBuffer, nBufferMax) \
1063     (LoadString(kmm_get_resource_hmodule(module), uID, lpBuffer, nBufferMax))
1064 /*@}*/ /* Convenience Macros */
1065 #endif
1066 /*@}*/ /* group kmm_loc */
1067 /*@}*/ /* group kmm */
1068 #endif