rime_api.h

Go to the documentation of this file.

/*
 * Copyright RIME Developers
 * Distributed under the BSD License
 *
 * 2011-08-08  GONG Chen <chen.sst@gmail.com>  v0.9
 * 2013-05-02  GONG Chen <chen.sst@gmail.com>  v1.0
 */
#ifndef RIME_API_H_
#define RIME_API_H_
 
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if defined(_WIN32)
#if defined(RIME_EXPORTS)
/* DLL export */
#define RIME_DLL __declspec(dllexport)
#define RIME_API extern "C" RIME_DLL
#elif defined(RIME_IMPORTS)
/* DLL import */
#define RIME_DLL __declspec(dllimport)
#define RIME_API extern "C" RIME_DLL
#else
/* static library */
#define RIME_DLL
#define RIME_API
#endif
#else /* _WIN32 */
#define RIME_DLL
#define RIME_API
#endif /* _WIN32 */
 
#ifndef RIME_DEPRECATED
#define RIME_DEPRECATED RIME_API
#endif
 
#ifndef RIME_FLAVORED
#define RIME_FLAVORED(name) name
#endif
 
#ifndef Bool
#define Bool int
#endif
 
#ifndef False
#define False 0
#endif
 
#ifndef True
#define True 1
#endif
 
typedef uintptr_t RimeSessionId;
 
// Version control
#define RIME_STRUCT_INIT(Type, var) \
  ((var).data_size = sizeof(Type) - sizeof((var).data_size))
#define RIME_STRUCT_HAS_MEMBER(var, member)           \
  ((int)(sizeof((var).data_size) + (var).data_size) > \
   (char*)&member - (char*)&var)
#define RIME_STRUCT_CLEAR(var) \
  memset((char*)&(var) + sizeof((var).data_size), 0, (var).data_size)

#define RIME_STRUCT(Type, var) \
  Type var = {0};              \
  RIME_STRUCT_INIT(Type, var);
 
// tests that member is a non-null pointer in self-versioned struct *p.
#define RIME_PROVIDED(p, member) \
  ((p) && RIME_STRUCT_HAS_MEMBER(*(p), (p)->member) && (p)->member)

#define RIME_PROTO_BUILDER void


typedef struct rime_traits_t {
  int data_size;
  // v0.9
  const char* shared_data_dir;
  const char* user_data_dir;
  const char* distribution_name;
  const char* distribution_code_name;
  const char* distribution_version;
  // v1.0
  const char* app_name;

  const char** modules;
  // v1.6
  int min_log_level;
  const char* log_dir;
  const char* prebuilt_data_dir;
  const char* staging_dir;
} RimeTraits;
 
typedef struct {
  int length;
  int cursor_pos;
  int sel_start;
  int sel_end;
  char* preedit;
} RimeComposition;
 
typedef struct rime_candidate_t {
  char* text;
  char* comment;
  void* reserved;
} RimeCandidate;
 
typedef struct {
  int page_size;
  int page_no;
  Bool is_last_page;
  int highlighted_candidate_index;
  int num_candidates;
  RimeCandidate* candidates;
  char* select_keys;
} RIME_FLAVORED(RimeMenu);

typedef struct rime_commit_t {
  int data_size;
  // v0.9
  char* text;
} RimeCommit;

typedef struct RIME_FLAVORED(rime_context_t) {
  int data_size;
  // v0.9
  RimeComposition composition;
  RIME_FLAVORED(RimeMenu) menu;
  // v0.9.2
  char* commit_text_preview;
  char** select_labels;
} RIME_FLAVORED(RimeContext);

typedef struct RIME_FLAVORED(rime_status_t) {
  int data_size;
  // v0.9
  char* schema_id;
  char* schema_name;
  Bool is_disabled;
  Bool is_composing;
  Bool is_ascii_mode;
  Bool is_full_shape;
  Bool is_simplified;
  Bool is_traditional;
  Bool is_ascii_punct;
} RIME_FLAVORED(RimeStatus);
 
