src/WINNT/kfw/inc/netidmgr/kplugin.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_KPLUGIN_H
  28 #define __KHIMAIRA_KPLUGIN_H
  29
  30 #include<kmm.h>
  31 #include<kherror.h>
  32
  33 /*! \addtogroup kmm
  34 @{*/
  35 /*! \defgroup kplugin NetIDMgr Plugin Callbacks
  36
  37 See the following related documentation pages for more information
  38 about NetIDMgr plugins.
  39
  40 These are prototypes of functions that must be implemented by a NetIDMgr
  41 plugin.
  42
  43 - \ref plugins
  44 @{*/
  45
  46 /*! \brief Initialize the module
  47
  48     This is the first callback function to be called in a module.
  49     Perform all the required intialization when this is called.  As
  50     mentioned in \ref plugins, you should not attempt to call any
  51     NetIDMgr API function from DLLMain or other initialization code
  52     other than this one.
  53
  54     You should use this call back to register the plugins that will be
  55     implemented in this module and to notify the plugin manager of any
  56     resource libraries that this module will use.
  57
  58     Call:
  59     - kmm_set_locale() : to set the notify the plugin manager of the
  60       locale specifc resource libraries that are used by this module.
  61     - kmm_provide_plugin() : to register each plugin that is
  62       implemented in this module.
  63
  64     This function is called in the context of the current user, from
  65     the plug-in manager thread.  This same thread is used by the
  66     plug-in manager to load and initialize all the modules for a
  67     session.
  68
  69     The name of the callback must be init_module().  The calling
  70     convention is KHMAPI, which is currently __stdcall.
  71
  72     If this function does not register any plugins, the plugin manager
  73     will immediately call exit_module() and unload the module even if
  74     the init_module() function completes successfully.
  75
  76     \return Return the following values to indicate whether the module
  77         successfully initialized or not.
  78         - KHM_ERROR_SUCCESS : Succeeded. The module manager will call
  79             init_plugin() for each of the registered plugins for the
  80             module.
  81         - any other error code: Signals that the module did not
  82             successfully initialize.  The plugin manager will
  83             immediately call exit_module() and then unload the module.
  84
  85     \note This callback is required.
  86 */
  87 KHMEXP khm_int32 KHMAPI init_module(kmm_module h_module);
  88
  89 /*! \brief Type for init_module() */
  90 typedef khm_int32 (KHMAPI *init_module_t)(kmm_module);
  91
  92 #if defined(_WIN64)
  93 #define EXP_INIT_MODULE "init_module"
  94 #elif defined(_WIN32)
  95 #define EXP_INIT_MODULE "_init_module@4"
  96 #else
  97 #error  EXP_INIT_MODULE not defined for platform
  98 #endif
  99
 100 /*! \brief Plugin procedure
 101
 102     This is the message processor for a plugin.  See \ref pi_fw_pnm_p
 103     for more information.
 104
 105     Essentially, this is a message subscriber for KMQ messages.
 106 */
 107 KHMEXP khm_int32 KHMAPI _plugin_proc(khm_int32 msg_type, khm_int32 msg_subtype, khm_ui_4 uparam, void * vparam);
 108
 109 /*! \brief Type for init_plugin() */
 110 typedef kmq_callback_t _plugin_proc_t;
 111
 112 /*! \brief Exit a module
 113
 114     This is the last callback function that the NetIDMgr module
 115     manager calls before unloading the module.  When this function is
 116     called, all of the plugins for the module have already been
 117     stopped.  However, any localization libraries that were loaded as
 118     a result of init_module() calling kmm_set_locale_info() will still
 119     be loaded.  These localization libraries will be unloaded
 120     immediately after this callback returns.
 121
 122     Use this callback to perform any required cleanup tasks.  However,
 123     it is advisable that each plugin perform its own cleanup tasks,
 124     since each plugin may be stopped independently of others.
 125
 126     \return The return value of this function is ignored.
 127
 128     \note This callback is not required.
 129 */
 130 KHMEXP khm_int32 KHMAPI exit_module(kmm_module h_module);
 131
 132 /*! \brief Type for exit_module() */
 133 typedef khm_int32 (KHMAPI *exit_module_t)(kmm_module);
 134
 135 #if defined(_WIN64)
 136 #define EXP_EXIT_MODULE "exit_module"
 137 #elif defined(_WIN32)
 138 #define EXP_EXIT_MODULE "_exit_module@4"
 139 #else
 140 #error  EXP_EXIT_MODULE not defined for platform
 141 #endif
 142
 143 /*@}*/
 144 /*@}*/
 145
 146 #endif