Struct Session 

pub struct Session { /* private fields */ }

Implementations

impl Session

pub fn new(options: SessionOptions) -> Result<Session>

Validates the paths and every option (INVALID_SESSION_OPTIONS, UNKNOWN_HELPCODE_SCHEMA), loads the helpcode table and applies the options in the reference order (session.cpp:11-30, 57-66).

pub fn candidate_revision(&self) -> u64

Changes whenever a call may have changed the candidate list, so a host that read the candidates under one revision can tell that an index it holds no longer means the same row. Read-only calls never change it; neither do the setters that only affect later keys (clock, key touch and geometry, touch tuning, punctuation options, rescoring context). Starts at 0 and only grows.

pub fn set_clock(&mut self, clock: Clock)

Replace the steady and local clocks, so tests can cross the 3 s / 8 s / 10 s personal-learning windows and the date/time mode can be pinned.

pub fn character(&mut self, value: u8, shift_only: bool) -> KeyResult

One ASCII character; shift_only is a bare Shift+letter (local mode entry). 全拼下九键开启且没有别的组字时，数字 2-9 交给九宫格会话；九键双拼交的是方案用到的数字（可以有 1 和 0）；注音九键的数字由注音编辑器自己处理。待用的触点（Self::set_key_touch）只交给 26 键组字，九宫格的数字用不到它，一律在这一键后作废。

pub fn set_key_touch(&mut self, touch: Option<KeyTouch>)

下一次 character 的按下点（触屏宿主经 msime_client_touch_character 送来）。只有那一键是 26 键双拼的小写字母或 ; 时才交给方案；其余会改动组字或改道按键的入口（命令、选词、以词定字、结束组字、钉住和删除候选、移光标、九宫格、网格键、滑行、标点、换方案、换网格或几何、展开首字母候选、重置上下文）一开头就丢掉它，所以改道到别处的按键不会把触点留给后面的字母。只改配置的 setter（辅助码表、云候选开关、重排上下文等）不碰它。

pub fn set_key_geometry(&mut self, geometry: Option<Arc<KeyGeometry>>)

宿主注册或清除的键位几何，见 crate::touch::KeyGeometry。

pub fn set_touch_tuning(&mut self, tuning: TouchTuning)

按触点计价的参数；只有 Rust 侧（评测示例）调用，不经 FFI。

pub fn glide( &mut self, keyboard: &GlideKeyboard, points: &[GlidePoint], ) -> KeyResult

滑过字母键的一笔：它最可能拼出的全拼字母写到光标处，与已有组字之间用 ' 隔开。不是全拼、在本地模式或专用英文里、九键数字正在组字，以及没有串跟得上这一笔时，不处理。

pub fn key_grid(&self) -> Option<KeyGrid>

上一次 Session::set_key_grid（或 Session::set_nine_key_enabled）设下的组码网格，None 是不用网格；新会话是 None。网格开着时硬件键盘的字母照样走 26 键，要知道这次组字是不是在网格里打的，看 Session::grid_composing。

pub fn grid_composing(&self) -> bool

字母网格正在组字：九宫格会话（九键、14 键、18 键）在组字，快照、命令和上屏都来自它；或者五笔 14 键在组字，组码不是确定的字母。两种情况下的原样上屏都不是用户逐个打出的字母。

pub fn set_nine_key_enabled(&mut self, enabled: bool)

set_key_grid 的九键开关：开是九键，关是不用网格。

pub fn set_key_grid(&mut self, grid: Option<KeyGrid>)

换触屏的组码网格，先丢掉网格里的组字，所以在换键盘布局、没有组字时调用。英文九键和注音九键只在九键下打开（注音组字会被丢掉）：14 键的英文模式画全键盘，注音没有 14 键。

pub fn grid_key(&mut self, letter: u8) -> KeyResult

字母网格的一键：小写字母由 KeyGrid::code_of 归成整组，十八键双拼另收大写 ASCII 标记精确字母。标记保留在组码里，不复用硬件键盘的 character。全拼和双拼分别使用自己的分组表，五笔在 14 键下按组展开码表（wubi::grid）；本地模式、专用英文或已有 26 键组字时不处理，状态不变。

pub fn grid_limit_pick_ready(&self, value: u8, grid_key: bool) -> bool

九宫格组码已经到上限时，这一键能不能先选掉首选、再接着打（NineKeySession::limit_pick_ready）。grid_key 为真时 value 是 grid_key 收到的归组字母，否则是 character 收到的九键或九键双拼数字；两条路由各自只认自己的网格。

pub fn choose_nine_key_spelling(&mut self, index: usize) -> KeyResult

九宫格会话活跃时选它的拼写；否则在注音里钉目标音节的读音。

pub fn set_nine_key_filter( &mut self, single_character: bool, strokes: &str, ) -> KeyResult

九宫格组字时按单字、按笔画筛选候选（NineKeySession::set_filter）；没有九宫格组字时不处理。