typedef struct rime_candidate_list_iterator_t {
  void* ptr;
  int index;
  RimeCandidate candidate;
} RimeCandidateListIterator;
 
typedef struct rime_config_t {
  void* ptr;
} RimeConfig;
 
typedef struct rime_config_iterator_t {
  void* list;
  void* map;
  int index;
  const char* key;
  const char* path;
} RimeConfigIterator;
 
typedef struct rime_schema_list_item_t {
  char* schema_id;
  char* name;
  void* reserved;
} RimeSchemaListItem;
 
typedef struct rime_schema_list_t {
  size_t size;
  RimeSchemaListItem* list;
} RimeSchemaList;
 
typedef struct rime_string_slice_t {
  const char* str;
  size_t length;
} RimeStringSlice;

typedef void (*RimeNotificationHandler)(void* context_object,
                                        RimeSessionId session_id,
                                        const char* message_type,
                                        const char* message_value);

typedef struct rime_custom_api_t {
  int data_size;
} RimeCustomApi;
 
typedef struct rime_module_t {
  int data_size;
 
  const char* module_name;
  void (*initialize)(void);
  void (*finalize)(void);
  RimeCustomApi* (*get_api)(void);
} RimeModule;
 
RIME_API Bool RimeRegisterModule(RimeModule* module);
RIME_API RimeModule* RimeFindModule(const char* module_name);

