/src/im/gpinyin/include/pinyinime.h

http://ftk.googlecode.com/ · C++ Header · 211 lines · 36 code · 25 blank · 150 comment · 0 complexity · b1e9fcc55fc0ce62d7a2bdb85961553f MD5 · raw file

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