Scim Bridge Developer Manual: The communication protocol

Up

Who does need this section?

Basically, you don't have to know about the communication protocol between the agent and the clients because the client library interprets it for you. So, this section is mainly written for...

- core developers of scim-bridge.
- he or she who wants to write clients without using C language.
- he or she who wants to write an alternative agent.

Let's know about the fumdamental rules

- Every message is described in UTF8, and it ends with '\n'.
- Every message must begin with the header. It can also has some following arguments.
- All the items (the header and the arguments) in a message are seperated by spaces (' ').
  Note, the seperator of two spaces indicate that there are a *NULL* argument between them.
- Space characters (' ') or line feed characters ('\n') included in headers and arguments must be espaced by '\', like "\s" and "\n".
  Note, '\' itself must be espaced by itself.
- Some commands expect response from the other. It will block until the responsive message arrives, so you have to send it as soon as possible.

Now, you can communicate with the agent by open the unix domain socket in O_RDWR mode.

The command list

The following list describes all the commands go through the socket.

From the agent to clients:

- preedit_mode_changed
  - The way to show the preedit has been changed.
  - This message is the response of set_preedit_mode.
- imcontext_registered id
  - An IMContext has been registered.
  - This message is the response of register_imcontext.
  - id stands for the ID for the new IMContext.
- imcontext_deregistered
  - An IMContext has been deregistered.
  - This message is the response of deregister_imcontext.
- imcontext_reseted
  - An IMContext has been reseted.
  - This message is the response of reset_imcontext.
- focus_changed
  - The focus has been changed.
  - This message is the response of set_focus.
- cursor_location_changed
  - The cursor position in the display has been changed.
  - This message is the response of set_cursor_location.
- update_preedit id
  - Update the embedded preedit.
  - You should expect preedit_updated as the response.
  - id stands for the ID of IMContext.
- set_preedit_shown id shown
  - Update visibility of the preedit.
  - id stands for the ID of IMContext.
  - shown stands for new visiblity. Give it "true" or "false".
  - Note that clients shouldn't change the preedit until update_preedit is called.
  - This command can be ignored if invalid IMContext is requested.
- set_preedit_string id string
  - Update the preedit string.
  - id stands for the ID of IMContext.
  - string stands for new preedit string.
  - Note that clients shouldn't change the preedit until update_preedit is called.
  - This command can be ignored if invalid IMContext is requested, or the preedit is not shown.
- set_preedit_attributes id begin1 end1 type1 value1 begin2 ...
  - Update the attributes of the preedit string.
  - id stands for the ID of IMContext.
  - begin* stands for begining index (in wcs) of the attribute.
  - end* stands for ending index (in wcs) of the attribute.
  - type* stands for the type of the attribute.
  - value* stands for the value of the attribute.
  - Please read here if you want to know what attributes are supported.
  - Note that clients shouldn't change the preedit until update_preedit is called.
  - This command can be ignored if invalid IMContext is requested, or the preedit is not shown.
- commit_string id string
  - Commit a string into the focused widget.
  - You should expect string_committed as the response.
  - id stands for the ID of IMContext.
  - string stands for the string to commit.
- get_surrounding_string id before_max after_max
  - Get the surrounding string of the caret.
  - You should expect surrounding_string_gotten as the response.
  - id stands for the ID of IMContext.
  - before_max is the maximum expected wide characters before the caret.
  - after_max is the maximum expected wide characters after the caret.
- delete_surrounding_string id offset length
  - Delete a part of the surrounding string of the caret.
  - You have to get it by get_surrounding_string before using this.
  - You should expect surrounding_string_deleted as the response.
  - id stands for the ID of IMContext.
  - offset is the starting offset of the text to remove from the caret.
  - length is the length of the text to remove.
- replace_surrounding_string id corsor_index string
  - Replace the surrounding string of the caret.
  - You have to get it by get_surrounding_string before using this.
  - You should expect surrounding_string_replaced as the response.
  - id stands for the ID of IMContext.
  - cursor_index is the new caret position in the new surrounding string.
  - string is the text to be set as the new surrounding string.
- beep id
  - Make a beep sound.
  - You should expect beeped as the response.
  - id stands for the ID of IMContext.