typedef struct RIME_FLAVORED(rime_api_t) {
  int data_size;

  void (*setup)(RimeTraits* traits);

  void (*set_notification_handler)(RimeNotificationHandler handler,
                                   void* context_object);
 
  // entry and exit
 
  void (*initialize)(RimeTraits* traits);
  void (*finalize)(void);
 
  Bool (*start_maintenance)(Bool full_check);
  Bool (*is_maintenance_mode)(void);
  void (*join_maintenance_thread)(void);
 
  // deployment
 
  void (*deployer_initialize)(RimeTraits* traits);
  Bool (*prebuild)(void);
  Bool (*deploy)(void);
  Bool (*deploy_schema)(const char* schema_file);
  Bool (*deploy_config_file)(const char* file_name, const char* version_key);
 
  Bool (*sync_user_data)(void);
 
  // session management
 
  RimeSessionId (*create_session)(void);
  Bool (*find_session)(RimeSessionId session_id);
  Bool (*destroy_session)(RimeSessionId session_id);
  void (*cleanup_stale_sessions)(void);
  void (*cleanup_all_sessions)(void);
 
  // input
 
  Bool (*process_key)(RimeSessionId session_id, int keycode, int mask);
  // return True if there is unread commit text
  Bool (*commit_composition)(RimeSessionId session_id);
  void (*clear_composition)(RimeSessionId session_id);
 
  // output
 
  Bool (*get_commit)(RimeSessionId session_id, RimeCommit* commit);
  Bool (*free_commit)(RimeCommit* commit);
  Bool (*get_context)(RimeSessionId session_id,
                      RIME_FLAVORED(RimeContext) * context);
  Bool (*free_context)(RIME_FLAVORED(RimeContext) * ctx);
  Bool (*get_status)(RimeSessionId session_id,
                     RIME_FLAVORED(RimeStatus) * status);
  Bool (*free_status)(RIME_FLAVORED(RimeStatus) * status);
 
  // runtime options
 
  void (*set_option)(RimeSessionId session_id, const char* option, Bool value);
  Bool (*get_option)(RimeSessionId session_id, const char* option);
 
  void (*set_property)(RimeSessionId session_id,
                       const char* prop,
                       const char* value);
  Bool (*get_property)(RimeSessionId session_id,
                       const char* prop,
                       char* value,
                       size_t buffer_size);
 
  Bool (*get_schema_list)(RimeSchemaList* schema_list);
  void (*free_schema_list)(RimeSchemaList* schema_list);
 
  Bool (*get_current_schema)(RimeSessionId session_id,
                             char* schema_id,
                             size_t buffer_size);
  Bool (*select_schema)(RimeSessionId session_id, const char* schema_id);
 
  // configuration
 
  Bool (*schema_open)(const char* schema_id, RimeConfig* config);
  Bool (*config_open)(const char* config_id, RimeConfig* config);
  Bool (*config_close)(RimeConfig* config);
  Bool (*config_get_bool)(RimeConfig* config, const char* key, Bool* value);
  Bool (*config_get_int)(RimeConfig* config, const char* key, int* value);
  Bool (*config_get_double)(RimeConfig* config, const char* key, double* value);
  Bool (*config_get_string)(RimeConfig* config,
                            const char* key,
                            char* value,
                            size_t buffer_size);
  const char* (*config_get_cstring)(RimeConfig* config, const char* key);
  Bool (*config_update_signature)(RimeConfig* config, const char* signer);
  Bool (*config_begin_map)(RimeConfigIterator* iterator,
                           RimeConfig* config,
                           const char* key);
  Bool (*config_next)(RimeConfigIterator* iterator);
  void (*config_end)(RimeConfigIterator* iterator);
 
  // testing
 
  Bool (*simulate_key_sequence)(RimeSessionId session_id,
                                const char* key_sequence);
 
  // module
 
  Bool (*register_module)(RimeModule* module);
  RimeModule* (*find_module)(const char* module_name);
 
  Bool (*run_task)(const char* task_name);

  const char* (*get_shared_data_dir)(void);
  const char* (*get_user_data_dir)(void);
  const char* (*get_sync_dir)(void);
 
  const char* (*get_user_id)(void);
  void (*get_user_data_sync_dir)(char* dir, size_t buffer_size);


  Bool (*config_init)(RimeConfig* config);
  Bool (*config_load_string)(RimeConfig* config, const char* yaml);
 
  // configuration: setters
  Bool (*config_set_bool)(RimeConfig* config, const char* key, Bool value);
  Bool (*config_set_int)(RimeConfig* config, const char* key, int value);
  Bool (*config_set_double)(RimeConfig* config, const char* key, double value);
  Bool (*config_set_string)(RimeConfig* config,
                            const char* key,
                            const char* value);
 
  // configuration: manipulating complex structures
  Bool (*config_get_item)(RimeConfig* config,
                          const char* key,
                          RimeConfig* value);
  Bool (*config_set_item)(RimeConfig* config,
                          const char* key,
                          RimeConfig* value);
  Bool (*config_clear)(RimeConfig* config, const char* key);
  Bool (*config_create_list)(RimeConfig* config, const char* key);
  Bool (*config_create_map)(RimeConfig* config, const char* key);
  size_t (*config_list_size)(RimeConfig* config, const char* key);
  Bool (*config_begin_list)(RimeConfigIterator* iterator,
                            RimeConfig* config,
                            const char* key);


  const char* (*get_input)(RimeSessionId session_id);

  size_t (*get_caret_pos)(RimeSessionId session_id);

  Bool (*select_candidate)(RimeSessionId session_id, size_t index);

  const char* (*get_version)(void);

  void (*set_caret_pos)(RimeSessionId session_id, size_t caret_pos);

  Bool (*select_candidate_on_current_page)(RimeSessionId session_id,
                                           size_t index);

  Bool (*candidate_list_begin)(RimeSessionId session_id,
                               RimeCandidateListIterator* iterator);
  Bool (*candidate_list_next)(RimeCandidateListIterator* iterator);
  void (*candidate_list_end)(RimeCandidateListIterator* iterator);

  Bool (*user_config_open)(const char* config_id, RimeConfig* config);
 
  Bool (*candidate_list_from_index)(RimeSessionId session_id,
                                    RimeCandidateListIterator* iterator,
                                    int index);

  const char* (*get_prebuilt_data_dir)(void);
  const char* (*get_staging_dir)(void);

  void (*commit_proto)(RimeSessionId session_id,
                       RIME_PROTO_BUILDER* commit_builder);
  void (*context_proto)(RimeSessionId session_id,
                        RIME_PROTO_BUILDER* context_builder);
  void (*status_proto)(RimeSessionId session_id,
                       RIME_PROTO_BUILDER* status_builder);
 
  const char* (*get_state_label)(RimeSessionId session_id,
                                 const char* option_name,
                                 Bool state);

  Bool (*delete_candidate)(RimeSessionId session_id, size_t index);
  Bool (*delete_candidate_on_current_page)(RimeSessionId session_id,
                                           size_t index);
 
  RimeStringSlice (*get_state_label_abbreviated)(RimeSessionId session_id,
                                                 const char* option_name,
                                                 Bool state,
                                                 Bool abbreviated);
 
  Bool (*set_input)(RimeSessionId session_id, const char* input);
 
  void (*get_shared_data_dir_s)(char* dir, size_t buffer_size);
  void (*get_user_data_dir_s)(char* dir, size_t buffer_size);
  void (*get_prebuilt_data_dir_s)(char* dir, size_t buffer_size);
  void (*get_staging_dir_s)(char* dir, size_t buffer_size);
  void (*get_sync_dir_s)(char* dir, size_t buffer_size);

  Bool (*highlight_candidate)(RimeSessionId session_id, size_t index);
  Bool (*highlight_candidate_on_current_page)(RimeSessionId session_id,
                                              size_t index);
 
  Bool (*change_page)(RimeSessionId session_id, Bool backward);
} RIME_FLAVORED(RimeApi);


