IFEDictionary

 

August 2003

Microsoft Corporation

Summary: This document describes the IFEDictionary interface for the Microsoft IME 2003, Japanese version. The IFEDictionary interface allows clients to access a Microsoft IME user dictionary. (12 printed pages)

Contents

Data Structures
Creating an IFEDictionary Instance
Operating the Dictionary File Object
Getting and Registering Words

This is a global interface.

Interface ID: IID_IFEDictionary
Version: 1.0

Note   Regarding the usage of this API: This API is intended to enable your applications to access and use the data contained in the Microsoft® IME dictionaries (including personal names & geographical names dictionaries) or user dictionary, and you can develop and sell such applications, provided that: 1) You do not create an application that accesses a dictionary that is not a Microsoft IME dictionary through this API, and 2) you do not dump, copy, and distribute the dictionaries' data contained in the Microsoft IME. You must use the API only for the purpose of developing applications for users who already have the Microsoft IME.

IFEDictionary Methods Description
Open Open dictionary file
Close Close dictionary file
GetHeader Get distionary header from dictionary file
SetHeader Set dictionary header to dictionary file
Create Create a user dictionary file
Release Free the IFEDictionary object
GetPosTable Get public POS table
GetWords Get word entry from dictionary
NextWords Get next word entry from dictionary
ExistWord Check if specified word exist in dictionary
RegisterWord Register a word into dictionary
DisplayProperty Invokes OpenProperty method of IImeActiveDict interface.

Data Structures

WORD Descriptor—IMEWRD

typedef struct _IMEWRD {
    WCHAR *pwchReading;
    WCHAR *pwchDisplay;
    union {
        ULONG ulPos;
        struct {
            WORD nPos1; //hinshi
            WORD nPos2; //extended hinshi
        };
    };
    ULONG rgulAttrs[2]; //attributes
    INT cbComment; //size of user comment
    IMEUCT uct; //type of user comment
    VOID *pvComment; //user comment
} IMEWRD, *PIMEWRD;

User Comment Type—IMEUCT

typedef enum
{
IFED_UCT_NONE,
IFED_UCT_STRING_SJIS,
IFED_UCT_STRING_UNICODE,
IFED_UCT_USER_DEFINED,
IFED_UCT_MAX,
} IMEUCT;

Notes on User Comment

IMEUCT specifies the type of user comment.IFED_UCT_STRING_SJISis a string in Shift JIS format andIFED_UCT_STRING_UNICODEis a string in Unicode format. If a string is null-terminated, the size of data must include the last null character. IFED_UCT_USER_DEFINED means a client can register a word of this type with User Comment and use it for whatever reason the client may have. The IME kernel will not use a word of this type during morphological analysis. When IMEWRD structure is returned via GetNextWord, the pvComment field will be set to NULL andcbCommentwill be zero if there are no user comments for that word. Otherwise, the IMEUCT field specifies the type of user comment. ThepvCommentis allocated by IFEDictionary object. The buffer size is the actual data size (cbComment) plus two, and the last two bytes are set to zero. This allows non-zero-terminated strings to be made zero-terminated without copying the strings to another location with a bigger buffer. The client must free the pvComment buffer.

Dictionary Header—IMESHF

typedef struct {
    WORD cbShf; //size of SHF
    WORD verDic; //user specified dictionary version
    CHAR szTitle[48]; //title of dictionary
    CHAR szDescription[256]; //description of dictionary
    CHAR szCopyright[128]; //copyright info
} IMESHF;

Creating an IFEDictionary Instance

This creates an IFEDictionary object, and returns a pointer to the object. This is one way of obtaining an interface pointer to IFEDictionary. Another way of obtaining this pointer is via IFECommon interface, using the QueryInterface method with IID_IFEDictionary interface ID defined in MSIME.H. This is a DLL function.

HRESULT CreateIFEDictionaryInstance

Parameter Description
void **ppvObj (OUT) A pointer to the created object is placed
Return Values
HRESULT S_OK
E_OUTOFMEMORY
E_FAIL

Operating the Dictionary File Object

HRESULT IFEDictionary::Open

This opens an existing dictionary file and associates it with "this" IFEDictionary object.

Parameter Description
CHAR * pchFileName (IN) Points to a file name (NULL terminated) string to be opened. If pchFileName is NULL or an empty string, user dictionary opened by the IME kernel will be used. If pchFileName is an empty string, name of user dictionary will be copied into pchFileName. In this case, the size of pchFileName must be MAX_PATH.
IMESHF * pSHF (OUT) header of the opened file is stored at pSHF. Can be NULL.
Return Values
HRESULT S_OK
JDIC_S_EMPTY_DICTIONARY
IFED_E_NOT_FOUND
IFED_E_INVALID_FORMAT
IFED_E_OPEN_FAILED
E_FAIL