pub fn command(&mut self, command: Command) -> KeyResult

pub fn conversion_left_from(&mut self, index: usize) -> KeyResult

整句改字的左移，进入改字时从第 index 个候选（宿主高亮的那一行）开始；已在改字里时与 command(ConversionLeft) 相同。九宫格和进不了改字时按 MoveLeft 处理。

pub fn candidate_key(&mut self, value: u8) -> KeyResult

1..9 选择组字候选；空闲联想不接管数字键。

pub fn punctuation(&mut self, value: u8) -> KeyResult

Finishes the composition and appends the Chinese mark; unhandled when Chinese punctuation is off or locked to ASCII, or the key has no mark.

pub fn set_chinese_punctuation_enabled(&mut self, enabled: bool)

Live; keeps the composition, caret and pairing state.

pub fn set_punctuation_lock(&mut self, lock: i32) -> Result<()>

INVALID_PUNCTUATION_LOCK outside 0..=2.

pub fn set_paired_punctuation_enabled(&mut self, enabled: bool)

pub fn set_punctuation_marks(&mut self, marks: PunctuationMarks)

换引号和方头括号的样式；组字、光标和交替状态都不动。

pub fn balance_paired_punctuation_after_auto_close(&mut self, opening: u8)

The host emitted the closing half of a paired mark itself.

pub fn select(&mut self, index: usize) -> KeyResult

pub fn select_edge(&mut self, index: usize, edge: CandidateEdge) -> KeyResult

Commit the first or last Han character of a candidate and drop the rest of the composition.

pub fn pin(&mut self, index: usize) -> KeyResult

Promote a dictionary candidate without committing; unsupported rows are unhandled, persistence failures carry a diagnostic.

pub fn remove(&mut self, index: usize) -> KeyResult

Remove a dictionary phrase without committing; single-character non-English rows are protected.

pub fn fix_position(&mut self, index: usize, position: i32) -> KeyResult

Fix a dictionary candidate to slot 1..=5 in this input context; unhandled for any other slot.

pub fn clear_position(&mut self, index: usize) -> KeyResult

pub fn finish(&mut self, first_index: usize) -> KeyResult

从宿主高亮的候选开始结束整段组字（没有高亮时为 0），剩余片段使用各自首选；索引无效时提交原文。普通拼音中的大写片段由字面候选保留。

pub fn switch_scheme(&mut self, scheme: SchemeType) -> Result<()>

Discards the composition. Fails, staying in the current scheme with the composition untouched, when the new scheme’s dictionary cannot be opened (Cantonese without a usable msime-cantonese.db, Stroke without a usable msime-stroke.db: LANGUAGE_DICTIONARY_UNAVAILABLE, LANGUAGE_DICTIONARY_VERSION_UNSUPPORTED).

pub fn is_supported_helpcode_schema(schema: &str) -> bool

pub fn set_helpcode_schema(&mut self, schema: &str) -> bool

False for an unsupported schema or a table that cannot be loaded.

pub fn set_helpcode_table(&mut self, table: SharedKeymap)

换上宿主给的辅助码表，替换当前的表；全拼和双拼都用它。

pub fn set_helpcode_enabled(&mut self, enabled: bool)

Quanpin and shuangpin together, as SessionOptions::helpcode does.

pub fn set_dedicated_english(&mut self, enabled: bool)

只有模式改变时才取消组字；重复设置保留当前输入。

pub fn wubi_pinyin_continues(&self, value: u8, shift: bool) -> bool

混输候选的读音能继续时，运行时应保留组字，不提前顶字上屏。

pub fn set_wubi_mixed_pinyin(&mut self, enabled: bool)

pub fn wubi_mixed_pinyin(&self) -> bool

五笔拼音混输是否打开。

pub fn reset_cache(&mut self)

宿主的清缓存动作（维护快捷键、iOS 键盘扩展的内存告警）：清掉本会话各方案的候选缓存，并放掉进程级缓存里的日文模型和没有会话在用的个人学习模型，让不再用它们的进程能交还内存；本会话若正持有模型，照常用到会话结束。

pub fn set_command_table( &mut self, table: &[CommandTableEntry], ) -> Option<String>

Replace the / mode’s command table; rows it cannot use are dropped. A diagnostic only if the open command list could not be refreshed.

pub fn set_plugin_commands( &mut self, commands: &[PluginCommand], ) -> Option<String>

替换脚本插件的 / 指令；用不了的被丢弃（local::command::usable_plugin_commands），缓存的插件行清掉。只有打开的 / 列表刷新失败时才返回诊断。

pub fn plugin_command_title(&self, trigger: &str) -> Option<&str>

生效的插件指令里 trigger 的标题，见 CandidateQueries::plugin_command_title。

pub fn set_quick_phrase_table( &mut self, table: &[QuickPhraseEntry], ) -> Option<String>

替换 K 模式的宿主短语表；用不了的行被丢弃。只有打开的 K 模式列表刷新失败时才返回诊断。

