-
Notifications
You must be signed in to change notification settings - Fork 0
HelperProtocol
= HELPER-PROTOCOL =
To communicate between uim-related processes such as GUI applications and toolbar applets, uim uses the helper system. This file describes the helper protocol within uim.
The message based helper protocol participants form a peer-to-peer star topology network connected via central uim-helper-server using UNIX domain socket.
+-----------------+ ----- uim-toolbar-gtk
uim app1 ----- |uim-helper-server| ----- uim app2
uim app3 ----- +-----------------+ ----- uim configuration tool
Although uim-helper-server is named as 'server', it only means 'listen to the connections'. The server is currently implemented as simple message reflector, so the network always behaves as broadcasting.
msg +-----------------+ ----> uim-toolbar-gtk
uim app1 ----> |uim-helper-server| ----> uim app2
uim app3 <---- +-----------------+ ----> uim configuration tool
All participants receives the message from uim app1
Since the broadcasting behavior, the protocol does not have the specification about 'response message'. Any messages are delivered to all participants and implicitly done. The sender cannot know any receiver information such as 'properly received' or 'how many participants are accepted the message'.
Although the message layer does not specifies neither response message nor unicast, higher layer virtually provides it. Some messages behave as 'request' and 'response to the request' in semantic view (of course the 2 messages are not related in message layer). See 'prop_list_get' and 'prop_list_update' as example.
In another situation, the helper system can simulate unicast message by following way.
+-----------------+ ----> uim-toolbar-gtk
uim app1 <---- |uim-helper-server| ----> uim app2
uim app3 ----> +-----------------+ ----> uim configuration tool
focus_in
(1) uim app3 send focus_in message to declare that "I've activated"
prop_activate
+-----------------+ <---- uim-toolbar-gtk
uim app1 <---- |uim-helper-server| ----> uim app2
uim app3 <---- +-----------------+ ----> uim configuration tool
(2) uim-toolbar-gtk send prop_activate
prop_activate
+-----------------+ <---- uim-toolbar-gtk
uim app1 x---- |uim-helper-server| ----x uim app2
uim app3 <---- +-----------------+ ----x uim configuration tool
(3) inactive processes ignore the message
All messages in the protocol are defined as follows.
The protocol data consist of human readable messages on an IPC connection. Each messages are consist of arbitrary lines of text and delimited from another message by "\n\n".
session = messages
messages = messages message | message
message = (focus_in |
focus_out |
prop_activate |
prop_list_get |
prop_list_update |
im_list |
im_list_get |
im_change_this_text_area_only |
im_change_whole_desktop |
im_change_this_application_only |
prop_update_custom |
custom_reload_notify |
commit_string |
im_switcher_start
im_switcher_quit) "\n"
charset_specifier = "charset=" charset "\n"
charset = "UTF-8" | "EUC-JP" | "GB18030" |
<or any name that can be specified as iconv_open(3) argument>
str = str <any characters except for '\0', '\t' or '\n'> | ""
identifier = [_a-zA-Z][_a-zA-Z0-9]*
This message declares that the sender has gotten a focus. This means that the focused context of this process has become 'active context' and any other contexts have become 'inactive context'. It implies that only active context can respond to some messages prop_list_get, prop_label_get, prop_activate, im_list_get and commit_string. Contexts in other processes have to become inactive by receiving focus_in message from another process.
Invoke uim_helper_client_focus_in() to send this message.
focus_in = "focus_in\n"
This message notifies that the sender has been lost a focus. This message is currently not received by official uim suites.
Invoke uim_helper_client_focus_out() to send this message.
focus_out = "focus_out\n"
The concept 'property' in uim means 'properties of input method'. An input method (in accurately, input context) can own arbitrary number of properties. A property is ordinarily appeared for user as a popup menu with an indicator. Such indicator will be appeared simultaneously for user if the input method has 2 or more properties. One property controls one variable state of the input method such as 'input mode' or 'keymap'.
action_id = identifier
This message notifies that a command named as action_id has been activated. This message is usually sent from toolbar applets in response to an user selection and received by corresponding IM. Once received, the prop-handler of current IM has been invoked with action_id. Several IMs use action_id as 'input mode' such as 'hiragana', 'katakana', 'direct' and so on, and switches to activated input mode on receiving.
See also prop_list_update.
prop_activate = "prop_activate\n" action_id "\n"
This message requests a prop_list_update. The request sender will receive prop_list_update in response to this message. This message is typically used for active acquiring of prop_list by toolber applets at start up. If this message has not been sent, the applet has to passively wait for prop_list_update that will be notified by current IM to show correct information.
Invoke uim_helper_client_get_prop_list() to send this message.
See also prop_list_update
prop_list_get = "prop_list_get\n"
This message notifies that a set of menu items typically for toolbar applets. A message is consist of branches which contains arbitrary number of leaves. A branch represents a property which is shown as (popup) menu for user, and a leaf represents a menu item of the branch.
indication_id is an identifier that specifies visual appearance of the item. The ID roughly considerable as "icon name", and so the message receiver can use it to form filename for the corresponding icon (e.g. "anthy" -> "/path/to/somewhere/32x32/anthy.png"). There is a special ID. If the ID is "separator", message receivers should display the leaf as toolkit-native separator. But it is not necessary since the "separator" appears as dummy item with no action if the receiver is not aware of it.
iconic_label is a very short string typically 1 character to be used as icon. For example, "a" means 'direct input'. This field should be translated with gettext(3) or equivalent. See safe_gettext() of toolbar-common-gtk.c.
label_string is a short string to be shown in the menu, or used as tooltip of the button. This field should be translated with gettext(3) or equivalent.
short_desc is a short description string usually used as tooltip of the menu item. This field should be translated with gettext(3) or equivalent.
action_id is an identifier of the menu item. This will be notified to other processes by prop_activate when this menu item has been selected by user.
activity means that whether this menu item is selected. Only one menu item per branch should be notified as "" which means 'selected'.
Invoke im-update-prop-list to send this message.
See also prop_activate.
prop_list_update = "prop_list_update\n" charset_specifier parts
parts = parts part | part
part = branch leaves
branch = "branch\t" indication_id "\t" iconic_label "\t" label_string "\n"
leaves = leaves leaf | leaf
leaf = "leaf\t" indication_id "\t" iconic_label "\t"
label_string "\t" short_desc "\t" action_id "\t" activity "\n"
indication_id = identifier | "separator"
iconic_label = str
label_string = str
short_desc = str
activity = "*" | ""
imname is an identifier name of the input method written in ASCII.
imname = str
This message notifies that the set of currently available input methods.
imlang is an i18n-ized free format human readable string such as "Japanese".
imshort_description is a short description of the input method. This string is currently not i18n-ized (i.e. written in English).
selectedflag specifies which input method of all available one is currently selected. At most one input method has the value "selected".
See also im_list_get
im_list = "im_list\n" charset_specifier iminfos
iminfos = iminfos iminfo | iminfo
iminfo = imname "\t" imlang "\t" imshort_description "\t" selectedflag"\n"
imlang = human_readable_language_name
imshort_description = str
selectedflag = "selected" | ""
human_readable_language_name = str
This message requests a im_list. The request sender will receive im_list from currently focused input context in response to this message. This message is typically used for active acquiring of im_list by im-switcher application (such as uim-im-switcher) at start up.
See also im_list, focus_in
im_list_get = "im_list_get\n"
This message notifies that currently focused input context must be switched its input method to specified imname. All receivers must properly accept or discard this message in accordance with focus management.
See also focus_in
im_change_this_text_area_only = "im_change_this_text_area_only\n" imname "\n"
This message notifies that all input context of the application that has currently focused input context must be switched its input method to specified imname. All receiver processes must properly accept or discard this message in accordance with focus management.
See also focus_in
im_change_this_application_only = "im_change_this_application_only\n" imname "\n"
This message notifies that all input contexts in local machine must be switched its input method to specified imname. All receiver processes must accept this message and switch all input context of the process.
im_change_whole_desktop = "im_change_whole_desktop\n" imname "\n"
Update a custom value of received process. The received message are evaluated as (custom-set! custom_sym custom_value) and immediately affects the running IMs. Both custom_sym and custom_value will be strictly validated to prevent crashing or abuse. Invalid messages will be simply ignored.
custom_sym and custom_value are delimited by "\n" instead of "\t" to allow "\t" to be included in the value.
The command name 'prop_update_custom' is wrongly named by misunderstanding about naming convention of the helper protocol. It should be renamed as 'custom_set'.
prop_update_custom = "prop_update_custom\n" custom_sym "\n" custom_value "\n"
custom_sym = /^[-\?a-zA-Z0-9]+$/
custom_value = <valid S-expression>
This is a notification message to reload configrations. If a process receive this message, the process should reload configrations somehow. This message maybe needless in the future.
custom_reload_notify = "custom_reload_notify\n"
This message commits a string to currently focused context. See also focus_in.
commit_string = "commit_string\n" charset_specifier str_to_commit "\n"
str_to_commit = /^[^\n]+$/
This message notifies that a new uim-im-switcher is started. When an existing old uim-im-switcher receives im_switcher_start, the existing uim-im-switcher must send im_switcher_quit to quit newly started uim-im-switcher.
See also im_switcher_quit.
im_switcher_start = "im_switcher_start\n"
This message requests newly started uim-im-switcher to quit. All uim-im-switcher must quit immediately after received this message.
See also im_switcher_start.
im_switcher_quit = "im_switcher_quit\n"