To implement a multiple dictionary facility, multiple open/release procedures must be carried out.

HRESULT IFEDictionary::Close

This closes the file associated to this object.

Parameters:    None

Return Values
HRESULT S_OK
E_FAIL

HRESULT IFEDictionary::GetHeader

This method obtains the header of a dictionary without opening the dictionary.

Parameter Description
CHAR * pchFileName (IN) Points to a file name (NULL terminated) string
IMESHF * pSHF (OUT) Header of the dictionary is stored at pSHF; can be NULL
IMEFMT *pjfmt IFED_UNKNOWN,

IFED_MSIME2_BIN_SYSTEM,

IFED_MSIME2_BIN_USER,

IFED_MSIME2_TEXT_USER,

IFED_MSIME95_BIN_SYSTEM,

IFED_MSIME95_BIN_USER,

IFED_MSIME95_TEXT_USER,

IFED_MSIME97_BIN_SYSTEM,

IFED_MSIME97_BIN_USER,

IFED_MSIME97_TEXT_USER,

IFED_MSIME98_BIN_SYSTEM,

IFED_MSIME98_BIN_USER,

IFED_MSIME98_TEST_USER,

IFED_ACTIVE_DICT,

IFED_ATOK9,

IFED_ATOK10,

IFED_NEC_AI_,

IFED_WX_II,

IFED_WX_III,

IFED_VJE_20,

IFED_MSIME98_SYSTEM_CE

IFED_MSIME_BIN_SYSTEM,

IFED_MSIME_BIN_USER,

IFED_MSIME_TEXT_USER

IFED_PIME2_BIN_USER

IFED_PIME2_BIN_SYSTEM

IFED_PIME2_BIN_STANDARD_SYSTEM

ULONG *pdicat (OUT) Dictionary type is returned
dicatNone  Undefined
dicatGeneral  General dictionary
dicatNamePlace  Name/place dictionary
dicatSpeech  Speech dictionary
dicatReverse  Reverse dictionary
dicatEnglish  English dictionary
dicatALL  Or of above flags
Return Values
HRESULT S_OK
IFED_E_INVALID_FORMAT
E_FAIL

HRESULT IFEDictionary::SetHeader

This sets/modifies the dictionary header of "this" IFEDictionary object.

Parameter Description
IMESHF * pSHF (IN) Points to a dictionary header structure.
Return Values
HRESULT S_OK
E_FAILED

HRESULT IFEDictionary::Create

This creates a user dictionary and associates it with "this" IFEDictionary object.

Parameter Description
CHAR * pchFileName (IN) Points to a file path (Null terminated) string to be created
IMESHF * pSHF (IN) Points to a dictionary header structure
Return Values
HRESULT S_OK
IFED_S_EMPTY_DICTIONARY
E_OUTOFMEMORY
E_FAIL

ULONG IFEDictionary::Release

This frees the IFEDictionary object.

Getting and Registering Words

HRESULT IFEDictionary::GetPosTable

This method obtains the public POS (Part of Speech) table. Since this table is language and IME dependent, clients must include an appropriate header for a particular language. For Japanese, the header is named "msime.h" and includes the following data structure.

POSTBL

//POS table data structure
typedef struct _POSTBL {
    WORD nPos; //pos number
    BYTE *szName; //name of pos
} POSTBL;
Parameter Description
POSTBL **prgPosTbl (OUT) pointer to the array of POSTBL.
int *pcPosTbl (OUT) pointer to the count of part of speech in POSTBL; can be NULL.
Return Values
HRESULT S_OK
E_FAIL

HRESULT IFEDictionary::GetWords

This method gets word entries from a dictionary. The selection can be performed by a combination of: 1) a string with Japanese phonetic characters, with or without a wildcard at the end of the string, 2) a word, with or without a wildcard at its end, 3) by Part of Speech. In addition, retrievals by a string with Japanese phonetic characters can be performed by specifying a range in the Hiragana 50-on ordering.

