Input method engines

The struct arif_engine type defines a few functions for ARIF to communite with an input method engine.

struct arif_engine {
    arif_engine_init_func     *init;
    arif_engine_finalize_func *finalize;
    arif_engine_info_func     *info;
    arif_engine_query_func    *query;
};

Only the query function is used by the ARIF library. It's up to the library user to call the other functions when needed.

Engine initialization

If an input method engine needs to be initialized before use, the init function must be implemented. Otherwise, it should be NULL.

typedef int (arif_engine_init_func) (
    void const  *args,
    void       **engine_data_ptr
);

Extra info can be passed into the initializer function through args.

If initialization is successful, the function must return 0. Optionally, it can store a pointer to engine_data_ptr, which will be passed as an argument on subsequent engine function calls.

If initialization fails, the function must return a non-zero value.

Engine finalization

If not NULL, the finalize function is used for cleaning up resources for an engine, when the engine is no longer in use.

typedef void (arif_engine_finalize_func) (
    void *engine_data
);

The engine_data argument is the pointer stored to engine_data_ptr during initialization.

Engine info

If not NULL, the info function is used for retrieving information of an engine.

typedef void (arif_engine_info_func) (
    void        *engine_data,
    char const **name_ptr,
    char const **description_ptr
);

The engine_data argument is the pointer stored to engine_data_ptr during initialization.

The function can store a NUL-terminated string that identifies an engine to name_ptr. It's preferably a short and memorable word (like "pinyin" and "rime").

The function can store another NUL-terminated string to description_ptr, to provide additional information of the engine, such as version, copyright notice, homepage URL, etc.

Query engine for candidates

The query function is used for asking the engine for candidates of an input text. It must not be NULL.

typedef int (arif_engine_query_func) (
    void                    *engine_data,
    char const              *line,
    int                      offset,
    int                      len,
    int                      num_candidates,
    struct arif_cand const **candidates_ptr
);

The engine_data argument is the pointer stored to engine_data_ptr during initialization.

The line, offset and len arguments correspond to the arguments of function arif_query() with the same name. If line is NULL, it means that the caller is asking for more candidates for the previous input text.

The num_candidates argument is the minimum number of candidates required from the engine. The engine should store the pointer of an array containing at least that many candidates to candidates_ptr, and return the number of candidates. If returning less than num_candidates, it indicates that the entire list of candidates is exhausted. The engine should ensure that the memory location referenced by those candidates are valid until the next query call with non-NULL line.

Note that the engine is not responsible for specifying the display text for a candidate. The display and display_len members of a candidate should be ignored by the caller.

Both line and candidates_ptr can be NULL, in which case the caller is indicating that a candidate at offset is selected with inlined candidate selection (see arif_query()), and the return value is ignored. The engine may make use of this information for purposes like analytics.

Input context without engine

For an input context, when arif_set_engine() is not yet called, or last called with a NULL engine argument, the input context does not have an associated input method engine.

In such input contexts, functions other than arif_set_engine() or arif_ctx_destroy() must not be called.