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.


* Network topology and message passing

  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.



* Message format in (extended) BNF

  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]*

* Focus notification messages

  - focus_in

    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"

  - focus_out

    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"


* Property messages

    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

  - prop_activate

    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"

  - prop_list_get

    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"

  - prop_list_update

    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 = "*" | ""


* IM management messages

  imname is an identifier name of the input method written in ASCII.

  imname = str

  - im_list

    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

  - im_list_get

    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"

  - im_change_this_text_area_only

    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"

  - im_change_this_application_only

    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"

  - im_change_whole_desktop

    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"


* Other messages

  - prop_update_custom

    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>

  - custom_reload_notify

    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"

  - commit_string

    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]+$/

  - im_switcher_start

    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"

  - im_switcher_quit

    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"

Local Variables:
mode: indented-text
fill-column: 78
End: