# IIIMCF library specification.

MIYASHITA
Hisashi
himi@OpenI18N.org

## design goal

IIIMCF (IIIM Client Framework) is a generic C-based client framework which easily makes applications enable intelligent input method facility.

IIIMCF API design goals are:

1. The APIs shall be easily used by not only user applications but also application frameworks like GTk, Qt, .etc.

2. The APIs shall flexibly supply multiple levels of IIIMF services.

3. The APIs must cover full features that IIIMCF suppose.

4. The design of the APIs shall not conflict with other frameworks like toolkits or class libraries.

5. Application users shall control any IM features as possible.

6. The APIs shall be extensible for further enhancement.

## IIIMCF API principles

Like many other frameworks, IIIMCF API is designed by object oriented base. API users are able to forward user inputs, receive the result from IM services, and constitute their own components that handle IM services.

IIIMCF API, however, never restricts any specific message processing models. API users could fully control message flow. IIIMCF API does not deceivingly call event handlers of components without explicitly calling `iiimcf_dispatch_event` except special emergency events. Even if your application wants to behave as an active obejct, IIIMCF API does not actively call your component, and your component does not need to be called passively at all, it has only to call proper APIs to obtain current IM status and result.

Therefore, IIIMCF API can be applied to wide range of targets. It would well worked not only with normal applications but also with many other existing frameworks.

IIIMCF API can be roughly splitted into 3 parts.

1. event control APIs

2. status acquisition APIs

3. component management APIs

In principle, with event control APIs, user applications can forward or dispatch events that usually come from user input, and the applications can obtain the results (i.e. current status) with status acquisition APIs.

If user application need components that handle IM services, and are passively invoked, you can control event flow by event control APIs. But it is not indispensable at all. User application can retrieve any informations with status acquisition APIs.

## IIIMCF event processing model

IIIMCF has three sorts of task delegation system, (1) event forwarding; (2) event dispatchment; and (3) event broadcasting.

Event forwarding is processed by `iiimcf_forward_event`. This function sends a given event to IM service provider(s). IM service provider may be IIIM server side or intermediate LWE(s) like PCE. IIIMCF have to forward events to appropriate service provider(s) that deal with the current input context. If any IM service provider(s) cannot deal with the delegated task, `iiimcf_forward_event` returns IIIMF_STATUS_EVENT_NOT_FORWARDED. See .

### IIIMCF event forwarding model diagram.

Event dispatchment is processed by `iiimcf_dispatch_event`. This function sends a given event to component(s) owned by the current component. Normally, the component handler usually process the delegated task, then return IIIMF_STATUS_SUCCESS. If it does not process or fail to deal with the task, the component handler should return IIIMF_STATUS_COMPONENT_FAIL.

Also each component can delegate the task to subcomponent(s) with `iiimcf_dispatch_event`. If all of the subcomponents do not deal with the task (in this case, all subcomponents must return IIIMF_STATUS_COMPONENT_INDIFFERENT), or any of the subcomponents returns IIIMF_STATUS_COMPONENT_FAIL, `iiimcf_dispatch_event` fails and returns an error status code other than IIIMCF_STATUS_SUCCESS. Of course, the component that fails to dispatch the event can process the task by itself. If it do so, its component handler should return IIIMF_STATUS_SUCCESS. See .

### IIIMCF event dispatchment model diagram.

Notice that IIIMCF does not process any events automatically. Therefore, users have to dispatch or ignore incoming events obtained by `iiimcf_get_next_event` properly; otherwise, such events are stored in the event queue of IIIMCF, that is, those events occupy memory forever (c.f. ).

Event broadcasting is only used for special purpose, and only that type of event processing cannot be controlled by users. IIIMCF library deliver the event to all components by compulsion. `iiimcf_dispatch_event` is completely ignored during event broadcasting. Even though a component fails to process the event, event broadcasting will be succeeded.

Fortunately, event broadcasting is only used for an exceptional situation. Currently, IIIMCF broadcast an event only when a context is destroyed or the connection is shut down. That is, event broadcasting is used to convey the information that all components should process. For detail of connection shutdown, refer to

## connection shutdown

Since in IIIMF, each entity communicates with each other via any sorts of network with IIIM Protocol, IIIMCF must naturally deal with abrupt connection shutdown.

Whenever IIIMCF detects abnormal connection shutdown, it immediately resets all context of the shutdown handle except conversion mode, and broadcast a IIIMCF_EVENT_TYPE_RESET event to all of the components that the handle has. Every component that receives this event should reset its all internal states related to the context except for auxiliary state, and also notifies that all states visible from users have been changed. Note that any auxiliary states (controlled by IM_AUX_DRAW) are sustained because such auxiliary objects have their own initial state that IIIMCF does not know.

Then if the user requests to that context, IIIMCF automatically restore it by requesting the server to recreate it. At this stage, the conversion mode is restored as well, thus we can virtually regard that the conversion mode is persistent even after the shutdown. Therefore the IIIMCF library user does not need to take care of connection shutdown.

## IIIMCF object life-cycle

IIIMCF has various kinds of objects, e.g., IIIMCF_text IIIMCF_lookup_choice , IIIMCF_event , .etc. In principle, users do not need to manage such objects' construction nor destruction. In principle, IIIMCF library manages life-cycles of such objects.

There are only two rules that you must follow. First, you must be sure to call `iiimcf_ignore_event` for the event obtained by `iiimcf_get_next_event` . IIIMCF library does not discard the event until users call `iiimcf_get_next_event` to it.

Second, users are able to create IIIMCF_attr by `iiimcf_create_attr` and duplicate IIIMCF_text by `IIIMCF_duplicate_text` . Such objects are never deleted by IIIMCF library so that users must destroy it by `iiimcf_destroy_attr` or `iiimcf_destroy_text` . Of course, users must not delete other IIIMCF_text and IIIMCF_attr objects that are not created or duplicated by these function.

