IImePad, IImePadApplet Interface specification

Overview

IImePad, IImePadApplet are both COM based interface of MSIME98. IImePad provides the Architecture for non hardware keyboard input method (software keyboard, HW recognition, etc.) IImePad manages IImePadApplet, and intermediates between other IME Component and IImePadApplet. The Request for inputting composition string from IImePadApplet is transfer to other MSIME Component through IImePad.

IImePadApplet is one interface for ImePad's Applet. Applet is implemented as DLL module. It provides IImePadApplet interface as inproc server. Users can implement multiple IImePadApplet interfaces in one DLL. To specify and emulate IImePadApplet interface in Applet DLL, Applet has to provide IImeSpecifyApplets interface also. All interacts are global interface, defined in imepad.h

This documents describes interface definition of IImePad, IImePadApplet, and IImeSpecifyApplets to realize these implementations.

IImePad

The IImePad interface specifies methods that handle several requests from IImePadApplet. Only one method Request() is provided, and IImePadApplet can request several methods with RequestId.

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interface
AddRef	Increment reference count
Release	Decrement reference count

IImePad methods	Description
Request	request several method with RequestId.

IImePad::Request

The Request() is called by IImePadApplet with RequestId to handle composition string, and other requests.

HRESULT Request(
    IImePadApplet *pIImePadApplet,
    INT reqId,
    WPARAM wParam,
    LPARAM lParam
); 

ImePadApplet [in] set self Applet Interface pointer.

reqId [in] specifies IMEPAD's Request ID

wParam [in/out] Specifies additional Request ID specific information

Param [in/out] Specifies additional Request ID specific information

Return Value

   S_OK    Success 
   S_FALSE Failure

Remarks

Request method is similar to Win32API's SendMessage(). Set the Request ID and request id related wParam, lParam value.

RequestID

IMEPADREQ_INSERTSTRING

Applet can use IMEPADREQ_INSERTSTRING to insert string to Application as composition string.

wParam = (WPARAM)lpwstr;
lParam = 0;

Parameters

lpwstr Value of wParam, Point to the null-terminated string that is to be inserted to the Application.

Return value

S_OK     success
S_FALSE error

IMEPADREQ_INSERTSTRINGCANDIDATE

Applet can use IMEPADREQ_INSERTSTRINGCANDIDATE to insert string and its candidate string to Application.

wParam = (LPIMESTRINGCANDIDATE)lpStringCandidate;
lParam = 0;

Parameters

Return Value

S_OK success
S_FALSE error

IMEPADREQ_SENDCONTROL

Applet can use IMEPADREQ_SENDCONTROL to control composition string,  caret, etc., in Application.

wParam = (WPARAM)ctrl;<
lParam = 0; 

ctrl Value of wParam, specifies Control value that requests IME to process composition string, caret position.

S_OK Success
S_FALSE Failure

IMEPADREQ_GETCOMPOSITIONSTRING

Applet can use IMEPADREQ_GETCOMPOSTIONSTRING to get composition string in application.

wParam = (WPARAM)lpwstr;
lParam = (LPARAM)nMaxCount;

Parameters

Return Value

S_OK Success
S_FALSE Failure

IMEPADREQ_SETAPPLETSIZE

Applet can use IMEPADREQ_SETAPPLETSIZE to set new applet window size.

wParam = MAKEWPARAM(width, height);
lParam = no use

Parameters

Width, height Value of wParam. Set the new Applet width and height.

Return Value

S_OK Success
S_FALSE Failure

IMEPADREQ_SETAPPLETDATA

Applet can use IMEPADREQ_SETAPPLETDATA to set Applet original data. It is saved to registry, and can get it with IMEPADREQ_GETAPPLETDATA.

Param = (WPARAM)(PBYTE)pByte;
lParam = (LPARAM)(INT)size;

Parameters

Return Value

S_OK Success
S_FALSE Failure

IMEPADREQ_GETAPPLETDATA

Applet can use IMEPADREQ_GETAPPLETDATA to get Applet original data.

wParam = (WPARAM)(PBYTE)pByte
lParam = (LPARMA)(INT)size

Parameters

IMEPADREQ_GETCOMPOSITIONSTRINGINFO

Applet can use IMEPADREQ_GETCOMPOSITIONSTRINGINFO to get current composition strings information.

