librime: rime_api.h Source File

| librime 1.2 Rime Input Method Engine, the core library

rime_api.h
Go to the documentation of this file.
1/*
2 * Copyright RIME Developers
3 * Distributed under the BSD License
4 *
5 * 2011-08-08 GONG Chen <chen.sst@gmail.com> v0.9
6 * 2013-05-02 GONG Chen <chen.sst@gmail.com> v1.0
7 */
8#ifndef RIME_API_H_
9#define RIME_API_H_
10
11#include <stddef.h>
12#include <stdint.h>
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
18#if defined(_WIN32)
19#if defined(RIME_EXPORTS)
20/* DLL export */
21#define RIME_DLL __declspec(dllexport)
22#define RIME_API extern "C" RIME_DLL
23#elif defined(RIME_IMPORTS)
24/* DLL import */
25#define RIME_DLL __declspec(dllimport)
26#define RIME_API extern "C" RIME_DLL
27#else
28/* static library */
29#define RIME_DLL
30#define RIME_API
31#endif
32#else /* _WIN32 */
33#define RIME_DLL
34#define RIME_API
35#endif /* _WIN32 */
36
37#ifndef RIME_DEPRECATED
38#define RIME_DEPRECATED RIME_API
39#endif
40
41#ifndef RIME_FLAVORED
42#define RIME_FLAVORED(name) name
43#endif
44
45#ifndef Bool
46#define Bool int
47#endif
48
49#ifndef False
50#define False 0
51#endif
52
53#ifndef True
54#define True 1
55#endif
56
57 typedef uintptr_t RimeSessionId;
58
59// Version control
60#define RIME_STRUCT_INIT(Type, var) \
61 ((var).data_size = sizeof(Type) - sizeof((var).data_size))
62#define RIME_STRUCT_HAS_MEMBER(var, member) \
63 ((int)(sizeof((var).data_size) + (var).data_size) > \
64 (char*)&member - (char*)&var)
65#define RIME_STRUCT_CLEAR(var) \
66 memset((char*)&(var) + sizeof((var).data_size), 0, (var).data_size)
67
69#define RIME_STRUCT(Type, var) \
70 Type var = {0}; \
71 RIME_STRUCT_INIT(Type, var);
72
73// tests that member is a non-null pointer in self-versioned struct *p.
74#define RIME_PROVIDED(p, member) \
75 ((p) && RIME_STRUCT_HAS_MEMBER(*(p), (p)->member) && (p)->member)
76
78#define RIME_PROTO_BUILDER void
79
81
84 typedef struct rime_traits_t {
85 int data_size;
86 // v0.9
87 const char* shared_data_dir;
88 const char* user_data_dir;
89 const char* distribution_name;
90 const char* distribution_code_name;
91 const char* distribution_version;
92 // v1.0
98 const char* app_name;
99
101 const char** modules;
102 // v1.6
107 int min_log_level;
112 const char* log_dir;
114 const char* prebuilt_data_dir;
116 const char* staging_dir;
117} RimeTraits;
118
119 typedef struct {
120 int length;
121 int cursor_pos;
122 int sel_start;
123 int sel_end;
124 char* preedit;
125} RimeComposition;
126
127 typedef struct rime_candidate_t {
128 char* text;
129 char* comment;
130 void* reserved;
131} RimeCandidate;
132
133 typedef struct {
134 int page_size;
135 int page_no;
136 Bool is_last_page;
137 int highlighted_candidate_index;
138 int num_candidates;
139 RimeCandidate* candidates;
140 char* select_keys;
141} RIME_FLAVORED(RimeMenu);
142
146 typedef struct rime_commit_t {
147 int data_size;
148 // v0.9
149 char* text;
150} RimeCommit;
151
155typedef struct RIME_FLAVORED(rime_context_t) {
156 int data_size;
157 // v0.9
158 RimeComposition composition;
159 RIME_FLAVORED(RimeMenu) menu;
160 // v0.9.2
161 char* commit_text_preview;
162 char** select_labels;
163} RIME_FLAVORED(RimeContext);
164
168typedef struct RIME_FLAVORED(rime_status_t) {
169 int data_size;
170 // v0.9
171 char* schema_id;
172 char* schema_name;
173 Bool is_disabled;
174 Bool is_composing;
175 Bool is_ascii_mode;
176 Bool is_full_shape;
177 Bool is_simplified;
178 Bool is_traditional;
179 Bool is_ascii_punct;
180} RIME_FLAVORED(RimeStatus);
181
182 typedef struct rime_candidate_list_iterator_t {
183 void* ptr;
184 int index;
185 RimeCandidate candidate;
186} RimeCandidateListIterator;
187
188 typedef struct rime_config_t {
189 void* ptr;
190} RimeConfig;
191
192 typedef struct rime_config_iterator_t {
193 void* list;
194 void* map;
195 int index;
196 const char* key;
197 const char* path;
198} RimeConfigIterator;
199
200 typedef struct rime_schema_list_item_t {
201 char* schema_id;
202 char* name;
203 void* reserved;
204} RimeSchemaListItem;
205
206 typedef struct rime_schema_list_t {
207 size_t size;
208 RimeSchemaListItem* list;
209} RimeSchemaList;
210
211 typedef struct rime_string_slice_t {
212 const char* str;
213 size_t length;
214} RimeStringSlice;
215
231 typedef void (*RimeNotificationHandler)(void* context_object,
232 RimeSessionId session_id,
233 const char* message_type,
234 const char* message_value);
235
240 typedef struct rime_custom_api_t {
241 int data_size;
242} RimeCustomApi;
243
244 typedef struct rime_module_t {
245 int data_size;
246
247 const char* module_name;
248 void (*initialize)(void);
249 void (*finalize)(void);
250 RimeCustomApi* (*get_api)(void);
251} RimeModule;
252
253 RIME_API Bool RimeRegisterModule(RimeModule* module);
254 RIME_API RimeModule* RimeFindModule(const char* module_name);
255
259typedef struct RIME_FLAVORED(rime_api_t) {
260 int data_size;
261
265 void (*setup)(RimeTraits* traits);
266
283 void (*set_notification_handler)(RimeNotificationHandler handler,
284 void* context_object);
285
286 // entry and exit
287
288 void (*initialize)(RimeTraits* traits);
289 void (*finalize)(void);
290
291 Bool (*start_maintenance)(Bool full_check);
292 Bool (*is_maintenance_mode)(void);
293 void (*join_maintenance_thread)(void);
294
295 // deployment
296
297 void (*deployer_initialize)(RimeTraits* traits);
298 Bool (*prebuild)(void);
299 Bool (*deploy)(void);
300 Bool (*deploy_schema)(const char* schema_file);
301 Bool (*deploy_config_file)(const char* file_name, const char* version_key);
302
303 Bool (*sync_user_data)(void);
304
305 // session management
306
307 RimeSessionId (*create_session)(void);
308 Bool (*find_session)(RimeSessionId session_id);
309 Bool (*destroy_session)(RimeSessionId session_id);
310 void (*cleanup_stale_sessions)(void);
311 void (*cleanup_all_sessions)(void);
312
313 // input
314
315 Bool (*process_key)(RimeSessionId session_id, int keycode, int mask);
316 // return True if there is unread commit text
317 Bool (*commit_composition)(RimeSessionId session_id);
318 void (*clear_composition)(RimeSessionId session_id);
319
320 // output
321
322 Bool (*get_commit)(RimeSessionId session_id, RimeCommit* commit);
323 Bool (*free_commit)(RimeCommit* commit);
324 Bool (*get_context)(RimeSessionId session_id,
325 RIME_FLAVORED(RimeContext) * context);
326 Bool (*free_context)(RIME_FLAVORED(RimeContext) * ctx);
327 Bool (*get_status)(RimeSessionId session_id,
328 RIME_FLAVORED(RimeStatus) * status);
329 Bool (*free_status)(RIME_FLAVORED(RimeStatus) * status);
330
331 // runtime options
332
333 void (*set_option)(RimeSessionId session_id, const char* option, Bool value);
334 Bool (*get_option)(RimeSessionId session_id, const char* option);
335
336 void (*set_property)(RimeSessionId session_id,
337 const char* prop,
338 const char* value);
339 Bool (*get_property)(RimeSessionId session_id,
340 const char* prop,
341 char* value,
342 size_t buffer_size);
343
344 Bool (*get_schema_list)(RimeSchemaList* schema_list);
345 void (*free_schema_list)(RimeSchemaList* schema_list);
346
347 Bool (*get_current_schema)(RimeSessionId session_id,
348 char* schema_id,
349 size_t buffer_size);
350 Bool (*select_schema)(RimeSessionId session_id, const char* schema_id);
351
352 // configuration
353
354 Bool (*schema_open)(const char* schema_id, RimeConfig* config);
355 Bool (*config_open)(const char* config_id, RimeConfig* config);
356 Bool (*config_close)(RimeConfig* config);
357 Bool (*config_get_bool)(RimeConfig* config, const char* key, Bool* value);
358 Bool (*config_get_int)(RimeConfig* config, const char* key, int* value);
359 Bool (*config_get_double)(RimeConfig* config, const char* key, double* value);
360 Bool (*config_get_string)(RimeConfig* config,
361 const char* key,
362 char* value,
363 size_t buffer_size);
364 const char* (*config_get_cstring)(RimeConfig* config, const char* key);
365 Bool (*config_update_signature)(RimeConfig* config, const char* signer);
366 Bool (*config_begin_map)(RimeConfigIterator* iterator,
367 RimeConfig* config,
368 const char* key);
369 Bool (*config_next)(RimeConfigIterator* iterator);
370 void (*config_end)(RimeConfigIterator* iterator);
371
372 // testing
373
374 Bool (*simulate_key_sequence)(RimeSessionId session_id,
375 const char* key_sequence);
376
377 // module
378
379 Bool (*register_module)(RimeModule* module);
380 RimeModule* (*find_module)(const char* module_name);
381
382 Bool (*run_task)(const char* task_name);
383
385 const char* (*get_shared_data_dir)(void);
387 const char* (*get_user_data_dir)(void);
389 const char* (*get_sync_dir)(void);
390
391 const char* (*get_user_id)(void);
392 void (*get_user_data_sync_dir)(char* dir, size_t buffer_size);
393
395
398 Bool (*config_init)(RimeConfig* config);
400 Bool (*config_load_string)(RimeConfig* config, const char* yaml);
401
402 // configuration: setters
403 Bool (*config_set_bool)(RimeConfig* config, const char* key, Bool value);
404 Bool (*config_set_int)(RimeConfig* config, const char* key, int value);
405 Bool (*config_set_double)(RimeConfig* config, const char* key, double value);
406 Bool (*config_set_string)(RimeConfig* config,
407 const char* key,
408 const char* value);
409
410 // configuration: manipulating complex structures
411 Bool (*config_get_item)(RimeConfig* config,
412 const char* key,
413 RimeConfig* value);
414 Bool (*config_set_item)(RimeConfig* config,
415 const char* key,
416 RimeConfig* value);
417 Bool (*config_clear)(RimeConfig* config, const char* key);
418 Bool (*config_create_list)(RimeConfig* config, const char* key);
419 Bool (*config_create_map)(RimeConfig* config, const char* key);
420 size_t (*config_list_size)(RimeConfig* config, const char* key);
421 Bool (*config_begin_list)(RimeConfigIterator* iterator,
422 RimeConfig* config,
423 const char* key);
424
426
430 const char* (*get_input)(RimeSessionId session_id);
431
433 size_t (*get_caret_pos)(RimeSessionId session_id);
434
436 Bool (*select_candidate)(RimeSessionId session_id, size_t index);
437
439 const char* (*get_version)(void);
440
442 void (*set_caret_pos)(RimeSessionId session_id, size_t caret_pos);
443
445 Bool (*select_candidate_on_current_page)(RimeSessionId session_id,
446 size_t index);
447
449 Bool (*candidate_list_begin)(RimeSessionId session_id,
450 RimeCandidateListIterator* iterator);
451 Bool (*candidate_list_next)(RimeCandidateListIterator* iterator);
452 void (*candidate_list_end)(RimeCandidateListIterator* iterator);
453
456 Bool (*user_config_open)(const char* config_id, RimeConfig* config);
457
458 Bool (*candidate_list_from_index)(RimeSessionId session_id,
459 RimeCandidateListIterator* iterator,
460 int index);
461
464 const char* (*get_prebuilt_data_dir)(void);
467 const char* (*get_staging_dir)(void);
468
471 void (*commit_proto)(RimeSessionId session_id,
472 RIME_PROTO_BUILDER* commit_builder);
473 void (*context_proto)(RimeSessionId session_id,
474 RIME_PROTO_BUILDER* context_builder);
475 void (*status_proto)(RimeSessionId session_id,
476 RIME_PROTO_BUILDER* status_builder);
477
478 const char* (*get_state_label)(RimeSessionId session_id,
479 const char* option_name,
480 Bool state);
481
483 Bool (*delete_candidate)(RimeSessionId session_id, size_t index);
485 Bool (*delete_candidate_on_current_page)(RimeSessionId session_id,
486 size_t index);
487
488 RimeStringSlice (*get_state_label_abbreviated)(RimeSessionId session_id,
489 const char* option_name,
490 Bool state,
491 Bool abbreviated);
492
493 Bool (*set_input)(RimeSessionId session_id, const char* input);
494
495 void (*get_shared_data_dir_s)(char* dir, size_t buffer_size);
496 void (*get_user_data_dir_s)(char* dir, size_t buffer_size);
497 void (*get_prebuilt_data_dir_s)(char* dir, size_t buffer_size);
498 void (*get_staging_dir_s)(char* dir, size_t buffer_size);
499 void (*get_sync_dir_s)(char* dir, size_t buffer_size);
500
502 Bool (*highlight_candidate)(RimeSessionId session_id, size_t index);
504 Bool (*highlight_candidate_on_current_page)(RimeSessionId session_id,
505 size_t index);
506
507 Bool (*change_page)(RimeSessionId session_id, Bool backward);
508} RIME_FLAVORED(RimeApi);
509
511
514 RIME_API RIME_FLAVORED(RimeApi) * RIME_FLAVORED(rime_get_api)(void);
515
518#define RIME_API_AVAILABLE(api, func) \
519 (RIME_STRUCT_HAS_MEMBER(*(api), (api)->func) && (api)->func)
520
521// Initializer for MSVC and GCC.
522// 2010 Joe Lowe. Released into the public domain.
523#if defined(__GNUC__)
524#define RIME_MODULE_INITIALIZER(f) \
525 static void f(void) __attribute__((constructor)); \
526 static void f(void)
527#elif defined(_MSC_VER)
528#pragma section(".CRT$XCU", read)
529#define RIME_MODULE_INITIALIZER(f) \
530 static void __cdecl f(void); \
531 __declspec(allocate(".CRT$XCU")) void(__cdecl * f##_)(void) = f; \
532 static void __cdecl f(void)
533#endif
534
541#define RIME_REGISTER_MODULE(name) \
542 void rime_require_module_##name() {} \
543 RIME_MODULE_INITIALIZER(rime_register_module_##name) { \
544 static RimeModule module = {0}; \
545 if (!module.data_size) { \
546 RIME_STRUCT_INIT(RimeModule, module); \
547 module.module_name = #name; \
548 module.initialize = rime_##name##_initialize; \
549 module.finalize = rime_##name##_finalize; \
550 } \
551 RimeRegisterModule(&module); \
552 }
553
557#define RIME_REGISTER_CUSTOM_MODULE(name) \
558 void rime_require_module_##name() {} \
559 static void rime_customize_module_##name(RimeModule* module); \
560 RIME_MODULE_INITIALIZER(rime_register_module_##name) { \
561 static RimeModule module = {0}; \
562 if (!module.data_size) { \
563 RIME_STRUCT_INIT(RimeModule, module); \
564 module.module_name = #name; \
565 module.initialize = rime_##name##_initialize; \
566 module.finalize = rime_##name##_finalize; \
567 rime_customize_module_##name(&module); \
568 } \
569 RimeRegisterModule(&module); \
570 } \
571 static void rime_customize_module_##name(RimeModule* module)
572
576#define RIME_MODULE_LIST(var, ...) const char* var[] = {__VA_ARGS__, NULL}
577
582#define RIME_REGISTER_MODULE_GROUP(name, ...) \
583 static RIME_MODULE_LIST(rime_##name##_module_group, __VA_ARGS__); \
584 static void rime_##name##_initialize() { \
585 rime::LoadModules(rime_##name##_module_group); \
586 } \
587 static void rime_##name##_finalize() {} \
588 RIME_REGISTER_MODULE(name)
589
590#ifdef __cplusplus
591}
592#endif
593
594#endif // RIME_API_H_
RimeModule
struct rime_module_t RimeModule
Definition module.h:14
RimeFindModule
RIME_API RimeModule * RimeFindModule(const char *module_name)
Definition rime_api.cc:45
RimeRegisterModule
RIME_API Bool RimeRegisterModule(RimeModule *module)
Definition rime_api.cc:38
RimeCandidateListIterator
struct rime_candidate_list_iterator_t RimeCandidateListIterator
RimeSchemaListItem
struct rime_schema_list_item_t RimeSchemaListItem
RimeSessionId
uintptr_t RimeSessionId
Definition rime_api.h:57
RimeCustomApi
struct rime_custom_api_t RimeCustomApi
Extend the structure to publish custom data/functions in your specific module.
RimeStringSlice
struct rime_string_slice_t RimeStringSlice
RimeSchemaList
struct rime_schema_list_t RimeSchemaList
RimeCandidate
struct rime_candidate_t RimeCandidate
RimeConfigIterator
struct rime_config_iterator_t RimeConfigIterator
RimeConfig
struct rime_config_t RimeConfig
Bool
#define Bool
Definition rime_api.h:46
RimeNotificationHandler
void(*) RimeNotificationHandler(void *context_object, RimeSessionId session_id, const char *message_type, const char *message_value)
Definition rime_api.h:231
RIME_API
#define RIME_API
Definition rime_api.h:34
RIME_FLAVORED
#define RIME_FLAVORED(name)
Definition rime_api.h:42
RimeCommit
struct rime_commit_t RimeCommit
Should be initialized by calling RIME_STRUCT_INIT(Type, var);.
RIME_PROTO_BUILDER
#define RIME_PROTO_BUILDER
For passing pointer to capnproto builder as opaque pointer through C API.
Definition rime_api.h:78
RimeTraits
struct rime_traits_t RimeTraits
Rime traits structure.
rime_traits_t
Rime traits structure.
Definition rime_api.h:84
rime_traits_t::prebuilt_data_dir
const char * prebuilt_data_dir
prebuilt data directory. defaults to ${shared_data_dir}/build
Definition rime_api.h:114
rime_traits_t::distribution_code_name
const char * distribution_code_name
Definition rime_api.h:90
rime_traits_t::distribution_name
const char * distribution_name
Definition rime_api.h:89
rime_traits_t::staging_dir
const char * staging_dir
staging directory. defaults to ${user_data_dir}/build
Definition rime_api.h:116
rime_traits_t::log_dir
const char * log_dir
Directory of log files.
Definition rime_api.h:112
rime_traits_t::min_log_level
int min_log_level
Minimal level of logged messages.
Definition rime_api.h:107
rime_traits_t::modules
const char ** modules
A list of modules to load before initializing.
Definition rime_api.h:101
rime_traits_t::app_name
const char * app_name
Pass a C-string constant in the format "rime.x" where 'x' is the name of your application.
Definition rime_api.h:98
rime_traits_t::distribution_version
const char * distribution_version
Definition rime_api.h:91
rime_traits_t::user_data_dir
const char * user_data_dir
Definition rime_api.h:88
rime_traits_t::data_size
int data_size
Definition rime_api.h:85
rime_traits_t::shared_data_dir
const char * shared_data_dir
Definition rime_api.h:87
RimeComposition
Definition rime_api.h:119
RimeComposition::preedit
char * preedit
Definition rime_api.h:124
RimeComposition::length
int length
Definition rime_api.h:120
RimeComposition::cursor_pos
int cursor_pos
Definition rime_api.h:121
RimeComposition::sel_start
int sel_start
Definition rime_api.h:122
RimeComposition::sel_end
int sel_end
Definition rime_api.h:123
rime_candidate_t
Definition rime_api.h:127
rime_candidate_t::reserved
void * reserved
Definition rime_api.h:130
rime_candidate_t::comment
char * comment
Definition rime_api.h:129
rime_candidate_t::text
char * text
Definition rime_api.h:128
RIME_FLAVORED::highlighted_candidate_index
int highlighted_candidate_index
Definition rime_api.h:137
RIME_FLAVORED::is_last_page
Bool is_last_page
Definition rime_api.h:136
RIME_FLAVORED::page_no
int page_no
Definition rime_api.h:135
RIME_FLAVORED::select_keys
char * select_keys
Definition rime_api.h:140
RIME_FLAVORED::candidates
RimeCandidate * candidates
Definition rime_api.h:139
RIME_FLAVORED::num_candidates
int num_candidates
Definition rime_api.h:138
RIME_FLAVORED::page_size
int page_size
Definition rime_api.h:134
rime_commit_t
Should be initialized by calling RIME_STRUCT_INIT(Type, var);.
Definition rime_api.h:146
rime_commit_t::text
char * text
Definition rime_api.h:149
rime_commit_t::data_size
int data_size
Definition rime_api.h:147
rime_candidate_list_iterator_t
Definition rime_api.h:182
rime_candidate_list_iterator_t::index
int index
Definition rime_api.h:184
rime_candidate_list_iterator_t::candidate
RimeCandidate candidate
Definition rime_api.h:185
rime_candidate_list_iterator_t::ptr
void * ptr
Definition rime_api.h:183
rime_config_t
Definition rime_api.h:188
rime_config_t::ptr
void * ptr
Definition rime_api.h:189
rime_config_iterator_t
Definition rime_api.h:192
rime_config_iterator_t::index
int index
Definition rime_api.h:195
rime_config_iterator_t::list
void * list
Definition rime_api.h:193
rime_config_iterator_t::path
const char * path
Definition rime_api.h:197
rime_config_iterator_t::key
const char * key
Definition rime_api.h:196
rime_config_iterator_t::map
void * map
Definition rime_api.h:194
rime_schema_list_item_t
Definition rime_api.h:200
rime_schema_list_item_t::schema_id
char * schema_id
Definition rime_api.h:201
rime_schema_list_item_t::reserved
void * reserved
Definition rime_api.h:203
rime_schema_list_item_t::name
char * name
Definition rime_api.h:202
rime_schema_list_t
Definition rime_api.h:206
rime_schema_list_t::list
RimeSchemaListItem * list
Definition rime_api.h:208
rime_schema_list_t::size
size_t size
Definition rime_api.h:207
rime_string_slice_t
Definition rime_api.h:211
rime_string_slice_t::str
const char * str
Definition rime_api.h:212
rime_string_slice_t::length
size_t length
Definition rime_api.h:213
rime_custom_api_t
Extend the structure to publish custom data/functions in your specific module.
Definition rime_api.h:240
rime_custom_api_t::data_size
int data_size
Definition rime_api.h:241
rime_module_t
Definition rime_api.h:244
rime_module_t::data_size
int data_size
Definition rime_api.h:245
rime_module_t::module_name
const char * module_name
Definition rime_api.h:247
rime_module_t::initialize
void(*) initialize(void)
Definition rime_api.h:248
rime_module_t::finalize
void(*) finalize(void)
Definition rime_api.h:249