1 /* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef PINYINIME_INCLUDE_ANDPYIME_H__ 18 #define PINYINIME_INCLUDE_ANDPYIME_H__ 19 20 #include <stdlib.h> 21 #include "./dictdef.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 namespace ime_pinyin { 28 29 /** 30 * Open the decoder engine via the system and user dictionary file names. 31 * 32 * @param fn_sys_dict The file name of the system dictionary. 33 * @param fn_usr_dict The file name of the user dictionary. 34 * @return true if open the decoder engine successfully. 35 */ 36 bool im_open_decoder(const char *fn_sys_dict, const char *fn_usr_dict); 37 38 /** 39 * Open the decoder engine via the system dictionary FD and user dictionary 40 * file name. Because on Android, the system dictionary is embedded in the 41 * whole application apk file. 42 * 43 * @param sys_fd The file in which the system dictionary is embedded. 44 * @param start_offset The starting position of the system dictionary in the 45 * file sys_fd. 46 * @param length The length of the system dictionary in the file sys_fd, 47 * counted in byte. 48 * @return true if succeed. 49 */ 50 bool im_open_decoder_fd(int sys_fd, long start_offset, long length, 51 const char *fn_usr_dict); 52 53 /** 54 * Close the decoder engine. 55 */ 56 void im_close_decoder(); 57 58 /** 59 * Set maximum limitations for decoding. If this function is not called, 60 * default values will be used. For example, due to screen size limitation, 61 * the UI engine of the IME can only show a certain number of letters(input) 62 * to decode, and a certain number of Chinese characters(output). If after 63 * user adds a new letter, the input or the output string is longer than the 64 * limitations, the engine will discard the recent letter. 65 * 66 * @param max_sps_len Maximum length of the spelling string(Pinyin string). 67 * @max_hzs_len Maximum length of the decoded Chinese character string. 68 */ 69 void im_set_max_lens(size_t max_sps_len, size_t max_hzs_len); 70 71 /** 72 * Flush cached data to persistent memory. Because at runtime, in order to 73 * achieve best performance, some data is only store in memory. 74 */ 75 void im_flush_cache(); 76 77 /** 78 * Use a spelling string(Pinyin string) to search. The engine will try to do 79 * an incremental search based on its previous search result, so if the new 80 * string has the same prefix with the previous one stored in the decoder, 81 * the decoder will only continue the search from the end of the prefix. 82 * If the caller needs to do a brand new search, please call im_reset_search() 83 * first. Calling im_search() is equivalent to calling im_add_letter() one by 84 * one. 85 * 86 * @param sps_buf The spelling string buffer to decode. 87 * @param sps_len The length of the spelling string buffer. 88 * @return The number of candidates. 89 */ 90 size_t im_search(const char* sps_buf, size_t sps_len); 91 92 /** 93 * Make a delete operation in the current search result, and make research if 94 * necessary. 95 * 96 * @param pos The posistion of char in spelling string to delete, or the 97 * position of spelling id in result string to delete. 98 * @param is_pos_in_splid Indicate whether the pos parameter is the position 99 * in the spelling string, or the position in the result spelling id string. 100 * @return The number of candidates. 101 */ 102 size_t im_delsearch(size_t pos, bool is_pos_in_splid, 103 bool clear_fixed_this_step); 104 105 /** 106 * Reset the previous search result. 107 */ 108 void im_reset_search(); 109 110 /** 111 * Add a Pinyin letter to the current spelling string kept by decoder. If the 112 * decoder fails in adding the letter, it will do nothing. im_get_sps_str() 113 * can be used to get the spelling string kept by decoder currently. 114 * 115 * @param ch The letter to add. 116 * @return The number of candidates. 117 */ 118 size_t im_add_letter(char ch); 119 120 /** 121 * Get the spelling string kept by the decoder. 122 * 123 * @param decoded_len Used to return how many characters in the spelling 124 * string is successfully parsed. 125 * @return The spelling string kept by the decoder. 126 */ 127 const char *im_get_sps_str(size_t *decoded_len); 128 129 /** 130 * Get a candidate(or choice) string. 131 * 132 * @param cand_id The id to get a candidate. Started from 0. Usually, id 0 133 * is a sentence-level candidate. 134 * @param cand_str The buffer to store the candidate. 135 * @param max_len The maximum length of the buffer. 136 * @return cand_str if succeeds, otherwise NULL. 137 */ 138 char16* im_get_candidate(size_t cand_id, char16* cand_str, 139 size_t max_len); 140 141 /** 142 * Get the segmentation information(the starting positions) of the spelling 143 * string. 144 * 145 * @param spl_start Used to return the starting posistions. 146 * @return The number of spelling ids. If it is L, there will be L+1 valid 147 * elements in spl_start, and spl_start[L] is the posistion after the end of 148 * the last spelling id. 149 */ 150 size_t im_get_spl_start_pos(const uint16 *&spl_start); 151 152 /** 153 * Choose a candidate and make it fixed. If the candidate does not match 154 * the end of all spelling ids, new candidates will be provided from the 155 * first unfixed position. If the candidate matches the end of the all 156 * spelling ids, there will be only one new candidates, or the whole fixed 157 * sentence. 158 * 159 * @param cand_id The id of candidate to select and make it fixed. 160 * @return The number of candidates. If after the selection, the whole result 161 * string has been fixed, there will be only one candidate. 162 */ 163 size_t im_choose(size_t cand_id); 164 165 /** 166 * Cancel the last selection, or revert the last operation of im_choose(). 167 * 168 * @return The number of candidates. 169 */ 170 size_t im_cancel_last_choice(); 171 172 /** 173 * Get the number of fixed spelling ids, or Chinese characters. 174 * 175 * @return The number of fixed spelling ids, of Chinese characters. 176 */ 177 size_t im_get_fixed_len(); 178 179 /** 180 * Cancel the input state and reset the search workspace. 181 */ 182 bool im_cancel_input(); 183 184 /** 185 * Get prediction candiates based on the given fixed Chinese string as the 186 * history. 187 * 188 * @param his_buf The history buffer to do the prediction. It should be ended 189 * with '\0'. 190 * @param pre_buf Used to return prediction result list. 191 * @return The number of predicted result string. 192 */ 193 size_t im_get_predicts(const char16 *his_buf, 194 char16 (*&pre_buf)[kMaxPredictSize + 1]); 195 196 /** 197 * Enable Shengmus in ShouZiMu mode. 198 */ 199 void im_enable_shm_as_szm(bool enable); 200 201 /** 202 * Enable Yunmus in ShouZiMu mode. 203 */ 204 void im_enable_ym_as_szm(bool enable); 205 } 206 207 #ifdef __cplusplus 208 } 209 #endif 210 211 #endif // PINYINIME_INCLUDE_ANDPYIME_H__ 212