Note that any objects other than such created attr or duplicated text may be inaccessible after calling `iiimcf_forward_event` or `iiimcf_dispatch_event` , or returning from component entry function. After such operations, you have to retrieve again such objects by proper information obtaining APIs.

However, there is one exception to the above rule. `iiimcf_dispatch_event` does not discard the dispatched event. Therefore, you have to call `iiimcf_ignore_event` to it as well. The following example illustrates it.

    IIIMF_status
    your_component_entry_function(
        IIIMCF_context context,
        IIIMCF_event event,
        IIIMCF_component current,
        IIIMCF_component parent
    )
    {
        IIIMCF_event newevent;
        IIIMCF_keyevent kev;
        /* At this point, you can access "event". */
        iiimcf_dispatch_event(context, event);
        /* Also at this point, you can still access "event"
           despite having dispatched it. */
        kev.keychar = kev.keycode =  kev.modifier = kev.time_stamp = 0;
        iiimcf_create_keyevent(kev, &newevent);
        /* At this point, you can access both "event" and "newevent". */
        iiimcf_dispatch_event(context, newevent);
        /* Also at this point, you can access both "event" and "newevent". */
        iiimcf_ignore_event(newevent);
        /* Now newevent is discarded, you cannot access "newevent". */

        return IIIMF_STATUS_SUCCESS;
    }

NOTICE: old version of libiiimcf had discarded any events dispatched by `iiimcf_dispatch_event` . But in the new version, you MUST call `iiimcf_ignore_event` to all events that are obtained by `iiimcf_get_next_event` even though they are dispatched by `iiimcf_dispatch_event` .

## default component hierarchy

IIIMCF has the following predefined components by default. Users can use these components by making them parental components of user components.

The root component

  The root component processes all of the incoming events. In IIIMCF, it can be regarded as user's top level program (i.e. the program not invoked from component interface) itself because the top level program can receive all events by `iiimcf_get_next_event`, and dispatch any of them arbitrarily.

"org.OpenI18N.IIIMCF.UI" component

  This component processes only UI related events. If it receives any events associated with preedit, lookup-choice, and status, it dispatches them to all child components; otherwise, simply ignore them and return IIIMF_STATUS_COMPONENT_INDIFFERENT.

"org.OpenI18N.IIIMCF.UI.preedit" component

  This component processes only preedit events. If it receives any events associated with preedit, it dispatches them to all child components; otherwise, simply ignore them and return IIIMF_STATUS_COMPONENT_INDIFFERENT.

"org.OpenI18N.IIIMCF.UI.lookup_choice" component

  This component processes only preedit events. If it receives any events associated with lookup choice, it dispatches them to all child components; otherwise, simply ignore them and return IIIMF_STATUS_COMPONENT_INDIFFERENT.

"org.OpenI18N.IIIMCF.UI.status" component

  This component processes only preedit events. If it receives any events associated with status, it dispatches them to all child components; otherwise, simply ignore them and return IIIMF_STATUS_COMPONENT_INDIFFERENT.

"org.OpenI18N.IIIMCF.event" component

  This component processes only forwarded events. If it receives any events forwarded by IM service provider(s), e.g. key event, trigger-notify event, or something like, it dispatches them to all child components; otherwise, simply ignore them and return IIIMF_STATUS_COMPONENT_INDIFFERENT.

"org.OpenI18N.IIIMCF.event.key" component

  This component processes only forwarded key events. If it receives those events, it dispatches them to all child components; otherwise, simply ignore them and return IIIMF_STATUS_COMPONENT_INDIFFERENT.

"org.OpenI18N.IIIMCF.event.trigger_notify" component

  This component processes only trigger notify events. If it receives those events, it dispatches them to all child components; otherwise, simply ignore them and return IIIMF_STATUS_COMPONENT_INDIFFERENT.

"org.OpenI18N.IIIMCF.AUX" component

  This component processes only AUX related events. If it receives IIIMCF_EVENT_TYPE_AUX_DRAW events, it dispatches them to all child components; otherwise, simply ignore them and return IIIMF_STATUS_COMPONENT_INDIFFERENT.

Notice that "org.OpenI18N.IIIMCF" is reserved component domain name by IIIMCF. You MUST NOT use it for your own components' domain name.

The following figure illustrates the default component hierarchy.

### IIIMCF default component hierarchy diagram.

## Thread safety

In IIIMCF library, any objects are thread-safe in the sense that multiple threads can simultaneously access distinct objects. The user is responsible for mutual exclusion among multiple threads while they are accessing the same object.

Note that simultaneously accessing distinct contexts are safe even though they belong to the same handle (i.e., these contexts are created from the same handle). Therefore, it is safe that each thread has its own contexts created by the single handle that is shared throughout the process.

## API reference

### initialization and finalization

    	   IIIMF_status iiimcf_initialize
    	  IIIMCF_attr  attr

`iiimcf_initialize` initializes IIIMCF library. You MUST call this function once before using IIIMCF APIs, except for `iiimcf_attr_attr` , `iiimcf_destroy_attr` , `iiimcf_attr_put_*_value` , and `iiimcf_attr_get_*_value` .

    	   IIIMF_status iiimcf_finalize

`iiimcf_finalize` initializes IIIMCF library. This function releases all resources reserved or used by IIIMCF library.

Note that you MUST destroy all handles before calling this function.

### create and destroy handle

    	   IIIMF_status iiimcf_create_handle
    	  IIIMCF_attr  attr
    	  IIIMCF_handle*phandle

`iiimcf_create_handle` creates a handle, which is used as a descriptor to manage IIIMCF operations. IIIMCF_handle set to `phandle`.

