IM Server Developers Kit - C Language Interface			    Hidetoshi Tajima		    X11R6 Xi18n Implementation Group			      May 15, 19941.   Functions List1.1.   Open IM ServiveXIMS IMOpenIM(Display display,...)display		specifies the connection to the X server....		specifies the variable length argument list to set		IMValues. For further information, see the Section 2		"IMValues".   IMOpenIM initializes the connection for the Input Method Service, andalso sets one or more IMValues which are specified by a variable lengthargument list programming interface, and when succeeding to open theconnection, IMOpenIM allocates a new XIMS structure and returns it,otherwise IMOpenIM returns NULL. XIMS is an opaque data structure toabstract the Input Method Service.   First, IMOpenIM initializes a preconnection method by which clientscan search for the IMserver. The convention of the preconnection varieswith the IMProtocol model as below, however, you don't have to pay muchattention to such difference, because IMOpenIM encapsulates it.    Preconnection for R5 Ximp	IMserver must create the selection owner window of the ATOM for	the string, such as "_XIMP_%locale" or something, which are used	by clients to search for the IMserver.    Preconnection for R6 IMProtocol	IMserver must create the selection owner window of the ATOM for	the string, such as "@server=%im_name", and registers the ATOM	with the list of "XIM_SERVERS" property of the default root	window, which contains a list of ATOMs, each of which represents	each available IMservers on the display.   Second, IMOpenIM initialize a transport connection on which clientsand the IMserver can send and receive IMProtocols with each other. Theprocedures to initialize the transport connection varies with thetransport mechanism as below, however, you don't have to pay anyattention to such difference, either, because IMOpenIM also encapsulatesit.    Transport connection for X	IMserver must intern a number of ATOMs for the properties which	are used to set some IMserver specific feature and	characteristic.    Transport connection for TCP/IP	IMserver must open a listening socket to wait for connection	request from clients.1.2.   Set IM Attributeschar *IMSetIMValues(XIMS ims,...)ims		specifies the input method service....		specifies the variable length argument list to set		IMValues.   IMSetIMValues registers one or more IMValues, which are specified bya variable length argument list programming interface, with the XIMSstructure. Note that IMOpenIM is also used to set all IMValues, and someIMValues must be set when IMOpenIM is called.   IMSetIMValues returns NULL if it succeeds to set all the IMValues,otherwise, it returns the name of the first argument whose value couldnot be registered.1.3.   Get IM Attributeschar *IMGetIMValues(XIMS ims,...)ims		specifies the input method service....		specifies the variable length argument list to get		IMValues.   IMGetIMValues gets one or more IMValues, which are specified by avariable length argument list programming interface, from the XIMSstructure.   IMGetIMValues returns NULL if it succeeds to get all the IMValues,otherwise, it returns the name of the first argument whose value couldnot be obtained.1.4.   Close IM Servicevoid IMCloseIM(XIMS ims)ims		specifies the input method service to be closed.   IMCloseIM closes the connection which was opened by IMOpenIM.IMCloseIM frees all the allocated data in the XIMS structure, then freesthe XIMS itself.1.5.   Start Preeditingint IMPreeditStart(XIMS ims, XPointer im_protocol)ims		specifies the input method service.im_protocol	specifies the Input Protocol data.   IMPreeditStart is used to start preeditting in case of Dynamic EventFlow.The structure for im_protocol varies with the IMProtocol models:/* R5 Ximp */typedef struct {    INT32	type;    CARD32	icid;    Window	focus_win;    long	fwin_sel_mask;    CARD32	ximp_type_mask;    Window	client_win;} XIMPPreeditStateStruct;/* R6 IMProtocol */typedef struct {    int		major_code;    int		minor_code;    CARD16	connect_id;    CARD16	icid;} IMPreeditStateStruct;1.6.   Stop Preeditingint IMPreeditEnd(XIMS ims, XPointer im_protocol)ims		specifies the input method service.im_protocol	specifies the Input Protocol data.   IMPreeditEnd is used to stop preeditting in case of Dynamic EventFlow. However, if you registered off-keys list using IMOffKeysListIMValue, you might not need to use IMPreeditEnd, because IMdkit callsIMPreeditEnd internally when it receives a key event matching one ofthe registered off-keys. So, you are greatly encouraged to useIMPreeditEnd only when you did *NOT* register any off-keys list.1.7.   Forward back KeyEventvoid IMForwardEvent(XIMS ims, XPointer im_protocol)ims		specifies the input method service.im_protocol	specifies the Input Protocol data.   IMForwardEvent is used to send back a non-filteredKeyPress/KeyRelease Event.   The structure for im_protocol varies with the IMProtocol models:/* R5 Ximp */typedef struct {    INT32	type;    CARD32	icid;    Window	focus_win;    long	fwin_sel_mask;    CARD32	ximp_type_mask;    Window	client_win;    CARD32	keycode;    CARD32	state;    CARD32	time;} XIMPKeyEventStruct;/* R6 IMProtocol */typedef struct {    int		major_code;    int		minor_code;    CARD16	connect_id;    CARD16	icid;		/* input context ID */    BITMASK16	sync_bit;	/* precessed synchronously or not */    CARD16	serial_number;    XEvent	event;		/* X event to be filtered */} IMForwardEventStruct;1.8.   Commit Conversion Stringvoid IMCommitString(XIMS ims, XPointer im_protocol)ims		specifies the input method service.im_protocol	specifies the Input Protocol data.   IMCommitString is used to send a committed string, which may containa localized text converted by the IMserver.   The structure for im_protocol varies with the IMProtocol models:/* R5 Ximp */typedef struct {    INT32	type;    CARD32	icid;    Window	focus_win;    long	fwin_sel_mask;    CARD32	ximp_type_mask;    Window	client_win;    char	*ctext;} XIMPCommitStringStruct;/* R6 IMProtocol */typedef struct {    int		major_code;    int		minor_code;    CARD16	connect_id;    CARD16	icid;		/* input context ID */    CARD16	flag;	/* bit combination to tell the receiver what to do */		#0001	: process it synchroously, return XIM_SYNC_REPLY		#0002	: Lookup Chars		#0004	: Lookup KeySym		#0006	: Lookup Both = Lookup Chars and KeySym	 */    KeySym	keysym;		/* returned keysym */    char	*commit_string;	/* string to commit to XIM client */} IMCommitStruct;1.9.   Call Callbackint IMCallCallback(XIMS ims, XPointer im_protocol)ims		specifies the input method service.im_protocol	specifies the Input Protocol data.   IMCallCallback is used for your IMserver to send a callback requestasynchronously with the previous IMProtocol request. The type of thecallback request must be set in the proper members of the im_protocoldata structure by your IMserver. In addition, it's up to you to declarea new IMProtocol structure before you begin the callback requests.   The structures for im_protocol varies with the IMProtocol models:/* R6 IMProtocol */   The type of the callback request must be set in major_code andminor_code members in the IMProtocol structure, e.g., you can startgeometry management callback as follows;	IMGeometryCBStruct geometry;	...	geometry.major_code = XIM_GEOMETRY;	geometry.connect_id = previous_request->any.connect_id;	...	IMCallCallback(ims, (IMProtocol)&geometry);   The structures for R6 IMProtocol callbacks contain:/* for Geometry Callback */typedef struct {    int		major_code;    int		minor_code;    CARD16	connect_id;    CARD16	icid;} IMGeometryCBStruct;/* for Preedit Callback */typedef struct {    int		major_code;    int		minor_code;    CARD16	connect_id;    CARD16	icid;    union {	int	return_value;			/* PreeditStart */	XIMPreeditDrawCallbackStruct draw;	/* PreeditDraw */	XIMPreeditCaretCallbackStruct caret; 	/* PreeditCaret */    } todo;} IMPreeditCBStruct;/* for Status Callback */typedef struct {    int		major_code;    int		minor_code;    CARD16	connect_id;    CARD16	icid;    union {	XIMStatusDrawCallbackStruct draw;    } todo;} IMStatusCBStruct;   The structures for R5 Ximp callbacks contain:/* for Geometry Callback */typedef struct {    INT32	type;    CARD32	icid;    Window	focus_win;    long	fwin_sel_mask;    CARD32	ximp_type_mask;    Window	client_win;} XIMPAnyStruct;/* for Preedit Callback */typedef struct {    INT32	type;    CARD32	icid;    Window	focus_win;    long	fwin_sel_mask;    CARD32	ximp_type_mask;    Window	client_win;    union {	int	return_value;			/* PreeditStart */	XIMPreeditDrawCallbackStruct draw;	/* PreeditDraw */	XIMPreeditCaretCallbackStruct caret; 	/* PreeditCaret */    } todo;} XIMPPreeditCBStruct;/* for Status Callback */typedef struct {    INT32	type;    CARD32	icid;    Window	focus_win;    long	fwin_sel_mask;    CARD32	ximp_type_mask;    Window	client_win;    union {	XIMStatusDrawCallbackStruct draw;	/* StatusDraw */    } todo;} XIMPStatusCBStruct;2.   IMValues2.1.   IMModifiers   The IMModifiers argument, of type string, specifies the name of theIMProtocol model. At the current release, only three names are acceptedby IMdkit.	"Xi18n"		specifies the R6 standard IMProtocol model	"XIMP"		specifies the R5 Ximp model.   The IMModifiers argument must be set only once when IMOpenIM iscalled, and never be changed on the fly.2.2.   IMServerWindow   The IMServerWindow argument, of type Window, specifies the windowwhich identifies a method of preconnection with XIM clients. In additionto this primary purpose, the IMServerWindow might be used for any otherpurposes, which depends on the IMProtocol model to be used.   If this argument is unspecified, a default window might be providedby IMdkit, which depends on the IMProtocol model to be used, and if itis specified, it must be done only once by either IMOpenIM orIMSetIMValues, and never be changed on the fly.2.3.   IMServerName   The IMServerName argument, of type string, specifies the name of theIMserver. This argument might be a part of the IMserver identifiersby which XIM clients will search for the IMserver.   The IMServerName argument must be set only once when IMOpenIM iscalled, and never be changed on the fly.2.4.   IMLocale   The IMLocale argument, of type string, specifies a list of localesthe IMserver supports. This argument might be a part of the IMserveridentifiers which is used for XIM clients to search for the IMserver.   The IMLocale argument must be set only once when IMOpenIM is called,and never be changed on the fly.2.5.   IMServerTransport   The IMServerTransport argument, of type string, specifies the namefor the transport connection mechanism the IMserver uses. This argumentmight be a part of the IMserver identifiers which is used for XIMclients to search for the IMserver.   The preregistered formats for this argument are as follows.(*1)(*1) Reter to "The Input Method Protocol", Appendix B:  The list of transport specific IM Server address format registeredTCP/IP Names------------   Syntax for Internet domain names:	<TCP name> ::= "tcp/"<hostname>":"<ipportnumber>   	where <hostname> is either symbolic or numeric decimal form of	the host machine name, and <ipportnumber> is the port on which	the IMserver is listening for connections.   Syntax for system internal domain names:	<local name> ::= "locale/"<hostname>":"<pathname>	where <pathname> is a path name of socket address.DECnet Names------------   Syntax for DECnet names:	<DECnet name> ::= "decnet/"<nodename>"::IMSERVER$"<objname>	where <nodename> is either symbolic or numeric decimal form of	the DECnet address, and <objname> is normal, case-insensitive	DECnet object name.X Names-------   Syntax for X names:	<X name> ::= "X/"   The IMServerTransport argument must be set only once when IMOpenIM iscalled, and never be changed on the fly.2.6.   IMInputStyles   The IMInputStyles argument, of type XIMStyles, specifies a list ofthe input styles the IMserver supports.   If this argument is unspecified, a default list might be provided byIMdkit, which depends on the IMProtocol model to be used, and it can beset by either IMOpenIM or IMSetIMValues, but should not be changed onthe fly.2.7.   IMProtocolHandler   The IMProtocolHandler argument, of type IMProtoHandler, specifies thecallback function which is called each time when IMMainLoop receives anIMProtocol input from XIM clients. The generic prototype of theIMProtocolHandler function is;typedef int (*IMProtoHandler)();int ProtocolHandlerProc(ims, call_data)XIMS ims;XPointer call_data;call_data	points to a IMProtocol structure.2.8.   IMOnKeysList   The IMOnKeysList argument, of type XIMTriggerKeys, specifies the listof preediting start-keys for Dynamic Event Flow model. The IMOnKeysListIMValue is mandatary for IMserver to support Dynamic Event Flow Model,so that the IMlibrary can send the IMserver a request to startpreediting with the apperance of one of these registered on-keys.   If the IMOnKeysList is left unspecified, no default will be provided,and Static Event Flow model will be used.   XIMTriggerKeys structure is defined by IMdkit as follows:typedef struct {    CARD32	keysym;    CARD32	modifier;    CARD32	modifier_mask;} XIMTriggerKey;typedef struct {    unsigned short count_keys;    XIMTriggerKey *keylist;} XIMTriggerKeys;2.9.   IMOffKeysList   The IMOnKeysList argument, of type XIMTriggerKeys, specifies the listof preediing end-keys for Dynamic Event Flow model. The IMOffKeysListIMValue is optional for IMserver to support Dynamic Event Flow Model.   When it is specified, the IMlibrary can send the IMserver a requestto stop preediting with the apperance of one of these registeredoff-keys, while it's unspecified, the IMserver calls IMPreeditEnd tonotify the IMlibrary to stop preeditting when the IMserver would like tostop preeditring.   If the IMOffKeysList is left unspecified, no default will beprovided.2.10.   IMEncodingList   The IMEncodingList argument, of type XIMEncodings, specifies the list