/*
Copyright 1990-2001 Sun Microsystems, Inc. All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions: The above copyright notice and this
permission notice shall be included in all copies or substantial
portions of the Software.


THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE OPEN GROUP OR SUN MICROSYSTEMS, INC. BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE EVEN IF
ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH DAMAGES.


Except as contained in this notice, the names of The Open Group and/or
Sun Microsystems, Inc. shall not be used in advertising or otherwise to
promote the sale, use or other dealings in this Software without prior
written authorization from The Open Group and/or Sun Microsystems,
Inc., as applicable.


X Window System is a trademark of The Open Group

OSF/1, OSF/Motif and Motif are registered trademarks, and OSF, the OSF
logo, LBX, X Window System, and Xinerama are trademarks of the Open
Group. All other trademarks and registered trademarks mentioned herein
are the property of their respective owners. No right, title or
interest in or to any trademark, service mark, logo or trade name of
Sun Microsystems, Inc. or its licensors is granted.

*/

Please refer 

        doc/SPI/Language_Engine_Interface.html

for detail of Language Engine Interface

Overview
========
   Here is the overview how SunIM and Htt core work for IM client.
   SunIM library is used by Htt core to handle language engine modules.

IM Client	Htt Core		SunIM
---------	--------		-----
		Startup			LELookup::getListOfLEs()
					   gathering LE on the system and
					   returns the list of InterfaceModule

Startup	   ->	Open IF			LEInterface::getLEInterface()
					   dlopen LE module
					   Call If_OpenIF() of the LE
					      Start XSunIM Adapter if necessary
					      Start SunIM Adapter if necessary

		Open Session		LESessionContext::getLESessionContext()
					   Call If_CreateSC() of the LE

Get Focus   ->	Session->set_focus()  ->LESessionContext::set_focus()
					   Call If_SetSCFocus() of the LE

Lose Focus  -> 	Session->unset_focus()->LESessionContext::unset_focus()
					   Call If_UnsetSCFocus() of the LE

Key Input   ->	Session->send_event() ->LESessionContext::send_event()
					   Call If_SendEvent() of the LE

Preedit draw <-	iml_execute()         <-IML methods and iml_execute()
					   LE calls IML methods and
					   iml_execute() for preedit drawing,
					   lookup drawing and aux drawing

Exit	    ->  Close the Session     ->Delete LESessionContext
					   Call If_DestroySC() of the LE

Wrappers for SunIM
==================
   SunIM library is based on C language. Htt Core uses the wrapper
   of C++ version to call SunIM library.

   sunim.hh, sunim_wrapper.cpp

	defines UserInfo, LEInterface and LESessionContext class.

	UserInfo class
		is used for the argument of constructor of
		LESessionContext username, hostname and displayid
		are used for the constructor. A user is identified
		by these three information. The additional information
		such as client type, protocol type and os version of
		the client can be set by set_values() method.

	LEInterface class
		wrapper of iml_if_t structure which defines
		the language engine module. Htt Core opens the
		LEInterface through InterfaceModule class

		LEInterface		IF methods (SunIM.c)
		----------------	--------------------
		LEInterface()		if_OpenIF()
		~LEInterface()		if_CloseIF()
		set_values()		if_SetIFValues()
		get_values()		if_GetIFValues()

	LESessionContext class
		wrapper of iml_session_t which defines
		the session of the IM connection. Each method of
		this class is corresponded with each If method
		defined in SunIM.c

		LESessionContext	IF methods (SunIM.c)
		----------------	--------------------
		LESessionContext()	if_CreateSC()
					if_OpenDesktop()
		~LESessionContext()	if_DestroySC()
					if_CloseDesktop()
		set_values()		if_SetSCValues()
		get_values()		if_GetSCValues()
		reset()			if_ResetSC()
		set_focus()		if_SetSCFocus()
		unset_focus()		if_UnsetSCFocus()

		When the session creation is the first time or the last
		time for the user desktop, if_OpenDesktop() and
		if_CloseDesktop() will be called in LESessionContext() and
		~LESessionContext(). These methods are used for user
		management.