- key_event_handled consumed
  - The key event has been handled.
  - consumed stands for if the event has been consumed. You'll get "true" if the event has been consumed. Otherwise, you'll get "false".
  - Note, the events which has not been consumed must be passed to GUI library as the fallback key events.

From the clients to agent:

- set_preedit_mode id mode
  - Set the way to show the preedit.
  - You should expect preedit_mode_changed as the response.
  - id stands for the ID for the new IMContext. You can give it "-1" to change the default value for the client.
  - mode stands for how to show the preedit. See also here.
  - Note, the default mode is "any".
- set_cursor_location x y
  - Change the cursor location in the screen.
  - Note, the location must be an abolute location in the screen.
  - You must send this message unless you use "embedded" or "floating" for all the preedits, the lookup tables.
- register_imcontext
  - Register a new imcontext to the agent.
  - You should expect imcontext_registered as the response.
- deregister_imcontext id
  - Request to deregister of an imcontext.
  - id stands for the ID of IMContext.
  - You should expect imcontext_reseted as the response.
- reset_imcontext id
  - Request to reset of an imcontext.
  - id stands for the ID of IMContext.
  - You should expect imcontext_reseted as the response.
- string_commited
  - A string is commited into the focused widget.
  - This messages is the response of commit_string.
- preedit_updated
  - The embedded preedit has been updated.
  - This message is the response of update_preedit.
- set_focus id focus_in
  - Request to focus or unfocus an IMContext.
  - You should expect focus_changed as the response.
  - id stands for the ID of IMContext.
  - focus_in stands for which request this is. Give it "true" if you want to focus this. Otherwise, give it "false".
- handle_key_event id key_code key_pressed modifier1 modifier2 ...
  - Handle a key event.
  - You should expect key_event_handled as the response.
  - id stands for the ID of IMContext.
  - key_code stands for the code of the key. (I'll give you a list of them later...)
  - key_pressed stands for whether the key is pressed or not. Give it "true" if the key is pressed. Otherwise, give it "false".
  - modifier* stands for the modifier accompanied with the event key. (I'll give you a list of them later...)
- forward_key_event id key_code key_pressed modifier1 modifier2 ...
  - A key event has been forwarded from the agent.
  - key_code stands for the code of the key. (I'll give you a list of them later...)
  - key_pressed stands for whether the key is pressed or not. You'll get "true" if the key is pressed. Otherwise, you'll get "false".
  - modifier* stands for the modifier accompanied with the event key. (I'll give you a list of them later...)
- surrounding_string_gotten retval string cursor_position
  - The surrounding string has been gotten.
  - This is the response of get_surrounding_string.
  - retval returns "TRUE" if it succeeded, otherwise it returns "FALSE".
  - cursor_position is the caret position in the surrounding string. None is given if (retval) is FALSE.
  - string is the surrounding string. None is given if retval is "FALSE".
- surrounding_string_deleted retval
  - The surrounding string of the caret has been deleted.
  - This is the response of delete_surrounding_string.
  - retval returns "TRUE" if it succeeded, otherwise it returns "FALSE".
- surrounding_string_replaced retval
  - The surrounding string of the caret has been replaced.
  - This is the response of replace_surrounding_string.
  - retval returns "TRUE" if it succeeded, otherwise it returns "FALSE".

Appendix: Supported attributes

Type | Description | Supported values
--- | --- | ---
foreground | Change the text color of the preedit. | Colors in the format of "#RRGGBB".
background | Change the background color of the preedit. | Colors in the format of "#RRGGBB".
decoratation | Change the background color of the preedit. | "reverse" to exchange the foreground color and background one. "hilight" to hilight the preedit. "underline" to add a line under the preedit.
none | Invalid attribute. | "none" is recommanded.

Appendix: Modes for the the preedit.

Type | Description
--- | ---
embedded | The clients show the one by itself. The agent must not show the one.
hanging | The agent show the one just under the caret if the caret position is available. Otherwise, this is the same as "floating".
floating | The agent show the one in any position.
any | The agent uses it following to its preference.

Copyright (c) 2006 Ryo Dairiki <ryo-dairiki@users.sourceforge.net>