IFELanguage Functions

  • Article

 

August 2003

Microsoft Corporation

Summary: This document describes the various methods relating to the IFELanguage functions of Microsoft IME 2003, Japanese version. (7 printed pages)

 IFELanguage Methods Description
Open Opens the interface to initiate a session
Close Closes the interface to terminate a session
GetJMorphResult Gets the morphological analysis result
GetConversionModeCaps Gets the conversion mode capability
GetPhonetic Converts the string to phonetic symbols

HRESULT IFELanguage::Open

This method must be called before the use of IFELangauge for initialization.

Parameters:    None.

Return Values
HRESULT S_OK: Successfully terminated
S_FALSE: Fails to create a result

Note Microsoft® IME 98 Japanese version has the limitation that multiple processes should not initialize simultaneously through this call.

HRESULT IFELanguage::Close

This method must be called after using IFELanguage for termination.

Parameters:    None

Return Values
HRESULT S_OK: Successfully terminated
S_FALSE: Fails to create a result

HRESULT IFELanguage::GetJMorphResult

This method is used to get morphological analysis results. Before using this function, call IFELangauge::Open once for initialization.

Parameter Description
DWORD dwRequest (IN) A request for conversion
FELANG_REQ_CONV
FELANG_REQ_RECONV
FELANG_REQ_REV
DWORD dwCMode (IN) Any combination of the values below is possible, which determines the conversion output characters and some conversion options:

FELANG_CMODE_MONORUBY
FELANG_CMODE_NOPRUNING
FELANG_CMODE_KATAKANAOUT
FELANG_CMODE_HIRAGANAOUT
FELANG_CMODE_HALFWIDTHOUT
FELANG_CMODE_FULLWIDTHOUT
FELANG_CMODE_BOPOMOFO
FELANG_CMODE_HANGUL
FELANG_CMODE_PINYIN
FELANG_CMODE_PRECONV
FELANG_CMODE_RADICAL
FELANG_CMODE_UNKNOWNREADING
FELANG_CMODE_MARGECAND
FELANG_CMODE_ROMAN
FELANG_CMODE_BESTFIRST
FELANG_CMODE_USENOREVWORDS
FELANG_CMODE_NONE
FELANG_CMODE_PLAURALCLAUSE
FELANG_CMODE_SINGLECONVERT
FELANG_CMODE_AUTOMATIC
FELANG_CMODE_PHRASEPREDICT
FELANG_CMODE_CONVERSATION
FELANG_CMODE_NAME
FELANG_CMODE_NOINVISIBLECHAR
INT cwchInput (IN) Number of characters of ptchInput
WCHAR *pwchInput (IN) Original input characters to be converted by morphology engine
NULL means to get the next entry for the previously given string, with the next rank
This must be a UNICODE string
The order in which next entries are returned is defined by an implementation
DWORD *pfCInfo (IN) Means the information for each column (ptchInput[x]); pfCInfo[x] (column info) can be a combination of the flags below:

FELANG_CLMN_WBREAK
FELANG_CLMN_NOWBREAK
FELANG_CLMN_PBREAK
FELANG_CLMN_NOPBREAK
FELANG_CLMN_FIXR
FELANG_CLMN_FIXD
NULL can be used, which means all pfCInfo[] are FALSE (no request from client)
MORRSLT **ppResult (OUT) Address of an MORRSLT structure that receives morphology result data
GetJMorphResult() allocates memory (using the OLE task allocator) for the returned data, and sets the pResult to point to the memory
The application must free the memory pointed to by pResult, by using the CoTaskMemFree function
Return Values
HRESULT S_OK:
More candidates exist (if you call this function with ptchInput NULL, it will get the next best candidate for the previous ptchInput)
S_FALSE: Fails to create result
E_NOCAND: No more candidates
E_LARGEINPUT: Too large input
Fails to create result.

dwRequest—Request for Conversion

FELANG_REQ_CONV—to get a composition string from a string with Japanese phonetic characters. This request requires that the input string is a string with Japanese phonetic characters that doesn't have any ideographic character.

FELANG_REQ_RECONV—to get a composition string from a composition string. This request is to get a re-conversion result from a conversion result.

FELANG_REQ_REV—to get a string with Japanese phonetic characters from a composition string. On this request, the contents of WDD[n].wDispPos and WDD[n].wReadPos are exchanged.

MORRSLT.pwchRead is used as the source of reverse conversion.

pfCInfo—information relating to an input in each column.

Any combination of the flags below can be set for each column of an input string:

FELANG_CLMN_WBREAK PwchInput[x] is forced to be the start of the word in analysis.
FELANG_CLMN_NOWBREAK The result must not be divided here when IFELanguage makes a word. FELANG_CLMN_NOWBREAK always includes FELANG_CLMN_NOPBREAK.
FELANG_CLMN_PBREAK PwchInput[x] is forced to be the start of a phrase in analysis. FELANG_CLMN_PBREAK always includes FELANG_CLMN_WBREAK.
FELANG_CLMN_NOPBREAK The result must not be divided here when IFELanguage makes a PHRASE.
FELANG_CLMN_FIXR PwchInput[x] is used as a Japanese phonetic character in a conversion result on a FELANG_REQ_REV request. That is, the Japanese phonetic character of the conversion result is fixed to be ptchInput[x].
FELANG_CLMN_FIXD PwchInput[x] is used as a display character in a conversion result on a FELANG_REQ_CONV request. That is, the display character of the conversion result is fixed to be ptchInput[x].