About SunIM (for code review)
=============================

   - what is your component for?
	- what functionalities?

	  Htt Core uses this SunIM library to control language engine modules.
	  This library is based on XSunIM interfaces. This version provides
	  C++ wrapper for Htt core.

	- who uses your component?

	  o Htt Core
	  o IMdkit calls static function of LEInterface to pass
	    X event to XSunIM based LEs.

	    LEInterface::BC_xsunim_filterevent((IMInputEvent*)&x_event);

	    Note: may be changed because X handling object will be implemented.
		  We need to find more simple solution.

	- when is your component used?

	  At Htt start up:

		o Htt will initialize this library

		o Htt will gather the information such as HRN and supported
		   locale, of LE that are installed on the system.

	  Htt gets IM connection:

		o Htt creates LEInterface for the connection
		   If the language engine isn't used yet, the library
		   will create LEInterface for the LE module

		o Htt creates LESessionContext for the connection
		   Htt core creates a LESessionContext per IM client.

	- where is your component used?

	  IMdkit
		o lib/IMdkit/ximp/XIMProtocol.cpp

	  Htt Core
		o programs/im_server/session/LEManager.cpp
		o programs/im_server/session/sessioniml_sunim.cpp
                
   - how is development status?
	- what are done so far?

		See remaining tasks

	- what are remaining tasks?

	  o need SPI to inform client type to LE (BugID:4231518)

		Already added the suggested fix.
		Please review the suggested fix in the bugreport.

		The fix requires the changes of IM client. IM client
		needs to send information of the client system.

	  o COLOR setting APIs (BugID:4214314)

		Already evaluated. IMFeedback can be used.

		The fix requires the changes of IM client. IM client
		needs to render the text as IMFeedback.

	  o API set for Motif AUX support (BugID:4233516)

		IML methods of SunIM library are stable. The fix
		requires the changes of X handling object.

		Already added the suggested fix.
		Please review the suggested fix in the bugreport.

	- what you know are issues?

		See remaining tasks

	- how is portability to NT or Linux?

		Already succeeded to run NT and Linux

	- how is coding style of your component?
                                
   - Interfaces your component imports from others if any

	- modules(functions) names to import the interfaces

	  Imports two variable to start XSunIM adapter and
	  SunIM adapter.

	  src/server/lib/XSunIM_Adapter/XSunIMWrapper.cpp

		if_methods_t xsunim_methods;

	  src/server/lib/SunIM_Adapter/SunIMWrapper.cpp

		if_methods_t sunim_methods;

	- pointer to documents/specs of the interfaces

		src/server/lib/XSunIM_Adapter/README

	- if you know there are other components which imports
          same interfaces, what are they?
                
   - Interfaces your component exports to others if any

	- how stable are the interfaces?

		stable except UserInfo class

		UserInfo class will be updated for BugID:4231518.
		We needs to add more information to the class.

	- modules(functions) names to export the interfaces

		See `Wrappers for SunIM' section

	- pointer to documents/specs of the interfaces

	  SPI specification:

		doc/SPI/Language_Engine_Interface.html

	  This document:

		server/lib/LE_Interface/README

	- what components imports the interfaces?

		See `who uses your component?' section

SunIM library (Detail)
======================
   SunIM library core is based on C language. Theses functions will be
   called through SunIM wrapper of C++ version from Htt Core.

   SunIMCore.h,SunIMMMan.h,SunIMMthd.h,SunIMPriv.h,SunIMProt.h,SunIMPub.h
   SunIM.h

	definitions for SunIM library

	Note: these header files can be unified into one or two file(s).
	      Any idea?

   SunIM.c
	IF methods are defined.  Please refer the SPI documentation
	for the functionalities of IF methods,

		doc/SPI/Language_Engine_Interface.html#if

   SunIMConf.c
	if_configure()
		loads LE module dynamically from systems and retrieve
		information of the LE.

		If the module is not found on the system, the le is
		considered as XSunIM based module and SunIM calls the
		If methods of XSunIM adapter.

		If the module declare the le has locale dependency,
		SunIM calls the If methods of SunIM adapter.

	get_ifinfo()
		retrieves information from LE module.

	open_le_module(), close_le_module()
		uses dlopen() and dlclose() for UNIX, LoadLibrary() and
		FreeLibrary() are used for Win32 platform.

   SunIMMMan.c
	backward compatibility for XSunIM adapter.

	MM methods used in XSunIM were called directly from XSunIM based
	le module, not through the references of s->If->m. So we need to
	put _iml_new(), _iml_delete(), _iml_new2() and _iml_delete2() in
	the core of Htt.

   SunIMSubr.c
	IML methods are defined here. Please refer the SPI documentation
	for the functionalities of IML methods,

		doc/SPI/Language_Engine_Interface.html#iml

Looking for LEs from system
===========================

   InterfaceModule.hh, InterfaceModule.cpp

	InterfaceModule class is used in Htt Core. At the startup of Htt,
	Htt gathers what kind of LE are available from the system.
	LELookup class returns the list of LE as list of InterfaceModule.

	InterfaceModule just opens LEInterface of the LE and retrieves
	the information, such as ifpath, ifname, locale, list of object
	descriptor, and closed the LE, but it keeps the information.
	Htt can refer the information any time without opening the LE.

   LELookup.hh, LELookup.cpp
	LELookup class gathers the LE that available on the system
	and return the list of InterfaceModule.

	getListOfLEsFromSystem()
		This method gathers the LEs from ifpath directory.
		The default path is /usr/lib/im/leif. This class
		opens the directory and search .so files.

	mergeFromConfigFile()
		This method gathers the LEs from config file.
		The default path is /usr/lib/im/etc/im.config.
		It's for XSunIM based LEs because there was no
		way to declare the human readable name dynamically.

Example
=======
   sample.cpp
	example for sunim_wrapper.cpp which can run without iiimd
	to verify the SunIM wrapper can work properly.