`attr` specifies the additional attributes which can be used for creating the handle. Currently effective attributes are the followings.

IIIMCF_ATTR_SERVER_ADDRESS

  The corresponding value must be char* string that holds the address of IIIM server.

IIIMCF_ATTR_SERVER_SERVICE

  The corresponding value must be char* string that holds the service name of IIIM server.

IIIMCF_ATTR_USERNAME

  The corresponding value must be char* string that holds username.

IIIMCF_ATTR_CLIENT_TYPE

  The corresponding value must be char* string that specifies the client type, which will be sent to IIIMSF as a part of client descriptor.

IIIMCF_ATTR_DISABLE_AUTOMATIC_RESTORATION

  The corresponding value must be a number, and if it is non-0, the connection owned by the created handle will not be restored automatically. By default, libiiimcf will automatically restore a closed connection if it requires.

    	     IIIMF_status iiimcf_finalize
    	    IIIMCF_handle  handle

`iiimcf_destroy_handle` destroys IIIMCF_handle, `handle`. That is, direct service providers to finish all context, saves any required states like user dictionary or something else.

### create and destroy context

    	     IIIMF_status iiimcf_create_context
    	    IIIMCF_handle handle
    	    IIIMCF_attr  attr
    	    IIIMCF_context* pcontext

`iiimcf_create_context` creates input context related to `handle`.

`attr` specifies the additional attributes that should be compliant to a created input context. Currently effective attributes are the followings.

IIIMCF_ATTR_INPUT_LANGUAGE

  The corresponding value must be IIIMCF_language. This attribute specifies the input language of required input context.

IIIMCF_ATTR_INPUT_METHOD

  The corresponding value must be IIIMCF_input_method. This attribute specifies the input method of required input context.

IIIMCF_ATTR_DISABLE_AUTOMATIC_TRIGGER_NOTIFY

  The corresponding value must be a number. By default, IIIMCF library automatically turn the conversion mode on or off when accepting the trigger keys specified by IIIMSF. If this value is non-zero, IIIMCF library does not automatically treat such trigger keys.

    	     IIIMF_status iiimcf_destroy_context
    	    IIIMCF_context  context

`iiimcf_destroy_context` destroys `context`.

    	     IIIMF_status iiimcf_context_get_attr
    	    IIIMCF_context  context
    	    IIIMCF_attr*  pattr

`iiimcf_context_get_attr` gets IIIMCF attribute that is related to `context`. Notice that the returned attribute is not the same as what is given in `iiimcf_create_context` . This API is used for associating user's arbitrary data with a context. When the user put values to the attribute, it remembers those values until the context is destroyed.

### data manipulation APIs

#### IIIMCF attribute

IIIMCF has an attribute that holds zero or more of key and value pair(s). Key must be a number and some numbers are reserved by IIIMCF. However, users can freely use the range after IIIMCF_ATTR_PRIVATE_START.

IIIMCF_ATTR_NULL is a special attribute, which has no key and value pair. Use this attribute if you would like to specify no attribute in the argument of IIIMCF API function.

An value of IIIMCF attribute must be a number(int), a constant string(const char*), or a pointer(void*). When putting a value, the slot that has the value remembers what type of value is put, then if you try to get another type of value from the slot, IIIMCF returns IIIMF_STATUS_ARGUMENT.

    	     IIIMF_status iiimcf_create_attr
    	    IIIMCF_attr* pattr

`iiimcf_create_attr` creates new IIIMCF attribute, and set it to pattr.

    	     IIIMF_status iiimcf_destroy_attr
    	    IIIMCF_attr attr

`iiimcf_destroy_attr` destroys `attr` .

    	     IIIMF_status iiimcf_attr_put_string_value
    	    IIIMCF_attr attr
    	    int property
    	    const char* str

`iiimcf_attr_put_string_value` sets `str` to `property` of `attr` as an attribute value. You can access the value by `iiimcf_attr_get_string_value` . When already put value to `property`, the corresponding slot is overridden, but the type of slot must be string. If the type is not string, this function returns IIIMF_STATUS_ARGUMENT.

    	     IIIMF_status iiimcf_attr_get_string_value
    	    IIIMCF_attr attr
    	    int property
    	    const char** pstr

`iiimcf_attr_get_string_value` sets the string associated with `property` of `attr` to `pstr`. If `attr` has no value corresponds to `property`, this function returns IIIMF_STATUS_NO_ATTR_VALUE. If the type of the value associated with `property` is not string, this function returns IIIMF_STATUS_ARGUMENT.

    	     IIIMF_status iiimcf_attr_put_integer_value
    	    IIIMCF_attr attr
    	    int property
    	    int number

`iiimcf_attr_put_integer_value` sets `number` to `property` of `attr` as an attribute value. You can access the value by `iiimcf_attr_get_integer_value` . When already having put value to `property`, the corresponding slot is overridden, but the type of slot must be integer. If the type is not integer, this function returns IIIMF_STATUS_ARGUMENT.

    	     IIIMF_status iiimcf_attr_get_integer_value
    	    IIIMCF_attr attr
    	    int property
    	    int* pnumber

`iiimcf_attr_get_integer_value` set the integer associated with `property` of `attr` to `pnumber`. If `attr` has no value corresponds to `property`, this function returns IIIMF_STATUS_NO_ATTR_VALUE. If the type of the value associated with `property` is not integer, this function returns IIIMF_STATUS_ARGUMENT.

    	     IIIMF_status iiimcf_attr_put_ptr_value
    	    IIIMCF_attr attr
    	    int property
    	    void* ptr

