rime_api.h File Reference

#include <stddef.h>
#include <stdint.h>

Include dependency graph for rime_api.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rime_traits_t
	Rime traits structure. More...
struct	RimeComposition
struct	rime_candidate_t
struct	RIME_FLAVORED
struct	rime_commit_t
	Should be initialized by calling RIME_STRUCT_INIT(Type, var);. More...
struct	rime_candidate_list_iterator_t
struct	rime_config_t
struct	rime_config_iterator_t
struct	rime_schema_list_item_t
struct	rime_schema_list_t
struct	rime_string_slice_t
struct	rime_custom_api_t
	Extend the structure to publish custom data/functions in your specific module. More...
struct	rime_module_t

Macros
#define	RIME_DLL
#define	RIME_API
#define	RIME_DEPRECATED   RIME_API
#define	RIME_FLAVORED(name)
#define	Bool   int
#define	False   0
#define	True   1
#define	RIME_STRUCT_INIT(Type, var)
#define	RIME_STRUCT_HAS_MEMBER(var, member)
#define	RIME_STRUCT_CLEAR(var)
#define	RIME_STRUCT(Type, var)
	Define a variable of Type.
#define	RIME_PROVIDED(p, member)
#define	RIME_PROTO_BUILDER   void
	For passing pointer to capnproto builder as opaque pointer through C API.
#define	RIME_API_AVAILABLE(api, func)
	Clients should test if an api function is available in the current version before calling it.
#define	RIME_REGISTER_MODULE(name)
	Automatically register a rime module when the library is loaded.
#define	RIME_REGISTER_CUSTOM_MODULE(name)
	Customize the module by assigning additional functions, eg.
#define	RIME_MODULE_LIST(var, ...)
	Defines a constant for a list of module names.
#define	RIME_REGISTER_MODULE_GROUP(name, ...)
	Register a phony module which, when loaded, will load a list of modules.

Typedefs
typedef uintptr_t	RimeSessionId
typedef struct rime_traits_t	RimeTraits
	Rime traits structure.
typedef struct rime_candidate_t	RimeCandidate
typedef struct rime_commit_t	RimeCommit
	Should be initialized by calling RIME_STRUCT_INIT(Type, var);.
typedef struct rime_candidate_list_iterator_t	RimeCandidateListIterator
typedef struct rime_config_t	RimeConfig
typedef struct rime_config_iterator_t	RimeConfigIterator
typedef struct rime_schema_list_item_t	RimeSchemaListItem
typedef struct rime_schema_list_t	RimeSchemaList
typedef struct rime_string_slice_t	RimeStringSlice
typedef void(*)	RimeNotificationHandler(void *context_object, RimeSessionId session_id, const char *message_type, const char *message_value)
typedef struct rime_custom_api_t	RimeCustomApi
	Extend the structure to publish custom data/functions in your specific module.
typedef struct rime_module_t	RimeModule

Functions
struct	RIME_FLAVORED (rime_context_t)
	Should be initialized by calling RIME_STRUCT_INIT(Type, var);.
	RIME_FLAVORED (RimeContext)
struct	RIME_FLAVORED (rime_status_t)
	Should be initialized by calling RIME_STRUCT_INIT(Type, var);.
	RIME_FLAVORED (RimeStatus)
RIME_API Bool	RimeRegisterModule (RimeModule *module)
RIME_API RimeModule *	RimeFindModule (const char *module_name)
struct	RIME_FLAVORED (rime_api_t)
	The API structure RimeApi is for rime v1.0+.
	RIME_FLAVORED (RimeApi) *RIME_FLAVORED(rime_get_api)(void)
	API entry.

Macro Definition Documentation

Bool

#define Bool   int

False

#define False   0

RIME_API

#define RIME_API

RIME_API_AVAILABLE

#define RIME_API_AVAILABLE	(		api,
			func )

Value:

(RIME_STRUCT_HAS_MEMBER(*(api), (api)->func) && (api)->func)

Clients should test if an api function is available in the current version before calling it.

RIME_DEPRECATED

#define RIME_DEPRECATED   RIME_API

RIME_DLL

#define RIME_DLL

RIME_FLAVORED

#define RIME_FLAVORED

(

name

)

Value:

name

RIME_MODULE_LIST

#define RIME_MODULE_LIST	(		var,
			... )

Value:

const char* var[] = {__VA_ARGS__, NULL}

Defines a constant for a list of module names.

RIME_PROTO_BUILDER

#define RIME_PROTO_BUILDER   void

For passing pointer to capnproto builder as opaque pointer through C API.

RIME_PROVIDED

#define RIME_PROVIDED	(		p,
			member )

Value:

((p) && RIME_STRUCT_HAS_MEMBER(*(p), (p)->member) && (p)->member)

RIME_REGISTER_CUSTOM_MODULE

#define RIME_REGISTER_CUSTOM_MODULE

(

name

)

Value:

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)

Customize the module by assigning additional functions, eg.

module->get_api.

RIME_REGISTER_MODULE

#define RIME_REGISTER_MODULE

(

name

)

Value:

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);                         \
}

Automatically register a rime module when the library is loaded.

Clients should define functions called rime_<module_name>initialize(), and rime<module_name>_finalize().

See also

core_module.cc for an example.

RIME_REGISTER_MODULE_GROUP

#define RIME_REGISTER_MODULE_GROUP	(		name,
			... )

