1 /** @file scim_filter_module.h 2 * @brief definition of FilterModule related classes. 3 */ 4 5 /* 6 * Smart Common Input Method 7 * 8 * Copyright (c) 2005 James Su <suzhe@tsinghua.org.cn> 9 * 10 * 11 * This library is free software; you can redistribute it and/or 12 * modify it under the terms of the GNU Lesser General Public 13 * License as published by the Free Software Foundation; either 14 * version 2 of the License, or (at your option) any later version. 15 * 16 * This library is distributed in the hope that it will be useful, 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 19 * GNU Lesser General Public License for more details. 20 * 21 * You should have received a copy of the GNU Lesser General Public 22 * License along with this program; if not, write to the 23 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 24 * Boston, MA 02111-1307 USA 25 * 26 * $Id: scim_filter_module.h,v 1.7 2005/10/06 18:02:06 liuspider Exp $ 27 */ 28 29 #ifndef __SCIM_FILTER_MODULE_H 30 #define __SCIM_FILTER_MODULE_H 31 32 namespace scim { 33 /** 34 * @addtogroup IMEngine 35 * @{ 36 */ 37 38 /** 39 * @brief Initialize a Filter Module. 40 * 41 * There must be a function called "scim_filter_module_init" 42 * in each filter module which complies with this prototype. 43 * This function name can have a prefix like sctc_LTX_, 44 * in which "sctc" is the module's name. 45 * 46 * If a filter needs services from other IMEngineFactory objects, it should 47 * obtain the pointer of these IMEngineFactory objects from the given BacnEnd 48 * pointer. But please note that, those IMEngineFactory objects may not be loaded yet, 49 * when initializing this Filter module. 50 * So the pointers of available IMEngineFactory objects should only be queried from 51 * the BackEnd at the first time to used by this Filter. 52 * 53 * @param config a ConfigBase instance to maintain the configuration. 54 * 55 * @return the number of filters provided by this module. 56 */ 57 typedef unsigned int (*FilterModuleInitFunc) (const ConfigPointer &config); 58 59 /** 60 * @brief Create an object of this FilterFactory class 61 * 62 * There must be a function called "scim_filter_module_create_filter" 63 * which complies with this prototype. 64 * This function name can have a prefix like sctc_LTX_, 65 * in which "sctc" is the module's name. 66 * 67 * A new FilterFactory object should be returned for each call. Because 68 * multiple objects would be used at the same time. 69 * 70 * @param index the index of the FilterFactory to be used to create the object. 71 * Must between 0 and (number_of_filters - 1). 72 * @param backend the BackEnd instance which holds all real IMEngineFactory objects. 73 * Some filter may want to use other IMEngineFactory object 74 * to do some job, eg. inverse convert. 75 * 76 * @return the pointer of the FilterFactory object. 77 */ 78 typedef FilterFactoryPointer (*FilterModuleCreateFilterFunc) (unsigned int index); 79 80 /** 81 * @brief Get basic information of the FilterFactory class provided by this module. 82 * 83 * There must be a function called "scim_filter_module_get_filter_info" 84 * which complies with this prototype. 85 * This function name can have a prefix like sctc_LTX_, 86 * in which "sctc" is the module's name. 87 * 88 * 89 * @param index The index of the FilterFactory to be queried. 90 * 91 * @param info The object to hold the information. 92 * @param index the index of the Filter to be queried. 93 * 94 * @return The uuid of this FilterFactory class. 95 */ 96 typedef bool (*FilterModuleGetFilterInfoFunc) (unsigned int index, FilterInfo &info); 97 98 /** 99 * @brief The class to manipulate the Filter modules. 100 * 101 * This is a wrapper of scim::Module class, which is specially 102 * for manipulating the Filter modules. 103 */ 104 class FilterModule 105 { 106 Module m_module; 107 108 FilterModuleInitFunc m_filter_init; 109 FilterModuleCreateFilterFunc m_filter_create_filter; 110 FilterModuleGetFilterInfoFunc m_filter_get_filter_info; 111 112 unsigned int m_number_of_filters; 113 114 FilterModule (const FilterModule &); 115 FilterModule & operator= (const FilterModule &); 116 117 public: 118 /** 119 * @brief Default constructor. 120 */ 121 FilterModule (); 122 123 /** 124 * @brief Constructor. 125 * @param name the module's name, eg. "sctc". 126 * @param config a ConfigBase instance to maintain the configuration. 127 */ 128 FilterModule (const String &name, const ConfigPointer &config); 129 130 /** 131 * @brief Load a Filter Module by its name. 132 * 133 * Load a module into memory. 134 * If another module has been loaded into this object, 135 * then the old module will be unloaded first. 136 * If the old module is resident, false will be returned, 137 * and the old module will be untouched. 138 * 139 * @param name - the name of the Filter Module. 140 * @param config a ConfigBase instance to maintain the configuration. 141 * 142 * @return true if success. 143 */ 144 bool load (const String &name, const ConfigPointer &config); 145 146 /** 147 * @brief Unload the Filter Module. 148 * @return true if sucessfully unloaded. 149 */ 150 bool unload (); 151 152 /** 153 * @brief Check if a module is loaded and initialized successfully. 154 * @return true if a module is already loaded and initialized successfully. 155 */ 156 bool valid () const; 157 158 /** 159 * @brief Get how many Filter factories supported by this module. 160 * 161 * @return the number of Filter factories. 162 */ 163 unsigned int number_of_filters () const; 164 165 /** 166 * @brief Create an object for a Filter factory. 167 * 168 * @param index The index of the Filter factory, 169 * must be less than the result of number_of_factories method 170 * and greater than or equal to zero. 171 * @return A smart pointer to the factory object, NULL if failed. 172 */ 173 FilterFactoryPointer create_filter (unsigned int index) const; 174 175 /** 176 * @brief Get basic information of the FilterFactory class provided by this module. 177 * 178 * @param index The index of the Filter factory to be queried. 179 * @param info The result will be stored in this parameter. 180 * 181 * @return whether the info is successfully retrieved 182 */ 183 bool get_filter_info (unsigned int index, FilterInfo &info) const; 184 }; 185 186 /** 187 * @brief Get a name list of currently available Filter modules. 188 * @param mod_list - the result list will be stored here. 189 * @return the number of the modules, equal to mod_list.size (). 190 */ 191 int scim_get_filter_module_list (std::vector <String> &mod_list); 192 193 /** @} */ 194 195 } // namespace scim 196 197 #endif //__SCIM_FILTER_MODULE_H 198 199 /* 200 vi:ts=4:ai:nowrap:expandtab 201 */ 202 203