Htt Server: X Auxiliary Object Specifications for IIIM

Introduction

Solaris Input Method Server (Htt) for X Window System environment provides default GUI objects, such as preedit, status, and lookup selection window. Although these default GUI objects provide adequate functionalities for basic operations, input method engines requires much richer functionalities than the default GUI objects provide.

The mechanism of X auxiliary object enables Input Method engine vendors to define their own GUI objects which will work well with their Input Method engines.

This document describes the interface between Solaris Input Method Server provided by Solaris, and X Auxiliary Object which will be provided by Input Method engine vendors.

Overview

X Auxiliary Object is implemented as an shared library, which will be loaded by xiiimp.so. The loading is initiated by the request from xiiimp.so. After loading the shared library, xiiimp.so will forwards requests from Input Method engine to the shared library.

IIIM server can specify path names of X auxiliary shared library objects, or path names of configuration files.

Path names may not start with ``/'', nor contain ''/../''. Path names are interpreted relative to ``/usr/lib/im/''.

One X auxiliary shared library can contain one or more X auxiliary objects. See X Auxiliary Object Directory for more detail.

One X auxiliary object configuration file can contain one or more names of X auxiliary shared library objects. See X Auxiliary Object Configuration File for more detail of.

Interface

aux_t structure

aux_t structure is defined in iiimpAux.h. X auxiliary object can access the member ``service'', but may not access other members.

X Auxiliary Object Directory

X Auxiliary Object must define an auxiliary object directory, which consists of array of aux_dir_t structure. Each element defines an X auxiliary object. The array will be terminated with null element.

typedef struct {
        aux_name_t      name;
        aux_method_t *  method;
} aux_dir_t;

X auxiliary object must export a symbol ``aux_dir'' which points to the array of aux_aux_t structures.

Auxiliary Name

X Auxiliary Object must define the name of auxiliary object, as UTF-16 strings. The length is specified as a byte length.

typedef struct {
        int             len;
        CARD16 *        ptr;
} aux_name_t;

Auxiliary Methods

X Auxiliary Object must define the following methods.

typedef struct {
        Bool    (* create)(aux_t *);
        Bool    (* start)(aux_t *, const unsigned char *, int);
        Bool    (* draw)(aux_t *, const unsigned char *, int);
        Bool    (* done)(aux_t *, const unsigned char *, int);
        Bool    (* switched)(aux_t *, int, int);
        Bool    (* destroy)(aux_t *);
} aux_method_t;

Service Methods

xiiimp.so provides the following service methods, which can be accessed thru the member ``service'' of aux_t structure.

struct {
        void            (* aux_setvalue)(aux_t *, const unsigned char *, int);
        int             (* im_id)(aux_t *);
        int             (* ic_id)(aux_t *);
        Display *       (* display)(aux_t *);
        Window          (* window)(aux_t *);
        XPoint *        (* point)(aux_t *, XPoint *);
        XPoint *        (* point_caret)(aux_t *, XPoint *);
        size_t          (* utf16_mb)(const char **, size_t *,
                                     char **, size_t *);
        size_t          (* mb_utf16)(const char **, size_t *,
                                     char **, size_t *);
        unsigned char * (* compose)(const aux_data_t *, int *);
        int             (* compose_size)(aux_data_type_t,
                                         const unsigned char *);
        aux_data_t *    (* decompose)(aux_data_type_t, const unsigned char *);
        void            (* decompose_free)(aux_data_t *);
        void            (* register_X_filter)(Display *, Window, int, int, 
                                              Bool (*)(Display *, Window,
                                                       XEvent *, XPointer),
                                              XPointer);
        void            (* unregister_X_filter)(Display *, Window,
                                                Bool (*)(Display *, Window,
                                                         XEvent *, XPointer),
                                                XPointer);
        Bool            (* server)(aux_t *);
        Window          (* client_window)(aux_t *);
        Window          (* focus_window)(aux_t *);
        int             (* screen_number)(aux_t *);
        int             (* point_screen)(aux_t *, XPoint *);
        int             (* point_caret_screen)(aux_t *, XPoint *);
} aux_service_t;

aux_data_t structure

aux_data_t structure is defined in iiimpAux.h. X auxiliary object may not access a member string_ptr. It is intended to be used by decompose() and decompose_free() service methods.

typedef struct {
        aux_data_type_t type;
        int             im;
        int             ic;
        int             aux_index;
        int             aux_name_length;
        unsigned char * aux_name;
        int             integer_count;
        int *           integer_list;
        int             string_count;
        aux_string_t *  string_list;
        unsigned char * string_ptr;
} aux_data_t;

aux_data_type_t enumeration

aux_data_type_t is used for compose() and compose_size() service methods.