dwCMode—Conversion Mode

  • Any combination of the values below is possible. This determines the conversion mode.
  • FELANG_CMODE_MONORUBY: Makes a string with Japanese phonetic characters for mono-ruby wherever possible. If this flag is set, the returned result is put at paMonoBubyPos. This mode is valid when FELANG_REQ_REV is specified.
  • FELANG_CMODE_NOPRUNING: No pruning (filtering) in morphology analysis.
  • On input of , it may return, for example, ( is the body part of ). This result is impossible grammatically, but with FELANG_CMODE_NOPRUNING, one can obtain this candidate.
  • FELANG_CMODE_KATAKANAOUT: Output is in Katakana (Japanese phonetic) characters when IFELANG_REQ_REV is specified.
  • FELANG_CMODE_HIRAGANAOUT: Output is in Hirakana (Japanese phonetic) characters when IFELANG_REQ_REV is specified.
  • FELANG_CMODE_ROMAN: Output is in Roman characters when IFELANG_REQ_REV is specified.
  • FELANG_CMODE_HALFWIDTHOUT: Output is in half-width characters.
  • FELANG_CMODE_FULLWIDTHOUT: Output is in full-width characters (default).
  • FELANG_CMODE_BOPOMOFO: Output is in Bopomofo (Taiwan phonetic) characters when IFELANG_REQ_REV is specified.
  • FELANG_CMODE_HANGUL: Output is in Hangul (Korean phonetic) characters when IFELANG_REQ_REV is specified.
  • FELANG_CMODE_PINYIN: Output is in Pinyin (Chinese phonetic) characters when IFELANG_REQ_REV is specified.
  • FELANG_CMODE_PRECONV: Performs the following conversion before the actual conversion. These are implementation defined:
  • ROMAN to phonetic characters, for example: [a] to []
    1. The auto collect before the conversion, for example: [] to [-]
    2. The conversion of the punctuation mark and the brackets, for example: [] to [,]
  • FELANG_CMODE_RADICAL: Japanese phonetic characters are returned in radical (CHN).
  • FELANG_CMODE_UNKNOWNREADING: Japanese phonetic characters are returned in unknown format. (CHN)
  • FELANG_CMODE_MERGECAND: The result strings (candidates) are merged when the strings are the same.
  • FELANG_CMODE_ROMAN (JPN): Enables the romaji-kana conversion.
  • FELANG_CMODE_BESTFIRST: Forces simple conversion to get better performance time rather than conversion accuracy.
  • FELANG_CMODE_USENOREVWORDS(JPN): Optional conversion using additional words (for example, reverse conversion from address to ZIP code)
  • FELANG_CMODE_NONE: Corresponds to the analysis in IME_SMODE_NONE
  • FELANG_CMODE_PLAURALCLAUSE: Corresponds to the analysis in IME_SMODE_ PLAURALCLAUSE
  • FELANG_CMODE_SINGLECONVERT: Corresponds to the analysis in IME_SMODE_SINGLECONVERT
  • FELANG_CMODE_AUTOMATIC: Corresponds to the analysis in IME_SMODE_AUTOMATIC
  • FELANG_CMODE_PHRASEPREDICT: Corresponds to the analysis in IME_SMODE_PHRASEPREDICT
  • FELANG_CMODE_CONVERSATION: Corresponds to the analysis in IME_SMODE_CONVERSATION
  • FELANG_CMODE_NAME(JPN): Name mode (same as FELANG_CMODE_PLAURALCLAUSE)
  • FELANG_CMODE_NOINVISIBLECHAR: When specified, remove invisible characters in output string. This flag is usually used for display purpose. Both CHN and TWN IME will return some spaces and invisible characters. (For example, First tone mark, U+02c9, in Bopomofo.) For these, however, invisible characters should be removed upon displaying.

REMARKS   This function should not fail on any input (except memory full, and so on). In the worst case, this function returns a result with an unknown word.

HRESULT IFELanguage::GetConversionModeCaps

This method is used to get conversion mode capability of the IFELanguage. This function returns the FELANG_CMODE_xxx's supported by the object. *pdwCaps is a combination of supported FELANG_CMODE_xxx's.

Parameter Description
DWORD *pdwCaps (OUT) *pdwCaps is a bit field that contains FELANG_CMODE_xxx.
Return Values
HRESULT S_OK
Successfully terminated
S_FALSE
Fails to create result

HRESULT IFELanguage::GetPhonetic

This method is a thin wrapper function of GetJMorphResult with FELANG_REQ_REV. It simply converts the input string (which usually contains Kanji characters) to phonetic symbols. This function is designed to be called by Microsoft Visual Basic® (Visual Basic for Applications) through TLB.

Parameter Description
BSTR string (IN) A string of Kanji characters to be converted to phonetic symbols
LONG start (IN) The number of characters from which IFELanguage begins conversion; the first character is 1 (not 0)
LONG length (IN) The length of characters to be converted; if this value is (-1), it means that the entire length from the 'start' column is selected
BSTR *phonetic (OUT) The result string; this string is allocated by SysAllocStringLen and must be freed by clients
Return Values
HRESULT S_OK: Successfully terminated
S_FALSE: Fails to create a result