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

  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
 24extern "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(unsigned max_sps_len, unsigned 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  unsigned im_search(const char* sps_buf, unsigned 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  unsigned im_delsearch(unsigned 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  unsigned 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(unsigned *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(unsigned cand_id, char16* cand_str,
139                           unsigned 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  unsigned 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  unsigned im_choose(unsigned 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  unsigned 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  unsigned 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  unsigned 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__