typedef enum {
        AUX_DATA_NONE = 0,
        AUX_DATA_START = 1,
        AUX_DATA_DRAW = 2,
        AUX_DATA_DONE = 3,
        AUX_DATA_SETVALUE = 4
} aux_data_type_t;

X Auxiliary Object Configuration File

X auxiliary object configuration files can be defined to specify the names of X auxiliary shared library objects.

The configuration file is an ASCII file. The first line should be:

# IIIM X auxiliary

Lines beginning with ``#'' are treated as comments, and will be ignored. Empty lines are also ignored.

Each line consists of two fields. The first field is the name of X auxiliary object. The second filed is the path name to the X auxiliary shared library object.

The path name can be specified as an absolute path name or an relative path name. If the path name begins with ``/'', it will be interpreted as an absolute path name. Otherwise, the path name will be interpreted relative to the directory in which the configuration file resides.

Auxiliary Methods

Creating and destroying X Auxiliary Object

When the IM engine issues IM_AUX_START request for the first time for the X auxiliary object, create() method will be invoked before the invocation of start().

When the X auxiliary object is destroyed, destroy() method will be invoked. The method should deallocate any resources allocated in create method and other invocation of X Auxiliary Object methods.

Bool    (* create)(aux_t * aux)
Bool    (* destroy)(aux_t * aux)

Starting and stopping X Auxiliary Object

When the IM engine issues IM_AUX_START request, start() method will be invoked.

When the IM engine issues IM_AUX_DONE request, done() method will be invoked.

Bool    (* start)(aux_t * aux, const unsigned char * p, int len)
Bool    (* done)(aux_t * aux, const unsigned char * p, int len)
p
A pointer to the copy of IIIMP IM_AUX_START or IM_AUX_DONE request, excluding protocol header. It can be decomposed to aux_data_t object using decompose() service method.
len
length of IM_AUX_START or IM_AUX_DONE request

Drawing X Auxiliary Object

When the IM engine issues IM_AUX_DRAW request, draw() method will be invoked.

Bool    (* draw)(aux_t * aux, const unsigned char * p, int len)
p
A pointer to the copy of IIIMP IM_AUX_DRAW request, excluding protocol header. It can be decomposed to aux_data_t object using decompose() service method.
len
length of IM_AUX_DRAW request

Switching X Auxiliary Object

When the IM is switched on or off by Htt IM server, switched() method will be invoked.

Bool    (* switched)(aux_t * aux, int im_id, int on_off)
im_id
IM identifier
on_off
When the IM associated to the X Auxiliary Object is selected, 1 is set to on_off. When the IM associated to the X Auxiliary Object is unselected, 0 is set to on_off. request

Service Methods

Send data to IIIM Server

Send IM_AUX_SETVALUES request to IIIM server.

void    (* aux_setvalue)(aux_t * aux, const unsigned char * p, int len)
p
IM_AUX_SETVALUES request data
len
Length of IM_AUX_SETVALUES request data

Get IM identifier

Get IM identifier.

int     (* im_id)(aux_t * aux)

Get IC identifier

Get IC identifier.

int     (* ic_id)(aux_t * aux)

Save IC specific auxiliary private data

Save IC specific auxiliary private data

void    (* data_set)(aux_t * aux, int im_id, void * data)
im_id
IM identifier
data
Pointer to the private data.

Get IC specific auxiliary private data

Get IC specific auxiliary private data.

void *  (* data_get)(aux_t * aux, int im_id)

Get X display descriptor

Get X display descriptor.

Display *       (* display)(aux_t * aux)

Get window identifier

Get window identifier of focus window, client window, or None.

Window          (* window)(aux_t * aux)

Get cursor point

Get cursor point, or spot location, relative to the window obtained by window().

XPoint *        (* point)(aux_t * aux, XPoint * point)
point
Cursor point

Get caret point

Get caret point, or spot location, relative to the window obtained by window(), with caret adjustment.

XPoint *        (* point_caret)(aux_t * aux, XPoint * point)
point
Caret point

Convert character encoding from UTF-16 to MultiByte

Convert character encoding from UTF-16 to MultiByte.

size_t  (* utf16_mb)(const char ** inbuf, size_t * inbytesleft,
                     char ** outbuf, size_t * outbytesleft)
inbuf
Pointer to UTF-16 string.
inbytesleft
Byte length of UTF-16 string
outbuf
Pointer to the area where MultiByte string will be saved.
outbytesleft
Byte size of the area pointed by outbuf. This value will be updated

Convert character encoding from MultiByte to UTF-16

Convert character encoding from MultiByte to UTF-16.

size_t  (* mb_utf16)(const char ** inbuf, size_t * inbytesleft,
                     char ** outbuf, size_t * outbytesleft)