`iiimcf_attr_put_ptr_value` sets `ptr` to `property` of `attr` as an attribute value. You can access the value by `iiimcf_attr_get_ptr_value` . When already having put value to `property`, the corresponding slot is overridden, but the type of slot must be pointer. If the type is not ptr, this function returns IIIMF_STATUS_ARGUMENT.

    	     IIIMF_status iiimcf_attr_get_ptr_value
    	    IIIMCF_attr attr
    	    int property
    	    void** pptr

`iiimcf_attr_get_ptr_value` set the pointer associated with `property` of `attr` to `pptr`. If `attr` has no value corresponds to `property`, this function returns IIIMF_STATUS_NO_ATTR_VALUE. If the type of the value associated with `property` is not pointer, this function returns IIIMF_STATUS_ARGUMENT.

#### IIIMCF text

IIIMCF_text is an opaque object that conveys structured text information, i.e., UTF-16 based string, character feedback attribute, and text property value associated with any intervals of the text. You can access them only via the following functions.

    	     IIIMF_status iiimcf_get_text_utf16string
    	    IIIMCF_text text
    	    const IIIMP_card16** putf16

`iiimcf_get_text_utf16string` set UTF-16 string of `text` to `putf16`, which is terminated by 0.

You MUST NOT change the obtained string in `putf16`.

    	     IIIMF_status iiimcf_get_text_length
    	    IIIMCF_text text
    	    int* plen

`iiimcf_get_text_length` set the length in UTF-16 element of `text` to `plen`.

    	     IIIMF_status iiimcf_get_char_with_feedback
    	    IIIMCF_text text
    	    int pos
    	    IIIMP_card16* pch
    	    int* pnum_feedbacks
    	    const IIIMP_card32** pfeedback_id
    	    const IIIMP_card32** pfeedback

`iiimcf_get_char_with_feedback` sets a UTF-16 element and the corresponding feedbacks in `text`.

This function extract a UTF-16 element `pch` where `pos` points in the UTF-16 string of `text`.

It also sets feedback information into `pfeedback_id` and `pfeedback` arrays. The size of both are equal to `*pnum_feedbacks`.

    	     IIIMF_status iiimcf_duplicate_text
    	    IIIMCF_text src
    	    IIIMCF_text* pduplicated

`iiimcf_duplicate_text` duplicates `src` and set it to `pduplicated`.

When you don't need the duplicated text, you must destroy it by `iiimcf_destroy_text` in order to release resources.

    	     IIIMF_status iiimcf_destroy_text
    	    IIIMCF_text text

`iiimcf_destroy_text` destroys `text` that must be duplicated by users.

Note that you MUST NOT destroy any texts other than duplicated ones, because such texts are managed by IIIMCF library.

#### IIIMCF lookup choice

IIIMCF_lookup_choice is an opaque object that conveys lookup choice data, i.e., candidates and their label texts. You can access them only via the following APIs.

    	     IIIMF_status iiimcf_get_lookup_choice_size
    	    IIIMCF_lookup_choice lookup_choice
    	    int* psize
    	    int* pindex_of_first_candidate
    	    int* pindex_of_last_candidate
    	    int* pindex_of_current_candidate

`iiimcf_get_lookup_choice_size` sets the number of items in `lookup_choice` to `psize`, the index of the first candidate to `pindex_of_first_candidate`, the index of the last candidate to `pindex_of_last_candidate`, the index of the current candidate to `pindex_of_current_candidate`.

    	     IIIMF_status iiimcf_get_lookup_choice_configuration
    	    IIIMCF_lookup_choice lookup_choice
    	    int* pchoices_per_window
    	    int* pnumber_of_rows
    	    int* pdirection

`iiimcf_get_lookup_choice_configuration` informs how the lookup choice should be presented. This function sets the number of choices in one window to `pchoices_per_window`, the number of rows to `pnumber_of_rows`, the number of columns to `pnumber_of_columns`, and the direction in which the lookup choice should be ordered to `pdirection`, which is one of the following:

IIIMCF_LOOKUP_CHOICE_HORIZONTAL_DIRECTION

  That means the items should be ordered horizontally.

IIIMCF_LOOKUP_CHOICE_VERTICAL_DIRECTION

  That means the items should be ordered vertically.

    	     IIIMF_status iiimcf_get_lookup_choice_item
    	    IIIMCF_lookup_choice lookup_choice
    	    int idx
    	    IIIMCF_text* pcandidate
    	    IIIMCF_text* plabel
    	    int* pflag

`iiimcf_get_lookup_choice_item` retrieves an item in `lookup_choice`. The item is identified by `idx` that ranges from 0 to the size of `lookup_choice` - 1.

This function stores a candidate text into `pcandidate`, a label text into `plabel`, and flags of the item into `pflag`.

Currently flag is a combination of the following bits:

IIIMCF_LOOKUP_CHOICE_ITEM_ENABLED

  If this bit is set, the corresponding item is enabled. "Enabled" means user application must show the item in the lookup choice area. If it is not set, user application must not show the item.

IIIMCF_LOOKUP_CHOICE_SELECTED_ITEM

  If this bit is set, the corresponding item is now selected.

    	     IIIMF_status iiimcf_get_lookup_choice_title
    	    IIIMCF_lookup_choice lookup_choice
    	    IIIMCF_text* ptitle

`iiimcf_get_lookup_choice_title` sets the title in `lookup_choice` to `ptitle`

#### IIIMCF language

IIIMCF_language is an opaque object that conveys language information.

    	    IIIMF_status iiimcf_get_language_id
    	    IIIMCF_language lang
    	    char* plangid

`iiimcf_get_language_id` gets a language id registered by RFC1766. This function stored id to `plangid`.

#### IIIMCF input method

IIIMCF_input_method is an opaque object that conveys input method information.

    	    IIIMF_status iiimcf_get_input_method_desc
    	    IIIMCF_input_method input_method
    	    const IIIMP_card16** pinput_method_idname
    	    const IIIMP_card16** pinput_method_hrn
    	    const IIIMP_card16** pinput_method_domain