RIME_API RIME_FLAVORED(RimeApi) * RIME_FLAVORED(rime_get_api)(void);

#define RIME_API_AVAILABLE(api, func) \
  (RIME_STRUCT_HAS_MEMBER(*(api), (api)->func) && (api)->func)
 
// Initializer for MSVC and GCC.
// 2010 Joe Lowe. Released into the public domain.
#if defined(__GNUC__)
#define RIME_MODULE_INITIALIZER(f)                  \
  static void f(void) __attribute__((constructor)); \
  static void f(void)
#elif defined(_MSC_VER)
#pragma section(".CRT$XCU", read)
#define RIME_MODULE_INITIALIZER(f)                                 \
  static void __cdecl f(void);                                     \
  __declspec(allocate(".CRT$XCU")) void(__cdecl * f##_)(void) = f; \
  static void __cdecl f(void)
#endif

#define RIME_REGISTER_MODULE(name)                       \
  void rime_require_module_##name() {}                   \
  RIME_MODULE_INITIALIZER(rime_register_module_##name) { \
    static RimeModule module = {0};                      \
    if (!module.data_size) {                             \
      RIME_STRUCT_INIT(RimeModule, module);              \
      module.module_name = #name;                        \
      module.initialize = rime_##name##_initialize;      \
      module.finalize = rime_##name##_finalize;          \
    }                                                    \
    RimeRegisterModule(&module);                         \
  }

#define RIME_REGISTER_CUSTOM_MODULE(name)                       \
  void rime_require_module_##name() {}                          \
  static void rime_customize_module_##name(RimeModule* module); \
  RIME_MODULE_INITIALIZER(rime_register_module_##name) {        \
    static RimeModule module = {0};                             \
    if (!module.data_size) {                                    \
      RIME_STRUCT_INIT(RimeModule, module);                     \
      module.module_name = #name;                               \
      module.initialize = rime_##name##_initialize;             \
      module.finalize = rime_##name##_finalize;                 \
      rime_customize_module_##name(&module);                    \
    }                                                           \
    RimeRegisterModule(&module);                                \
  }                                                             \
  static void rime_customize_module_##name(RimeModule* module)

#define RIME_MODULE_LIST(var, ...) const char* var[] = {__VA_ARGS__, NULL}

#define RIME_REGISTER_MODULE_GROUP(name, ...)                       \
  static RIME_MODULE_LIST(rime_##name##_module_group, __VA_ARGS__); \
  static void rime_##name##_initialize() {                          \
    rime::LoadModules(rime_##name##_module_group);                  \
  }                                                                 \
  static void rime_##name##_finalize() {}                           \
  RIME_REGISTER_MODULE(name)
 
#ifdef __cplusplus
}
#endif
 
#endif  // RIME_API_H_