wParam = (WPARAM)(LPIMECOMPOSITIONSTRINGINFO)lpImeCompInfo.
lParam = 0; //no use.

Structure

typedef struct tagIMECOMPOSITIONSTRINGINFO {
    INT iCompStrLen;
    INT iCaretPos; 
    INT iEditStart;
    INT iEditLen;
    INT iTargetStart;
    INT iTargetLen;
}IMECOMPOSITIONSTRINGINFO, *LPIMECOMPOSITIONSTRINGINFO;

Parameters

S_OK Success
S_FALSE Failure

IMEPADREQ_GETCOMPOSITIONSTRINGID

Applet can use IMEPADREQ_GETCOMPOSITIONSTRINID to get composition string and its each Characters ID

wParam = (WPARAM)(LPIMECHARINFO)lpCharInfo;
lParam = (LPARAM)(INT)dwMaxLen;

Structure

typedef struct tagIMECHARINFO {
   WCHAR wch;
   DWORD dwCharInfo;
}IMECHARINFO, *LPIMECHARINFO;

Parameters

Return Value

S_OK Success
S_FALSE Failure

dwCharInfo includes Applet's Id, Lang Definition, character id.

IMEPADREQ_INSERTSTRINGINFO

Applet can use IMEPADREQ_INSERTSTRINGINFO to insert string to composition string with Fareast id, and can get Character Info.

wParam = (WPARAM)(LPIMESTRINGINFO)lpStrInfo;
lParam = (LPARAM)dwStartPos;

Parameters

Structure

typedef struct tabIMESTRINGINFO {
    DWORD dwFarEastId;
    LPWSTR lpwstr;
}IMESTRINGINFO, *LPIMESTRINGINFO;

Return value

If this value is 0, it means function failed, otherwise CharacterId(non-zero) of appended/changed string is "First" character's id. The type of ID is DWORD.

IMEPADREQ_CHANGESTRINGINFO

Applet can use IMEPADREQ_CHANGESTRINGINFO to change composition string with new string with Fareast Id. and can get Character Id.

wParam = (WPARAM)(LPIMESTRINGINFO)lpInfo;
lParam = MAKELPARAM(wStartPos, wLength);

Parameters

Return value

if this value is 0, it means function failed, otherwise CharacterId(non-zero) of appended/changed string's "First" characters id. The type of ID is DWORD.

IMEPADREQ_CHANGESTRING

Applet can use IMEPADREQ_CHANGESTRING to change composition string.

wParam = (WPARAM)(LPWSTR)lpwstr;
lParam = MAKELPARAM(wStartPos, wLength);

Parameters

S_OK Success
S_FALSE Failure

Difference from IMEPADEQ_CHANGESTRING is return value and can set Far east id.

IMEPADREQ_INSERTSTRINGCANDIDATEINFO

Applet can use IMEPADREQ_INSERTSTRINGCANDIDATEINFO to insert string with Candidate, and get Character Id.

wParam = (WPARAM)(LPIMESTRINGCANDIDATEINFO)lpCandInfo;
lParam = (LPARAM)(DWORD)dwStartPos;

Parameters

Structures

typedef struct tabIMEFAREASTINFO { 
    DWORD dwSize; 
    DWORD dwMask; 
    DWORD dwData[1]; 
}IMEFAREASTINFO, *LPIMEFAREASTINFO;

typedef struct tagIMESTRINGCANDIDATEINFO {
    DWORD dwFarEastId;
   LPIMEFAREASTINFO lpFarEastInfo;
   DWORD fInfoMask;
    INT iSelIndex;
    UINT uCount;
    LPWSTR lpwstr[1];
}IMESTRINGCANDIDATEINFO, *LPIMESTRINGCANDIDATEINFO;

Return value

If this value is 0, it means function failed. Otherwise Character Id(non-zero) of appended/changed string's "First" characters id. The type of ID is WORD.

Remarks

Applet can use this Interface to insert string with candidate and have two choices. You can control it with fInfoMask's value

1. Send string with candidate.

2. First, send string of top candidate. If IME tries to show candidate list on composition string, IME sends notify (IMEPN_QUERYCAND)to applet to tell that IME is about to show candidate. IMEPN_QUERYCAND notify comes with Character Id. If applet received this notify, applet can recognize what character's candidate that IME wants. Applet can call this interface to create and show candidate dynamically.

IMEPADREQ_CHANGESTRINGCANDIDATEINFO

