ism/src/scim_helper_module.h

   1 /**
   2  * @file scim_helper_module.h
   3  * @brief Defines scim::HelperModule and it's related types.
   4  *
   5  * scim::HelperModule is a class used to load Client Helper modules.
   6  *
   7  */
   8
   9 /* ISF is based on SCIM 1.4.7 and extended for supporting more mobile fitable. */
  10
  11 /*
  12  * Smart Common Input Method
  13  *
  14  * Copyright (c) 2004-2005 James Su <suzhe@tsinghua.org.cn>
  15  *
  16  *
  17  * This library is free software; you can redistribute it and/or
  18  * modify it under the terms of the GNU Lesser General Public
  19  * License as published by the Free Software Foundation; either
  20  * version 2 of the License, or (at your option) any later version.
  21  *
  22  * This library is distributed in the hope that it will be useful,
  23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25  * GNU Lesser General Public License for more details.
  26  *
  27  * You should have received a copy of the GNU Lesser General Public
  28  * License along with this program; if not, write to the
  29  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  30  * Boston, MA  02111-1307  USA
  31  *
  32  * $Id: scim_helper_module.h,v 1.6 2005/01/10 08:30:54 suzhe Exp $
  33  */
  34
  35 #ifndef __SCIM_HELPER_MODULE_H
  36 #define __SCIM_HELPER_MODULE_H
  37
  38 namespace scim {
  39
  40 /**
  41  * @addtogroup Helper
  42  * @ingroup InputServiceFramework
  43  * @{
  44  */
  45
  46 /**
  47  * @brief Get the number of Helpers in this module.
  48  *
  49  * A helper module can have multiple Helpers in it.
  50  * But each helper will run in its own process space.
  51  *
  52  * There must be a function called "scim_helper_module_number_of_helpers"
  53  * in each helper module which complies with this prototype.
  54  * This function name can have a prefix like kbd_LTX_,
  55  * in which "kbd" is the module's name.
  56  */
  57 typedef unsigned int  (*HelperModuleNumberOfHelpersFunc) (void);
  58
  59 /**
  60  * @brief Get the information of a Helper.
  61  *
  62  * There must be a function called "scim_helper_module_get_helper_info"
  63  * in each helper module which complies with this prototype.
  64  * This function name can have a prefix like kbd_LTX_,
  65  * in which "kbd" is the module's name.
  66  *
  67  * @param idx The index of this helper, must between 0 to (the number of helpers) - 1.
  68  * @param info The HelperInfo object to store the information.
  69  * @return true if this Helper is valid and the correct information is stored into info.
  70  */
  71 typedef bool (*HelperModuleGetHelperInfoFunc)   (unsigned int idx, HelperInfo &info);
  72
  73 /**
  74  * @brief Get the language of a Helper.
  75  *
  76  * There must be a function called "scim_helper_module_get_helper_language"
  77  * in each helper module which complies with this prototype.
  78  * This function name can have a prefix like kbd_LTX_,
  79  * in which "kbd" is the module's name.
  80  *
  81  * @param idx The index of this helper, must between 0 to (the number of helpers) - 1.
  82  * @return this Helper's language.
  83  */
  84 typedef String (*HelperModuleGetHelperLangFunc)   (unsigned int idx);
  85
  86 /**
  87  * @brief Run a specific Helper.
  88  *
  89  * This function will be called within an independent process.
  90  *
  91  * There must be a function called "scim_helper_module_run_helper"
  92  * in each helper module which complies with this prototype.
  93  * This function name can have a prefix like kbd_LTX_,
  94  * in which "kbd" is the module's name.
  95  *
  96  * @param config The Config object should be used to read/write configurations.
  97  * @param uuid The UUID of the Helper to be run.
  98  * @param display The display in which this helper should run.
  99  */
 100 typedef void (*HelperModuleRunHelperFunc)       (const String &uuid, const ConfigPointer &config, const String &display);
 101
 102
 103 /**
 104  * @brief The class used to load a Helper module and run its Helpers.
 105  *
 106  * This class should not be used directly. HelperManager should be used instead.
 107  */
 108 class HelperModule
 109 {
 110     Module                          m_module;
 111
 112     HelperModuleNumberOfHelpersFunc m_number_of_helpers;
 113     HelperModuleGetHelperInfoFunc   m_get_helper_info;
 114     HelperModuleGetHelperLangFunc   m_get_helper_lang;
 115     HelperModuleRunHelperFunc       m_run_helper;
 116
 117     HelperModule (const HelperModule &);
 118     HelperModule & operator= (const HelperModule &);
 119
 120 public:
 121     /**
 122      * @brief Constructor.
 123      *
 124      * @param name The name of the Helper module to be loaded.
 125      */
 126     HelperModule (const String &name = String (""));
 127
 128     /**
 129      * @brief Load a Helper module.
 130      *
 131      * If a module has already been loaded, then it'll be unloaded first.
 132      *
 133      * @param name The name of the Helper module to be loaded.
 134      * @return true if success.
 135      */
 136     bool load (const String &name);
 137
 138     /**
 139      * @brief Unload the module.
 140      *
 141      * @return true if success.
 142      */
 143     bool unload ();
 144
 145     /**
 146      * @brief Check if a Helper module has been loaded successfully.
 147      *
 148      * @return true if a module has been loaded successfully.
 149      */
 150     bool valid () const;
 151
 152     /**
 153      * @brief Get the number of helpers supported by this module.
 154      *
 155      * @return the number of helpers supported by this module.
 156      */
 157     unsigned int number_of_helpers () const;
 158
 159     /**
 160      * @brief The the information of a specific helper.
 161      *
 162      * @param idx The index of the helper, must between 0 to number_of_helpers () - 1.
 163      * @param info The HeperInfo object to store the information.
 164      * @return true if this helper is ok and the information is stored into info successfully.
 165      */
 166     bool get_helper_info (unsigned int idx, HelperInfo &info) const;
 167
 168     /**
 169      * @brief The language of a specific helper.
 170      *
 171      * @param idx The index of the helper, must between 0 to number_of_helpers () - 1.
 172      * @return this helper's language.
 173      */
 174     String get_helper_lang (unsigned int idx) const;
 175
 176     /**
 177      * @brief Run a specific helper.
 178      *
 179      * The helper should be run in an independent process, this function will not return
 180      * until the helper exits.
 181      *
 182      * @param config The Config object to be used to read configurations.
 183      * @param uuid The UUID of the helper, which is returned by get_helper_info ().
 184      * @param display The display in which this helper should run.
 185      */
 186     void run_helper (const String &uuid, const ConfigPointer &config, const String &display) const;
 187 };
 188
 189 /**
 190  * @brief Get a name list of currently available Helper modules.
 191  * @param mod_list - the result list will be stored here.
 192  * @return the number of the modules, equal to mod_list.size ().
 193  */
 194 int scim_get_helper_module_list (std::vector <String> &mod_list);
 195 /**  @} */
 196
 197 } // namespace scim
 198
 199 #endif //__SCIM_HELPER_MODULE_H
 200
 201 /*
 202 vi:ts=4:nowrap:ai:expandtab
 203 */
 204