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 [1] 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;
	  
[2]

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 the Section called connection shutdown.

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.

Notes

[1]

Status text is an indication text for input method users, which is usually used for notifying current status of the input method.

[2]

Note that IIIMP_int32 is 32 bit signed integer type.