`iiimcf_get_input_method_desc` gets a description of `input_method`.

This function stores the identifier name of the input method into `pinput_method_idname`, a human readable name into `pinput_method_hrn`, a reverse domain name into `pinput_method_domain`.

    	    IIIMF_status iiimcf_get_input_method_languages
    	    IIIMCF_input_method input_method
    	    int* pinput_method_language_size
    	    IIIMCF_language** pplangages

`iiimcf_get_input_method_languages` gets list of languages supported by `input_method`.

This function stores an array of IIIMCF_language* into pplanguages, and stores size of the array into `pinput_method_language_size`. That is, you could access all elements of the array by something like the following code:

    {
      int i, size;
      const char *id;
      IIIMCF_language *plangs;

      if (iiimcf_get_input_method_languages(input_method, &size, &plangs)
          == IIIMF_STATUS_SUCCESS) {
        for (i = 0; i < size; i++) {
          if (iiimcf_get_language_id(plangs[i], &id)
    	  == IIIMF_STATUS_SUCCESS) {
    	...
          }
          ...
        }
      }
    }

#### IIIMCF downloaded object

IIIMCF supports object downloading, which is encapsulated by an opaque object of IIIMCF_downloaded_object.

    	     IIIMF_status iiimcf_get_downloaded_object
    	    IIIMCF_handle handle
    	    int num_objs
    	    const IIIMCF_object_descriptor**ppdesc
    	    IIIMCF_downloaded_object* pobjs

`iiimcf_get_downloaded_object` gets downloadable objects from IIIMSF.

`num_objs` is a number of objects that must be equal to the array length of `ppdesc` and `pobjs`.

`ppdesc` is an array of the pointer of IIIMCF_object_descriptor, which must consist of the pointers returned by `iiimcf_get_object_descriptor_list`. You MUST NOT set the pointer of your own IIIMCF_object_descriptor .

If success, this function sets the corresponding IIIMCF_downloaded_object to the array specified by `pobjs`.

    	     IIIMF_status iiimcf_get_downloaded_object_descriptor
    	    IIIMCF_downloaded_object object
    	    const IIIMCF_object_descriptor** ppdesc

`iiimcf_get_downloaded_object_descriptor` gets the object descriptor of `object`, and set it to `*ppdesc`.

    	     IIIMF_status iiimcf_get_downloaded_object_filename
    	    IIIMCF_downloaded_object object
    	    const IIIMCF_card16** pfilename

`iiimcf_get_downloaded_object_filename` gets the filename of `object`.

Notice that `object` must be a BINARYFILE_OBJECT defined by IIIM Protocol Specification, i.e., it must be IIIMP_IMATTRIBUTE_BINARY_GUI_OBJECT, IIIMP_IMATTRIBUTE_BINARY_LIGHT_WEIGHT_ENGINE_OBJECT, or IIIMP_IMATTRIBUTE_SCRIPT_LIGHT_WEIGHT_ENGINE_OBJECT.

### state checking APIs

    	   IIIMF_status iiimcf_is_UIstate_changed
    	  IIIMCF_context context
    	  int* pflag

`iiimcf_is_UIstate_changed` checks if the state of UI in the current input context, and set the result to `pflag` in bitwise pattern.

`*pflag` has a combination of the following bits:

IIIMCF_STATE_PREEDIT_CHANGED

  This bit is set if the preedit text is changed by the previous event forwarding.

IIIMCF_STATE_LOOKUP_CHOICE_CHANGED

  This bit is set if the lookup choice is changed by the previous event forwarding.

IIIMCF_STATE_STATUS_CHANGED

  This bit is set if the status text Status text is an indication text for input method users, which is usually used for notifying current status of the input method. is changed by the previous event forwarding.

IIIMCF_STATE_COMMIT_REQUIRED

  This bit is set if the input method requires to commit resultant text from the previous event forwarding.

### information obtaining APIs

IIIMCF language is an opaque object that conveys version information of the library and protocol.

    	   IIIMF_status iiimcf_get_version_number
    	  IIIMCF_handle handle
    	  int flag
    	  int* pversion_number

`iiimcf_get_vesion_number` sets a version number to `*pversion_number`.

`flag` specifies an item of which you want to query the version, and also specifies the category of version number like `major' or `minor'.

Flags for specifying an item is the followings:

IIIMCF_LIBRARY_VERSION

  get IIIMCF library version.

IIIMCF_PROTOCOL_VERSION

  get IIIM protocol version currently enabled.

Flags for specifying category of version number:

IIIMCF_MINOR_VERSION

  get the minor part of version. If the entity has no minor version, `iiimcf_get_version_number` returns 0.

IIIMCF_MAJOR_VERSION

  get major part of the version.

`flag` must be a combination of both two sorts of flags. If you specify an invalid flag, it will return IIIMF_STATUS_ARGUMENT.

    	   IIIMF_status iiimcf_get_supported_languages
    	  IIIMCF_handle handle
    	  int* pnum_langs
    	  IIIMCF_language** pplangs

`iiimcf_get_supported_languages` retrieves a language list supported by the current input method service providers. This function stores the number of languages into `pnum_langs`, and an array of IIIMCF_language* into `pplangs`.

    	   IIIMF_status iiimcf_get_supported_input_methods
    	  IIIMCF_handle handle
    	  int* pnum_input_methods
    	  IIIMCF_input_method** ppinput_methods

`iiimcf_get_supported_input_methods` retrieves an input method list supported by the current input method service providers. This function stores the number of input methods into `pnum_input_methods`, and an array of IIIMCF_input_method* into `ppinput_methods`.

    	   IIIMF_status iiimcf_get_object_descriptor_list
    	  IIIMCF_handle handle
    	  int* pnum_object_descriptors
    	  const IIIMCF_object_descriptor** ppdesc