pub fn set_mention_entries( &mut self, entries: &[MentionEntry], ) -> Option<String>

Replace the @ mode’s list; entries it cannot use are dropped.

pub fn set_mention_places(&mut self, enabled: bool) -> Option<String>

Turn the embedded places of @ mode on or off.

pub fn reset_context(&mut self)

Forget the committed-word context (focus or application change, host-inserted text).

pub fn set_prediction_allowed(&mut self, allowed: bool)

宿主的即时隐私门禁；关闭时清掉建议，用户偏好仍保留。

pub fn set_personal_context_enabled(&mut self, enabled: bool)

Disabling also ends the current context.

pub fn cloud_candidates_enabled(&self) -> bool

当前组字是否预留云候选席位；运行时在修改前据此判断候选身份是否会变化。

pub fn set_cloud_candidates_enabled(&mut self, enabled: bool)

让宿主把云候选的固定席位交给当前会话；关闭时立即去掉尚未回答的占位行。

pub fn english_online_candidates_enabled(&self) -> bool

pub fn set_english_online_candidates_enabled(&mut self, enabled: bool)

pub fn set_rescoring_context(&mut self, context: &str)

The committed text the neural sentence models condition on, updated without rebuilding the session. Only the last 64 characters matter.

pub fn set_first_page_rows(&mut self, rows: FirstPageRows)

首页行数只决定词库要不要并入补全词。Runtime::set_page_size 在宿主改每页候选数时调它， 因此引擎的首屏门槛和分页始终同源，不必等下一次因别的偏好变化重建引擎。

pub fn expand_initial_candidates(&mut self) -> bool

Hand over the candidates withheld from a single-letter query; whether the list grew.

pub fn set_caret(&mut self, caret: Option<usize>)

设置前缀解码的组字光标（overlays.md §7.6）；位置限制在可编辑范围，不能越过本地模式的入口标记。None 回到末尾，九键组码时无操作。

pub fn prefix_end(&self) -> usize

End of the complete pinyin units before the caret in editing_text; 0 while nine-key digits are active.

pub fn pending_suffix(&self) -> String

The raw text after prefix_end, case kept; empty while nine-key digits are active.

pub fn snapshot(&self) -> SessionSnapshot

pub fn display_snapshot(&self) -> SessionSnapshot

给宿主画在屏幕上的快照：全拼的 preedit 按音节分开（双拼照 shuangpin_preedit_uses_raw），辅助码注释照常给出。Session::snapshot 的 preedit 保留全拼的按键原文，参考回放按它比对；其余字段两者相同。C 接口的 msime_engine_state 读的是这一份。

pub fn candidate_wubi_code(&self, word: &str) -> Option<&str>

返回候选词的完整五笔编码，仅供宿主显示反查结果；九宫格会话不沿用旧的普通候选反查。

pub fn segment_raw_boundaries(&self) -> Vec<usize>

Byte offsets into editing_text for pinyin-unit editing; empty when idle, in local modes, for non-pinyin schemes and during nine-key input. Read-only.

pub fn online_query(&self) -> Option<OnlineQuery>

pub fn takes_local_separator(&self) -> bool

Whether an apostrophe now separates a unit from its target or one /fy word from the next, so a host or runtime that would finish the composition on punctuation hands it over as a character instead.

pub fn command_translation_query(&self) -> Option<CommandTranslationQuery>

The /fy translation request; see InputSession::command_translation_query.

pub fn apply_command_translation( &mut self, query: &CommandTranslationQuery, translation: &str, ) -> bool

Whether the translation now shows first; false (not an error) for a stale query.

pub fn plugin_command_query(&self) -> Option<PluginCommandQuery>

插件指令要宿主去问的那一次；见 InputSession::plugin_command_query。

pub fn apply_plugin_command_rows( &mut self, query: &PluginCommandQuery, rows: &[(String, String)], ) -> bool

插件的行是否写进了会话；过期的查询返回 false（不是错误）。

pub fn apply_online_candidates( &mut self, query: &OnlineQuery, words: &[String], source: CandidateSource, ) -> bool

Whether the rows now show; false (not an error) for a stale query.

pub fn clear_online_candidates(&mut self, source: CandidateSource)

Remove one online provider’s rows from cached and visible candidates.

pub fn apply_online_candidate( &mut self, query: &OnlineQuery, word: &str, source: CandidateSource, ) -> bool

Trait Implementations

impl Drop for Session

The C++ registered PersonalNgramStore::flush_all with atexit (personal_ngram_store.cpp:255), so context learned in the last ~2 s reached the journal when the host quit. Rust runs no destructors for statics and atexit needs unsafe, so the session writes its journal’s queue as it ends, which hosts do on deactivation and shutdown. A host that can exit without dropping its sessions (macOS [NSApp terminate:] runs exit()) calls crate::flush_personal_learning (host-api’s msime_client_flush_all) or crate::shutdown from its will-terminate hook instead.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.