Applet can use IMEPADREQ_CHANGETRINGCANDIDATEINFO to change composition string with Candidate, and get Character Id.

wParam = (WPARAM)(LPIMESTRINGCANDIDATEINFO)lpCandInfo;
lParam = MAKELPARAM(startPos, length);

Parameters

If this value is 0, it means function failed. Otherwise Character Id(non-zero) of appended/changed strings's "First" characters id. The type of ID is WORD.

Remarks

This Interface is almost same as IMEPADREQ_INSERTSTRINGCANDIDATEINFO. The difference is that Applet can specify replace area of composition string.

IMEPADREQ_DELETESTRING

Applet can use IMEPADREQ_DELETESTRING to delete composition string.

wParam = MAKEWPARAM(wStartPos, wLength);
lParam = 0; //not used.

Parameters

S_OK success
S_FALSE error

IMEPADREQ_GETAPPLHWND

Applet can use IMEPADREQ_GETAPPLHWND to get Application window handle

wParam = (WPARAM)(HWND *)pHwnd;
lParam : not used

pHwnd Value of wParam, specifies HWND handle address to get Application window handle.

S_OK success
S_FALSE error

IMEPADREQ_FORCEIMEPADWINDOWSHOW

Applet can use IMEPADREQ_FORCEIMPADWINDOWSHOW to keep imepad window visible.

wParam = (BOOL)fShow
lParam : not used

Remarks
In a normal case, IImePad UI is activated if IME's context is active. if Applet want to keep ImePad UI visible(when Applet invoke Property Dialog, etc.) Applet can keep ImePad UI visible with this request.

IMEPADREQ_POSTMODALNOTIFY

If Applet call Request with IMEPADREQ_POSTMODALNOTIFY, imepad call's applet's Notify() asynchronously with
specified notify id and user data. 

wParam = (WPARAM)notifyCode
lParam = (LPARAM)dwUserData;

S_OK success
S_FALSE error

The IImePadApplet interface specifies methods called from IImePad, Create window, and several notify.

The Initialize() method is called from IImePad to initialize IImePadApplet.

HRESULT Initialize(
   IUnknown *pIUnknown //IUnknown pointer to query IImePad
);

pIUnknown
  [in] address of IUnknown interface. IImePadApplet can get IImePad interface pointer with using QueryInterface()

Remarks

When ImePad user interface created, IImePad calls this method, and sets IImePad interface pointer as argument. Applet can call pIImePad->Request() method with this pointer.

The Terminate() method is called from IImePad to terminate IImePadApplet.

HRESULT Terminate(VOID);

Remarks
  IImePad calls this method when finish to use IImePadApplet.

IImePadApplet::GetAppletConfig

The GetAppletConfig() is called from IImePad to get IImePadApplet's configuration data.

HRESULT GetAppletConfig(
    LPIMEAPPLETCFG lpCfg 
);

Return Value

S_OK success
S_FALSE error

Remarks

This method is called from IImePad to get Applet specific data. This method can be called before Calling Initialize () method. LPIMEAPPLETCFG data definition is as follows:

Structure

typedef struct tagAPPLETCFG {
    DWORD dwConfig; 
    WCHAR wchTitle[MAX_APPLETTITLE]; 
    WCHAR wchTitleFontFace[MAX_FONTFACE]; 
    DWORD dwCharSet; 
    INT iCategory; 
    HICON hIcon;
    LPARAM lReserved1;
    LPARAM lReserved2;
}MEAPPLETCFG, *LPIMEAPPLETCFG;

The CreateUI() is called from IImePad to get Applet's window handle, style, size. Applet can set its window style, sizing policy.

HRESULT CreateUI(

    HWND hwndParent, 
    LPIMEAPPLETUI lpAppletUI
);

Structure

typedef struct tagIMEAPPLETUI {
    HWND hwnd;  
    DWORD dwStyle; 
    INT width; 
    INT height; 
    INT minWidth; 
    INT minHeight; 
    INT maxWidth; 
    INT maxHeight; 
    LPARAM lReserved1; 
    LPARAM lReserved2; 
}IMEAPPLETUI, *LPIMEAPPLETUI;

S_OK success
S_FALSE error

IImePadApplet::Notify

The Notify() is called from IImePad to notify some kind of information with notify code.

