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_SJIS
is a string in Shift JIS format andIFED_UCT_STRING_UNICODE
is 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 andcbComment
will be zero if there are no user comments for that word. Otherwise, the IMEUCT field specifies the type of user comment. ThepvComment
is 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 |