Parameter Description
WCHAR * pwchFirst, (IN) Points to a text string against which IFEDictionary entries are matched; the value must be one of the following:
NULL (meaning "low-value")
Hiragana string (full text to be retrieved)
Hiragana string ended by "*" (specifying only leading characters of text)
This can be a initial text string when a range of words is to be retrieved, in which case a wildcard must not be used
WCHAR * pwchLast, (IN) Points to a text string. This is used to end a text string. This must contain the same value of pwchReading when a retrieval is performed by a single value; that is, not by a range value. The value must be one of the following:
NULL (meaning "high-value")
Hiragana string (full text to be retrieved)
Hiragana string ended by "*" (specifying only leading characters of text)
WCHAR * pwchDisplay, (IN) Points to a display string against which IFEDictionary entries are matched; the value must be one of the following:
NULL (meaning "*")
Any Japanese string

Japanese string ended by "*"

ULONG ulPos, The filters of Microsoft IME public POS:
IFED_POS_NONE
IFED_POS_NOUN
IFED_POS_VERB
IFED_POS_ADJECTIVE
IFED_POS_ADJECTIVE_VERB
IFED_POS_ADVERB
IFED_POS_ADNOUN
IFED_POS_CONJUNCTION
IFED_POS_INTERJECTION
IFED_POS_INDEPENDENT
IFED_POS_INFLECTIONALSUFFIX
IFED_POS_PREFIX
IFED_POS_SUFFIX
IFED_POS_AFFIX
IFED_POS_TANKANJI
IFED_POS_IDIOMS
IFED_POS_SYMBOLS
IFED_POS_PARTICLE
IFED_POS_AUXILIARY_VERB
IFED_POS_SUB_VERB
IFED_POS_DEPENDENT
IFED_POS_ALL
ULONG ulSelect (IN) Bit mask that specifies the query output of a word; must be logical OR one of the following:
IFED_SELECT_NONE
IFED_SELECT_READING
IFED_SELECT_DISPLAY
IFED_SELECT_POS
IFED_SELECT_ALL
Other bits are reserved for future extensions (translation, definition, etc.)
ULONG ulWordSrc (IN) Bit flag to specify the word source; must be logical OR one of the following when the IFEDictionary is a user dictionary:
IFED_REG_NONE
IFED_REG_USER
IFED_REG_AUTO
IFED_REG_GRAMMAR
IFED_REG_ALL
Other bits are reserved for future extensions
UCHAR * pchBuffer (IN/OUT) The caller provides the buffer and this function fills up the data
ULONG cbBuffer (IN) size of pchBuffer
ULONG * pcWrd (OUT) Number of IMEWRD structures returned in buffer; if more entries are found than the pchBuffer can store, an IFED_S_MORE_ENTRIES will be returned
Return Values
HRESULT S_OK
IFED_S_MORE_ENTRIES—Client must call NextWords to get additional IMEWRD structures
IFED_E_NO_ENTRY
E_OUTOFMEMORY
E_FAIL

HRESULT IFEDictionary::NextWords

The following must be used after GetWords to get additional words:

Result Parameters
UCHAR * pchBuffer (IN/OUT) The caller provides the buffer and this function fills up the data
ULONG cbBuffer (IN) size of pchBuffer
ULONG * pcWrd (OUT) Number of IMEWRD structures returned in buffer; if more entries are found than the pchBuffer can store, an IFED_S_MORE_ENTRIES will be returned
Return Values
HRESULT S_OK
IFED_S_MORE_ENTRIES—Client must call NextWords to get additional IMEWRD structures
E_FAIL

HRESULT IFEDictionary::ExistWord

This determines whether the specified word exists in the IFEDictionary.

Parameter Description
IMEWRD *pwrd (IN) word being checked
Return Values
HRESULT S_OK—word exists
S_FALSE—word does not exist
E_FAIL—error condition

HRESULT IFEDictionary::RegisterWord

This registers a word in the IFEDictionary.

Parameter Description
IMEREG reg (IN) Register type
IFED_REG_HEAD - register the word at head
IFED_REG_TAIL - register the word at tail
IFED_REG_DEL - delete the word.
IMEWRD * pWrd (IN) Points to an IMEWRD structure.
Return Values
HRESULT S_OK—success
IFED_E_NOT_USER_DIC—this object is not a user dictionary
IFED_S_WORD_EXISTS—word is already registered
IFED_E_USER_COMMENT—failed to insert user comment
S_FALSE—failed to register/delete a word
E_FAIL—unexpected error

HRESULT IFEDictionary::DisplayProperty

Invokes the OpenProperty method of the IImeActiveDict interface. This only works when the current dictionary has the IImeActiveDict interface.

Parameter Description
HWND hwnd (IN) Parent window handle
Return Values
HRESULT S_OK—success
E_FAI—unexpected error