inbuf
Pointer to MultiByte string.
inbytesleft
Byte length of MultiByte string
outbuf
Pointer to the area where UTF-16 string will be saved.
outbytesleft
Byte size of the area pointed by outbuf. This value will be updated.

Compose IIIMP request data

Compose IIIMP request data.

This method does not perform encoding conversion on the member ``string_list''. Normally, each string of string_list should be encoded with UTF-16 encoding. Locale related MultiByte strings can be converted to UTF-16 strings using mb_utf16() service method.

X auxiliary object must fill all member of aux_data object excluding ``string_ptr''.

unsigned char * (* compose)(const aux_data_t * aux_data, int * size)
aux_data
aux_data_t object from which IIIMP request is composed.
size
Pointer to which the size of the IIIMP request will be saved.

Get the size of composed IIIMP request

Get the size of composed IIIMP request.

int     (* compose_size)(aux_data_type_t data_type, const unsigned char * p)
data_type
Type of IIIMP request.
p
Pointer to IIIMP request data.

Decompose IIIMP request

Decompose IIIMP request to aux_data_t object. This method does not perform encoding conversion on the member ``string_list''. Normally, each string of string_list is encoded with UTF-16 encoding. UTF-16 strings can be converted to locale related MultiByte strings using utf16_mb() service method.

aux_data_t *    (* decompose)(aux_data_type_t data_type, const unsigned char * p)
data_type
Type of IIIMP request.
p
Pointer to IIIMP request data.

Free aux_data_t object

Free aux_data_t object which is returned by compose() service method.

void    (* decompose_free)(aux_data_t * aux_data)
aux_data
aux_data_t object.

Register X event filter

Register X event filter.

void    (* register_X_filter)(Display * display, Window window, 
                              int start_type, int end_type,
                              Bool (* filter)(Display *,
                                              Window,
                                              XEvent *,
                                              XPointer),
                              XPointer client_data);
display
X display descriptor.
window
X window identifier.
start_type
X event.
end_type
X event.
filter
X event filter, which will process the event.
client_data
The data will be passed to filter.

Unregister X event filter

Unregister X event filter.

void    (* unregister_X_filter)(Display * display, Window window, 
                                Bool (* filter)(Display *, Window,
                                                XEvent *, XPointer),
                                XPointer client_data);
display
X display descriptor.
window
X window identifier.
filter
X event filter, which will process the event.
client_data
The data will be passed to filter.

Server or Client

Returns True if the current process is Htt X back end server. Otherwise returns False;

Bool    (* server)(aux_t * aux);

Get client window identifier

Get window identifier of client window or None.

Window          (* client_window)(aux_t * aux)

Get focus window identifier

Get window identifier of focus window or None.

Window          (* focus_window)(aux_t * aux)

Get screen number of client window

Returns screen number of focus window, client window, or -1.

int             (* screen_number)(aux_t * aux)

Get cursor point in screen

Get cursor point, or spot location, relative to the root window.

Returns screen number of focus window, client window, or -1.

int             (* point_screen)(aux_t * aux, XPoint * point)
point
Cursor point

Get caret point in screen

Get caret point, or spot location, relative to the root window, with caret adjustment.

Returns screen number of focus window, client window, or -1.

int             (* point_caret_screen)(aux_t * aux, XPoint * point)
point
Caret point

Requirement

xiiimp.so is loaded by Htt X back end server, or X applications. Thus the followings are required.

Suggestion

If the X Auxiliary Object is to be implemented using Motif or other toolkits, it should be implemented as an external stand alone process. Communication between X Auxiliary Object and the external process can be achieved via X client message or property. Sample source files are available at the following directory.

Appendix

IIIMP request

IM_AUX_START
A IIIMP request to notify an auxiliary object a start event. When if_module issues iml_make_aux_start_inst() then iml_execute(), IIIM server sends the request to the client.
IM_AUX_DRAW
A IIIMP request to notify an auxiliary object a draw event. When if_module issues iml_make_aux_draw_inst() then iml_execute(), IIIM server sends the request to the client.
IM_AUX_DONE
A IIIMP request to notify an auxiliary object a done event. When if_module issues iml_make_aux_done_inst() then iml_execute(), IIIM server sends the request to the client.
IM_AUX_SETVALUES
A IIIMP request to send private data from auxiliary object to if_module which is attached to IIIM server. When IIIM server receives this request, if_SendEvent() method of if_module will be invoked.

Naming Convention

X auxiliary object directory
X auxiliary object files should be placed in /usr/lib/im/language/language/IM/.
X auxiliary object shared library
X auxiliary object shared library files should be postfixed with ``.so''.
X auxiliary object configuration file
X auxiliary object configuration file should be postfixed with ``.conf''.