`iiimcf_get_object_descriptor_list` retrieves a list of object descriptors. This function stores the number of object descriptors into `pnum_object_descriptors`, and an array of IIIMCF_object_descriptor* into `ppdesc`.

IIIMCF_object_descriptor is defined as follows:

    typedef struct {
        int category;
        size_t size;
        int predefined_id;
        int dynamic_id;
        const IIIMP_card16 *domain;
        const IIIMP_card16 *hrn;
        const IIIMP_card16 *signature;
        const IIIMP_card16 *user;
    } IIIMCF_object_descriptor;

Each member corresponds to the item of OBJECTDESCRIPTOR defined by the IIIM protocol specification.

    	   IIIMF_status iiimcf_get_current_conversion_mode
    	  IIIMCF_context context
    	  int* pflag

`iiimcf_get_current_conversion_mode` get the current conversion mode of `context`.

This function stores non-zero value to `*pflag` if the current conversion mode is on; otherwise, stores zero.

    	   IIIMF_status iiimcf_get_preedit_text
    	  IIIMCF_context context
    	  IIIMCF_text ptext
    	  int* pcaret_position

`iiimcf_get_preedit_text` get the current preedit text and the current caret position of `context`. This function stores the preedit text into `ptext`, and the caret position into `pcaret_position`.

If currently preedit text is not enabled, this function returns IIIMF_STATUS_NO_PREEDIT.

    	   IIIMF_status iiimcf_get_status_text
    	  IIIMCF_context context
    	  IIIMCF_text ptext

`iiimcf_get_preedit_text` gets the current status text of `context`. This function stores the status text into `ptext`.

If currently status text is not enabled, this function returns IIIMF_STATUS_NO_STATUS_TEXT.

    	   IIIMF_status iiimcf_get_lookup_choice
    	  IIIMCF_context context
    	  IIIMCF_lookup_choice plookup_choice

`iiimcf_get_lookup_choice` gets the current lookup choice of `context`. This function stores the lookup choice into `plookup_choice`.

If currently lookup choice is not enabled, this function returns IIIMF_STATUS_NO_LOOKUP_CHOICE.

    	   IIIMF_status iiimcf_get_committed_text
    	  IIIMCF_context context
    	  IIIMCF_text ptext

`iiimcf_get_committed_text` gets the committed text by the previous event forwarding or operation issuing in the input context specified by `context`. This function stores the committed text into `ptext`.

If currently `context` has no valid committed text, this function returns IIIMF_STATUS_NO_COMMITTED_TEXT.

    	   IIIMF_status iiimcf_get_aux_draw_data
    	  IIIMCF_context context
    	  const IIIMP_card16* aux_name
    	  IIIMP_card32 class_idx
    	  int* pnum_intvals
    	  const IIIMP_card32** ppintvals
    	  int* pnum_strvals
    	  const IIIMP_card16*** ppstrs

Get the latest auxiliary data sent from IIIMSF.

`iiimcf_get_aux_draw_data` retrieves auxiliary data which is sent with IM_AUX_DRAW. This function can get only the latest one, i.e., cannot get the data sent with the two previous IM_AUX_DRAW.

Users have to specify the auxiliary name to `aux_name` and the window class index to `class_idx`. If the corresponding IM_AUX_DRAW is not sent from the server, this function will return IIIMF_STATUS_NO_AUX.

`iiimcf_get_aux_draw_data` sets a array of integer values to `ppintvals`, size of the array to `pnum_intvals`, and a array of string values to `ppstrs`, size of the array to `pnum_strvals`.

Because this function returns many values via given pointers, for convenience, users can set NULL to any of pnum_intvals, ppintvals, pnum_strvals, and ppstrs when they don't want to receive data. This function simply ignores to set the data that corresponds to the NULL pointer.

### Event

In IIIMCF API, event is used to delegate task(s) to other service providers or component. IIIMCF API has two sorts of event flow, one is forwarding, and the other is dispatching.

Event forwarding is used for sending events to IM service providers. IM service providers will deal with the forwarded event, and return the result as a response.

Event dispatchment is used for sending events to IIIMCF components that are registered beforehand. IIIMCF component is ordered in tree structure. One IIIMCF component has sub-components more than 0. We can regard IIIMCF library as a top level component itself. `iiimcf_dispatch_event` sends an event to all of sub-components that the current component has.

#### event type

    	    IIIMF_status iiimcf_get_event_type
    	    IIIMCF_event event
    	    IIIMCF_event_type* pevent_type

Each IIIMCF event has its own event type. Currently IIIMCF defines only one event type, but in future, we will append more event types.

IIIMCF_EVENT_TYPE_KEYEVENT

  It means the event is key event. One key event has 4 integer values, code, character code, modifier, time stamp.

IIIMCF_event_type is defined as a simple C enumerator.

`iiimcf_get_event_type` gets the event type of `event`, and set it to `pevent_type`.

#### event constructor

Users can construct events by the following functions. Users MUST ignore, forward, or dispatch constructed events. IIIMCF event forwarder or dispatcher guarantee to destruct such events after processing the events.

    	    IIIMF_status iiimcf_create_keyevent
    	    IIIMCF_keyevent keyevent
    	    IIIMCF_event* pevent

`iiimcf_create_keyevent` creates an event whose event type is IIIMCF_EVENT_TYPE_KEYEVENT, and value is `keyevent`. The generated event is stored to `pevent`.

IIIMCF_keyevent is a simple transparent C structure. The definition is:

    typedef struct IIIMCF_keyevent {
        IIIMP_int32 keycode;
        IIIMP_int32 keychar;
        IIIMP_int32 modifier;
        IIIMP_int32 time_stamp;
    } IIIMCF_keyevent;