HRESULT Notify(
    IUnknown *pIUnknown, //Pointer of IUnknown to get IImePad interface pointer 
    INT notify, //notify code
    WPARAM wParam, //first parameter
    LPARAM lParam //second parameter
);

S_OK success
S_FALSE error

notify code

IMEPN_ACTIVATE

lpwstr1 = (LPWSTR)wParam;
lpwstr2 = (LPWSTR)lParam;

IMEPN_ACTIVATE is called when IImePadApplet Window has activated. wParam, lParam maybe point reading, or converted string pointer if Applet has activated by MSIME. Normal case these value are NULL. so, if Applet use wParam & lParam as string, Applet must check this pointer is NULL or not.

IMEPN_INACTIVATE

wParam=0;
lParam=0;

IMEPN_INACTIVATE is called when IImePadApplet Window has inactivated.

IMEPN_CONFIG

wParam = 0;
lParam = 0;

IMEPN_CONFIG notification indicates that user select "Property" menu in IImePad GUI.This can be the trigger for the IImePadApplet to Show the applet specific configuration dialog.

IMEPN_MODECHANGED

convMode = (INT)wParam;
sentenceMode = (INT)lParam

IMEPN_MODECHANGED notification indicates that IME's Conversion mode or Sentence mode has changed. convMode and sentenceMode value is same that defined in imm.h

IMEPN_QUERYCAND

wParam = (WPARAM)(DWORD)dwCharInfo;
lParam = 0;

Remarks

If Applets inserted string with above interface, and fInfoMask includes NOTIFYMASK_QUERYCAND, when IME shows candidate of this character, IMEPAD sends this notify to Applet. If Applet can provide additional candidates at IMEPN_QUERYCNAD opportunity, it can add/change them through above INTERFACE. If there is no additional candidate in applet, applet has only to ignore this notify.

IMEPN_APPLYCAND

wParam = (DWORD)dwCharInfo;
lParam = (INT)nSelectedCand;

Remarks

If a user chooses one of the candidate in IME candidate list, and these candidate are inserted with IMEPADREQ_INSERTSTRINGCANDIDATEINFO, IMEPADREQ_CHANGESTRINGCANDIDATEINFO, IME will notify which candidate has selected by user through this notify. if Applet receives this notify, Applet should call IImePad::Request with IMEPADREQ_CHANGESTRING(INFO) and apply the proper changes of the composition string.

IMEPN_APPLYCANDEX

wParam = (DWORD)dwCharInfo;
lParam = (LPAPPLYCANDEXPARAM)lpApplyCandExParam;

typedef struct tagAPPLYCANDEXPARAM
{
    DWORD dwSize;  
            //Specifies the size of  
the structure, in bytes.
    LPWSTR lpwstrDisplay;    //Display string is set.
    LPWSTR lpwstrReading;    //Reading string is set.
    DWORD dwReserved;        //Reserved.
} APPLYCANDEXPARAM, *LPAPPLYCANDEXPARAM;

If a user chooses one of the candidates in IME candidate list, and these candidate are inserted with IMEPADREQ_INSERTSTRINGCANDIDATEINFO, IMEPADREQ_CHANGESTRINGCANDIDATEINFO with INFOMASK_APPLYCAND_EX, IME will notify with this info. So applet can know what Reading string and Display string has selected in IME candidate list.

IImeSpecifyApplets

The IImeSpecifyApplets interface specifies methods called from IImePad, to emulate IImePadApplet's interface.

IImeSpecifyApplet::GetAppletIIDList

The GetAppletIIDList() is called from IImePad to emulate how many IImePadApplet's interfaces are implemimplemented

HRESULT GetAppletIIDList(
   REFIID refiid, //IImePadApplet IID
   LPAPPLETIIDLIST lpIIDList //address of APPLETIIDLIST
);

Structure

typedef struct tagAPPLETIDLIST {
   INT count;
   IID *pIIDList;
}APPLETIDLIST, *LPAPPLETIDLIST;

Remarks

This method is called from IImePad, to emulate how many IImePadApplet interfaces are implemented in this Applet DLL module. Applet must compare refiid & IID_ImePadApplet that defined in imepad.h. and if refiid is same as IID_IImePadApplet that are compiled with imepad.h, applet can set IID list to pIIDList Because in the future, IImePadApplet may be enhanced. If IImePadApplet interface has enhanced, IID_IImePadApplet will be changed.