IImeActiveDict

August 2003

Microsoft Corporation

Summary: This document describes the program dictionary for Microsoft IME 2003, Japanese version. The program dictionary uses the Component Object Model (COM) and contains the IImeActiveDict interface. The IImeActiveDict interface and its sub-class interfaces communicate with the IME dictionary kernel. (10 printed pages)

Contents

Registering the Program Dictionary
Obtaining the IImeActiveDict Interface Pointer
Data Structure
The IUnknown Interface
The IImeActiveDict Interface
Notes on Dictionary Implementation

Registering the Program Dictionary

The program dictionary will have a .DIC extension, just like any other IME dictionary. There are two ways to register a new dictionary:

1. The user can add a new dictionary from the dictionary property dialog box by clicking the Add button in the system dictionary group.
2. A new dictionary put into the default system dictionary folder is automatically scanned by Microsoft® IME and added to the registry. This scanning occurs when the property dialog is opened.

Obtaining the IImeActiveDict Interface Pointer

First, Microsoft IME will try to load the current active dictionary as a DLL. If it succeeds to load a DLL, it will try to get a predefined function through GetProcAddress(). This process occurs whenever Microsoft IME is initialized.

HRESULT CreateIImeActiveDictInstance(
VOID *ppvObj,
int  nid
);

• This function is case sensitive and must be exported from the program dictionary.
• One DLL can handle only one dictionary. This means one dictionary path maps to one dictionary.
• This process eliminates the use of class and interface IDs provided by the COM library.

Data Structure

The following structures are used to obtain dictionary information.

IMESHF2

The IMESHF2 describes a program dictionary. For example:

//Shared Header dictionary File
typedef struct {
   WORD   cbShf;               //size of this structure
   WORD   verDic;               //dictionary version
   WCHAR   wszTitle[48];         //dictionary title
   WCHAR   wszDescription[256];   //dictionary description
   WCHAR   wszCopyright[128];   //copyright information
} IMESHF2;

IMEDINFO

The IMEDINFO contains all of the information required to handle the dictionary. For example:

//Dictionary Info
Typedef struct _IMEDINFO
{
   IMESHF2   shf;      //header
   DWORD      ver;      //IImeActiveDict version number
   IMEDDISC   ddisc;      //disclosure permission type
   FILETIME   filestamp;  //file stamp at creation
   IMEDICAT   dicat;      //dictionary category
   IMEIDXTP   idxtp;      //index type
   WCHAR      wszHeading[cwchHeadingLen];   // Heading string which 
                                          // will be shown in candidate
                                          // box.
   BOOL      fSkipInitialSearch;   // If TRUE, this dictionary will be
                                 // skipped during initial search.
} IMEDINFO;

IMEPDT

The following data structure is used to obtain words from the dictionary:

#define cwchWordMax         64
typedef DWORD      IMESTMP;         //word stamp
//Program Dictionary Tango
Typedef struct _IMEPDT
{
   IMEIDXTP   idxtp;   //index type
   int   cwchInput;   //input string length
   int   cwchOutput;   //output string length
   WCHAR   wszInput[cwchWordMax];   //input string
   WCHAR   wszOutput[cwchWordMax];   //output string
   DWORD   nPos;   //part of speech
   IMESTMP   stmp;   //word time stamp
   union{
       DWORD   dwWordId;
       struct{
           DWORD   WordId : 20;   //word ID
           DWORD   fComment : 1;   //TRUE when this entry has word
         //comment.
           DWORD   dwFree : 11;
       };
   };
   WORD   wMojiKind;   //moji kind
} IMEPDT;

The IUnknown Interface

The IImeActiveDict interface follows the COM specification. The COM interface must be binary compatible and can be written by any computer language that supports function pointers. C++ is the recommended language, because it is object oriented and supports inheritance.

A COM interface must support the IUnknown interface, which consists of three basic functions: QueryInterface(), AddRef(), and Release().

IUnknown::QueryInterface

Not used.

HRESULT IUnknown::QueryInterface(
REFIID riid,
VOID **ppv
);

REFIID riid

VOID **ppv

IUnknown::AddRef

This function will keep track of the number of clients using this object. The client should call AddRef() whenever it makes a copy of the interface pointer. This way, the object knows how many copies of the object pointer are in use.

ULONG IUnknown::AddRef(VOID);

IUnknown::Release

The client should call this method when it is finished with an interface pointer. The reference count is decrement, and the object should destroy itself when the count reaches zero.

ULONG IUnknown::Release(VOID);

The IImeActiveDict Interface

Microsoft IME will use the interface pointer obtained fromCreateIImeActiveDictInstance()to access the following interface functions. These are specific to this interface and must be supported by the program dictionary.

IImeActiveDict::Inquire

This function can be called before opening a program dictionary. Microsoft IME may use the dictionary information returned by this function to decide whether the dictionary should or should not be used.

HRESULT IImeActiveDict::Inquire(
IMEDINFO *pdinfo
);

IImeActiveDict::Open

Microsoft IME will call this function just before accessing this program dictionary to obtain dictionary information. The pdinfo parameter should be returned with all fields filled.

HRESULT IImeActiveDict::Open(
IMEDINFO *pdinfo
);

IImeActiveDict::Close

Microsoft IME will call this function when an opened program dictionary is no longer needed. All resources attached with the program dictionary may be freed at this time. Since Microsoft IME may still keep the interface pointer, do not destroy the object instance at this time.

HRESULT IImeActiveDict::Close(void);

IImeActiveDict::SearchWord

This function searches for a word with a given input string. Microsoft IME calls this repeatedly until all words with the same input string are returned. It is up to the program dictionary to cache the searching state to increase performance. It is important to check for longer words with the input string as the prefix, and return IDICT_LONGER_WORD, in order to increase the performance of Microsoft IME.

HRESULT IImeActiveDict::SearchWord(
IMEPDT *ppdt,
BOOL fFirst,
BOOL fWildCard
);

IImeActiveDict::GetComment

Obtains a comment for a tango. The client obtains the size of the comment (in bytes) by calling this routine with pv set to NULL.

HRESULT IImeActiveDict::GetComment(
DWORD dwWordId,
VOID *pv,
DWORD *pdwSetID,
int *pcb,
IMEUCT *puct,
WORD *pwMojiKind
);

IImeActiveDict::OpenProperty

When this function is called, the program dictionary can create a window and/or a dialog box in which extra properties for the dictionary are shown and manipulated. The property window/dialog box should be modal, and it should be created in the same process as the program dictionary.

HRESULT IImeActiveDict::OpenProperty(
HWND hwnd
);

Notes on Dictionary Implementation

• The program dictionary must be read only.
• A program dictionary will be included in the dictionary set used by the IME kernel during morphological analysis. About 50 percent of the processing time is occupied by accessing the dictionary. It is important that the program dictionary's word retrieval routines are as efficient as possible.
• One way of improving performance is to use internal caching, which stores data in memory to avoid disk accesses. It should be noted that IME is attached to each application, and dictionaries are opened when IME is being attached. This indicates that the program dictionary's data space is not shared among applications. A program dictionary would use a great deal of memory if it allocated a caching memory for each process.
• In order to avoid this scenario, Win32 provides a memory-sharing mechanism among processes, called a memory-mapped file. It is desirable that program dictionaries use memory-mapped files to implement dictionary caching. APIs involved are CreateFileMapping(), MapViewOfFile(), UnmapViewOfFile(), and CloseHandle(). Please look at Win32 reference for detailed information on memory-mapped files.