Note that IIIMP_int32 is 32 bit signed integer type.

    	    IIIMF_status iiimcf_create_trigger_notify_event
    	    int flag
    	    IIIMCF_event* pevent

`iiimcf_create_trigger_notify_event` creates an event of IIIMCF_EVENT_TYPE_TRIGGER_NOTIFY. The generated event is stored to `pevent`.

Trigger notify event is used to turn the IM on or off. When trigger notify event is forwarded to the server, the server would turn the IM conversion on if `flag` is 1, turn that off if `flag` is 0. If such event is dispatched to components, they should change the state to turn the IM conversion on or off.

    	    IIIMF_status iiimcf_create_aux_setvalues_event
    	    IIIMP_card16* aux_name
    	    IIIMP_card32 class_idx
    	    int num_intvals
    	    const IIIMP_card32* pintvals
    	    int num_strvals
    	    const IIIMP_card16** pstrs
    	    IIIMCF_event* pevent

`iiimcf_create_aux_setvalues_event` creates an event of `IIIMCF_EVENT_TYPE_AUX_SETVALUES`. The generated event is stored to `pevent`.

AUX setvalues event is used to transfer the arbitrary information from client to server. You can forward the created event with `iiimcf_forward_event`. `aux_name` is an auxiliary name. `class_idx` is a window class index. `pintvals` is an array of integer data, and the array size must be set to `num_intvals`. `pstrs` is an array of string(UTF-16) data that must be terminated by 0, and the array size must be set to `num_strvals`.

#### event value

Each IIIMCF event has its own value. The value type depends on its IIIMCF_event_type. Users can access values of an event by the following function.

    	    IIIMF_status iiimcf_get_keyevent_value
    	    IIIMCF_event event
    	    IIIMCF_keyevent* pkeyevent

`iiimcf_get_keyevent_value` get key event value of `event`, and set it to `pkeyevent`.

When `event` is not IIIMCF_EVENT_TYPE_KEYEVENT, this function fails and return IIIMF_STATUS_ARGUMENT.

    	    IIIMF_status iiimcf_get_trigger_notify_flag
    	    IIIMCF_event event
    	    int* pflag

`iiimcf_get_trigger_notify_flag` gets the boolean flag of the trigger notify event of `event`, and set it to `pflag`.

When `event` is not IIIMCF_EVENT_TYPE_KEYEVENT, this function fails and return IIIMF_STATUS_ARGUMENT.

    	    IIIMF_status iiimcf_get_aux_event_value
    	    IIIMCF_event event
    	    const IIIMP_card16** paux_name
    	    IIIMP_card32* pclass_idx
    	    int* pnum_intvals
    	    const IIIMP_card32** ppintvals
    	    int* pnum_strvals
    	    const IIIMP_card16*** ppstrs

`iiimcf_get_aux_event_value` gets the value of the auxiliary event of `event`.

This function sets the auxiliary name to `paux_name`; the window class index to `pclass_idx`; the integer array data to `ppintvals` and its array size to `pnum_intvals`; and the string array data, each item string is terminated by 0, to `ppstrs` and its array size to `pnum_strvals`.

Because this function returns many values via given pointers, for convenience, users can set NULL to any of paux_name, pclass_idx, pnum_intvals, ppintvals, pnum_strvals, and ppstrs when they don't want to receive data. This function simply ignores to set the data that corresponds to the NULL pointer.

When `event` is not a proper auxiliary event, this function fails and return IIIMF_STATUS_ARGUMENT.

#### event flow control

    	    IIIMF_status iiimcf_forward_event
    	    IIIMCF_context context
    	    IIIMCF_event event

`iiimcf_forward_event` forwards `event` to input method service providers. The forwarded event is processed in the input context specified by `context`.

This function may change the various IM states. So normally, you need to check the state change by checking incoming events or by state checking APIs.

This function returns IIIMF_STATUS_EVENT_NOT_FORWARDED if the forwarded event has not been processed by any service provider(s). If it is, you maybe have to process the event by yourselves.

    	    IIIMF_status iiimcf_dispatch_event
    	    IIIMCF_context context
    	    IIIMCF_event event

`iiimcf_dispatch_event` dispatches `event` to sub components owned by the current component. This function provides one only method to invoke sub components.

    	    IIIMF_status iiimcf_get_next_event
    	    IIIMCF_context context
    	    IIIMCF_event* pevent

`iiimcf_get_next_event` retrieves the first new event, and delete it from the queue. This function set the new event to `pevent`. `context` identifies the current input context and the current component. Note that this function does NOT wait for a next event. If there are no incoming events, this function immediately returns IIIMF_STATUS_NO_EVENT.

Note that you MUST ignore, dispatch, or forward the obtained event when you don't refer it afterwards.

    	    IIIMF_status iiimcf_peek_next_event
    	    IIIMCF_context context
    	    IIIMCF_event* pevent

`iiimcf_peek_next_event` retrieves the first new event, but do NOT delete it from the queue. Other features are the same with `iiimcf_get_next_event`.

Note that you don't have to ignore, dispatch, or forward the peeked event.

    	    IIIMF_status iiimcf_ignore_event
    	    IIIMCF_event event

`iiimcf_ignore_event` ignores `event`. After it, you cannot access `event` any longer.

#### component management

Currently IIIMCF_component consists of one name, one function pointer, one parental component, and attributes of IIIMCF_attr.

Component name must be an identifier. In other word, you cannot register two components in the same address.

As stated earlier, IIIMCF component is ordered in tree structure. Thus if you would like to register your own component, you have to specify the parent component.

    	    IIIMF_status iiimcf_register_component
    	    const char* name
    	    IIIMCF_component_interface interface
    	    IIIMCF_component parent
    	    IIIMCF_component* pcomp

