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(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