Value:

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)

Register a phony module which, when loaded, will load a list of modules.

See also

setup.cc for an example.

RIME_STRUCT

#define RIME_STRUCT	(		Type,
			var )

Value:

Type var = {0};              \
RIME_STRUCT_INIT(Type, var);

Define a variable of Type.

RIME_STRUCT_CLEAR

#define RIME_STRUCT_CLEAR

(

var

)

Value:

memset((char*)&(var) + sizeof((var).data_size), 0, (var).data_size)

RIME_STRUCT_HAS_MEMBER

#define RIME_STRUCT_HAS_MEMBER	(		var,
			member )

Value:

((int)(sizeof((var).data_size) + (var).data_size) > \
 (char*)&member - (char*)&var)

RIME_STRUCT_INIT

#define RIME_STRUCT_INIT	(		Type,
			var )

Value:

((var).data_size = sizeof(Type) - sizeof((var).data_size))

True

#define True   1

Typedef Documentation

RimeCandidate

typedef struct rime_candidate_t RimeCandidate

RimeCandidateListIterator

typedef struct rime_candidate_list_iterator_t RimeCandidateListIterator

RimeCommit

typedef struct rime_commit_t RimeCommit

Should be initialized by calling RIME_STRUCT_INIT(Type, var);.

RimeConfig

typedef struct rime_config_t RimeConfig

RimeConfigIterator

typedef struct rime_config_iterator_t RimeConfigIterator

RimeCustomApi

typedef struct rime_custom_api_t RimeCustomApi

Extend the structure to publish custom data/functions in your specific module.

RimeModule

typedef struct rime_module_t RimeModule

RimeNotificationHandler

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

• on loading schema:
  • message_type="schema", message_value="luna_pinyin/Luna Pinyin"
• on changing mode:
  • message_type="option", message_value="ascii_mode"
  • message_type="option", message_value="!ascii_mode"

• on deployment:

  • session_id = 0, message_type="deploy", message_value="start"
  • session_id = 0, message_type="deploy", message_value="success"
  • session_id = 0, message_type="deploy", message_value="failure"

  handler will be called with context_object as the first parameter every time an event occurs in librime, until RimeFinalize() is called. when handler is NULL, notification is disabled.

RimeSchemaList

typedef struct rime_schema_list_t RimeSchemaList

RimeSchemaListItem

typedef struct rime_schema_list_item_t RimeSchemaListItem

RimeSessionId

typedef uintptr_t RimeSessionId

RimeStringSlice

typedef struct rime_string_slice_t RimeStringSlice

RimeTraits

typedef struct rime_traits_t RimeTraits

Rime traits structure.

Should be initialized by calling RIME_STRUCT_INIT(Type, var)

Function Documentation

RIME_FLAVORED() [1/6]

struct RIME_FLAVORED

(

rime_api_t

)

The API structure RimeApi is for rime v1.0+.

setup Call this function before accessing any other API functions.

Set up the notification callbacks Receive notifications

• on loading schema:
  • message_type="schema", message_value="luna_pinyin/Luna Pinyin"
• on changing mode:
  • message_type="option", message_value="ascii_mode"
  • message_type="option", message_value="!ascii_mode"
• on deployment:
  • session_id = 0, message_type="deploy", message_value="start"
  • session_id = 0, message_type="deploy", message_value="success"
  • session_id = 0, message_type="deploy", message_value="failure"

handler will be called with context_object as the first parameter every time an event occurs in librime, until RimeFinalize() is called. when handler is NULL, notification is disabled.

Deprecated

use get_shared_data_dir_s instead.

Deprecated

use get_user_data_dir_s instead.

Deprecated

use get_sync_dir_s instead.

initialize an empty config object

should call config_close() to free the object

deserialize config from a yaml string

get raw input

NULL is returned if session does not exist. the returned pointer to input string will become invalid upon editing.

caret position in terms of raw input

select a candidate at the given index in candidate list.

get the version of librime

set caret position in terms of raw input

select a candidate from current page.

access candidate list.

access config files in user data directory, eg. user.yaml and installation.yaml

prebuilt data directory.

Deprecated

use get_prebuilt_data_dir_s instead.

staging directory, stores data files deployed to a Rime client.

Deprecated

use get_staging_dir_s instead.

Deprecated

for capnproto API, use "proto" module from librime-proto plugin.

delete a candidate at the given index in candidate list.

delete a candidate from current page.

highlight a selection without committing

highlight a selection without committing

RIME_FLAVORED() [2/6]

struct RIME_FLAVORED

(

rime_context_t

)

Should be initialized by calling RIME_STRUCT_INIT(Type, var);.

RIME_FLAVORED() [3/6]

struct RIME_FLAVORED

(

rime_status_t

)

Should be initialized by calling RIME_STRUCT_INIT(Type, var);.

RIME_FLAVORED() [4/6]

RIME_API RIME_FLAVORED

(

RimeApi

)

API entry.

Acquire the version controlled RimeApi structure.

RIME_FLAVORED() [5/6]

RIME_FLAVORED

(

RimeContext

)

RIME_FLAVORED() [6/6]

RIME_FLAVORED

(

RimeStatus

)

RimeFindModule()

RIME_API RimeModule * RimeFindModule

(

const char *

module_name

)

RimeRegisterModule()

RIME_API Bool RimeRegisterModule

(

RimeModule *

module

)