`iiimcf_register_component` registers user's component. `name` must be a unique identifier for the component. `interface` must be a function pointer. The function prototype is the following:

    	    typedef IIIMF_status (*IIIMCF_component_interface)(IIIMCF_context context,
    	                                                       IIIMCF_event event,
    	                                                       IIIMCF_component current,
    	                                                       IIIMCF_component parent);

`parent` must be a parental component. If it is IIIMCF_ROOT_COMPONENT, IIIMCF library itself become a parent of the created component. This function stores the created component to `pcomp`.

If `name` has already been registered, this function returns IIIMF_STATUS_COMPONENT_DUPLICATED_NAME.

The registered component will be invoked via `interface` with four arguments. `event` has the event currently processed by the dispatchment. `context` has the current input context. `current` has the invoked component itself. `parent` has the parental component. This handler must return IIIMF_STATUS_SUCCESS if it can successfully process the task. If it fails to process the task, the handler should return IIIMF_STATUS_COMPONENT_FAIL. Otherwise, it must return IIIMF_STATUS_COMPONENT_INDIFFERENT.

This function returns IIIMF_STATUS_COMPONENT_FAIL if any of the component returns IIIMF_STATUS_COMPONENT_FAIL. Meanwhile, this function returns IIIMF_STATUS_COMPONENT_INDIFFERENT if the current component has no subcomponent or all of the subcomponent returns IIIMF_STATUS_COMPONENT_INDIFFERENT.

    	    IIIMF_status iiimcf_unregister_component
    	    IIIMCF_component component

`iiimcf_unregister_component` unregisters `component`.

    	    IIIMF_status iiimcf_get_component
    	    const char* name
    	    IIIMCF_component* pcomponent

`iiimcf_get_component` look up registered component by `name`.

If this function fail to find out a component named `name`, returns IIIMF_NO_COMPONENT.

    	    IIIMF_status iiimcf_component_get_attr
    	    IIIMCF_component component
    	    IIIMCF_attr* pattr

`iiimcf_component_get_attr` get the attributes of IIIMCF_attr associated with the component, `component`. This function stores the attributes to `pattr`.

Note that users can edit component attribute in order to store users' private data.

### event type list

IIIMCF_EVENT_TYPE_DESTROY

  This type of event will be broadcasted to all components whenever a context is being destroyed, and it has no value.

IIIMCF_EVENT_TYPE_RESET

  This type of event will be sent to components whenever they have to be reset their internal states associated with the context where being sent the event. This type of event is broadcasted to all of the components if the connection is shut down. For detail, refer to .

IIIMCF_EVENT_TYPE_KEYEVENT

  This type of event has a keyevent value, which can be obtained with `iiimcf_get_keyevent_value`. It is often used to forward a key event to or receive one from IM service provider(s).

IIIMCF_EVENT_TYPE_TRIGGER_NOTIFY

  This type of event has a flag to specify the conversion mode, which is obtained with `iiimcf_get_trigger_notify_flag`. It is often used to forward a trigger notify to or receive one from IM service provider(s).

IIIMCF_EVENT_TYPE_UI_PREEDIT_START

  This type of event is used to notify a component to show the preedit text. It has no event value.

IIIMCF_EVENT_TYPE_UI_PREEDIT_CHANGE

  This type of event is used to notify a component to update the preedit text because that have been changed by IM service provider(s). This type of event has no event value.

IIIMCF_EVENT_TYPE_UI_PREEDIT_DONE

  This type of event is used to notify a component to hide or turn off the preedit text. It has no event value.

IIIMCF_EVENT_TYPE_UI_LOOKUP_CHOICE_START

  This type of event is used to notify a component to show lookup choice information. It has no event value.

IIIMCF_EVENT_TYPE_UI_LOOKUP_CHOICE_CHANGE

  This type of event is used to notify a component to update the lookup choice information because that have been changed by IM service provider(s). This type of event has no event value.

IIIMCF_EVENT_TYPE_UI_LOOKUP_CHOICE_DONE

  This type of event is used to notify a component to hide or turn off the lookup choice presentation. It has no event value.

IIIMCF_EVENT_TYPE_UI_STATUS_START

  This type of event is used to notify a component to show status information. It has no event value.

IIIMCF_EVENT_TYPE_UI_STATUS_CHANGE

  This type of event is used to notify a component to update the status information because that have been changed by IM service provider(s). This type of event has no event value.

IIIMCF_EVENT_TYPE_UI_STATUS_DONE

  This type of event is used to notify a component to hide or turn off the status presentation. It has no event value.

IIIMCF_EVENT_TYPE_UI_COMMIT

  This type of event is used to notify a component to commit a new text sent from IM service provider(s). It has no event value.

IIIMCF_EVENT_TYPE_AUX_START

  This type of event is used to notify a auxiliary object to show the its own presentation. It has a auxiliary name and a window class index, which are obtained by `iiimcf_get_aux_event_value`.

IIIMCF_EVENT_TYPE_AUX_DRAW

  This type of event is used to notify a auxiliary object to show the its own presentation. It has a auxiliary name, a window class index, an integer list, and a string list, which are obtained by `iiimcf_get_aux_event_value`.

IIIMCF_EVENT_TYPE_AUX_SETVALUES

  This type of event is used to send private data of an auxiliary object to IM service provider(s) with `iiimcf_forward_event`. It has a auxiliary name, a window class index, an integer list, and a string list, which are obtained by `iiimcf_get_aux_event_value`, and this type of event can be constructed with `iiimcf_create_aux_setvalues_event`.

IIIMCF_EVENT_TYPE_AUX_DONE

  This type of event is used to notify a auxiliary object to hide or turn off the its own presentation. It has a auxiliary name and a window class index, which are obtained by `iiimcf_get_aux_event_value`.