POBox API定義 Up$Date: 2001/09/30 04:10:56 $ $Revision: 1.15 $

2000/7ごろの古い資料

API実装例 | 初期化/終了API | 辞書管理API | 単語管理API | 検索実行API | API使用例

API仕様の目標

- 携帯電話、携帯端末、PCなど各種の機器で共通に使えること
  - 操作インタフェースが異なる場合でもAPIを共通化するため、 キー入力や表示のAPIは用意しない
- 異なる形式の辞書を使う場合でもAPIを共通とすること
  - 辞書はROMかもしれないしサーバかもしれないが、APIからは 同じように見えるようにすること
- かな漢字変換システムとの融合も考慮する
  - かな漢字変換システムのON/OFFも制御できた方がよいかも
- 複数ユーザの場合を考慮する
- 状況により動的に辞書を切り替えられるようにする
  - アプリとコンテクストにより名簿辞書/地名辞書などを使う
  - 突然辞書サーバが増えた場合や、辞書のメモリースティックを 差した場合などへの対応
- 言語切換えAPIは無い。辞書切換えAPIで対応する。
- * ハフマン圧縮や検索に使えるようにする
- * PADなどで普通の辞書と共通に使えるようにする

API実装例

以下のような実装例があります。

- UNIX上の実装例 (辞書ファイルを使用)
- 携帯電話/InfoCarryの実装例 (ROM辞書を使用)

    #ifndef _POBOXLIB_H_
    #define _POBOXLIB_H_

    typedef int POBOX_INT;

初期化/終了API

    // 初期化
    POBOX_INT pobox_init(void);
返り値 | 初期化に成功すると0を返す。エラーの場合-1を返す。
備考 | -

    // 終了
    void pobox_finish(void);
返り値 | なし
備考 | -

辞書管理API

辞書を変更しないシステムではは本節のAPIを使用する必要はありません。

POBoxでは環境により各種の辞書を使い分ける必要があります。 たとえば携帯端末を持ち歩いて使う場合、

- システム標準辞書 (基本単語)
- 位置依存辞書 (現在地近くの地名)
- アプリケーション依存辞書 (スケジューラでは「会議」など)
- ユーザ依存辞書 (知人の名前など)

といった複数の辞書を使うと便利でしょう。 環境によって辞書を切換えたり単語を登録/学習したりするための APIをここで定義します。

ある場所で、ユーザがふたつのアプリケーションを切換えて 使用している場合を考えます。 この場合、 あらゆる場所とユーザで共通な基本基本辞書・ 場所に依存する地名辞書・ アプリケーション依存の固定辞書・ 登録可能なユーザ辞書・ ユーザとアプリケーションの両方に依存するアプリケーション辞書などを 下図のように階層的に使用すればよいでしょう。
たとえば、アプリケーション1使用時に ユーザが `pobox_search()` により候補単語を検索した場合、 システムは辞書1, 3, 4, 6, 7を順番に検索して 候補単語のリストを取得します。 その後、検索された候補のひとつを `pobox_select()` でユーザが選択した場合、 選んだ単語を辞書1, 3で学習させることができます。

> AP1使用時
> AP2使用時

> 1. AP1辞書 (学習/ユーザとAP依存)
> 2. AP2辞書 (学習/ユーザとAP依存)

> 3. ユーザ辞書 (学習/ユーザ依存)

> 4. AP1辞書 (固定/AP依存)
> 5. AP2辞書 (固定/AP依存)

> 6. 地名辞書 (固定/位置依存)

> 7. 基本辞書 (固定/共通)

辞書はROMかもしれませんし、ファイルかもしれませんし、 無線ネットワーク経由のテンポラリなものかもしれませんが、 POBox APIではこれらを区別しません。

`pobox_select()` を呼ぶと、 選択された単語は辞書の先頭に移動します。

    typedef enum {
    	POBOXDICT_STANDARD,	// 標準辞書
    	POBOXDICT_LOCATION,	// 地名辞書
    	POBOXDICT_PERSONNAME	// 人名辞書
    } POBoxDictKind;

    typedef enum {
    	POBOXDICT_TEXT,		// テキスト型式(非圧縮/交換型式)
    	POBOXDICT_SARY,		// SARY型式
    	POBOXDICT_LOOKUP,	// トライ型式
    	POBOXDICT_PDB,		// PalmのPDB型式
    	POBOXDICT_PDB_VFS	// PalmのVFS(MSなど)のPDB型式
    } POBoxDictType;

    typedef struct {
    	char *name;
    	POBoxDictKind kind;
    	POBoxDictType type;
    	int readonly;
    	int backup;		// Palm用: HotSyncでBackupするかどうか
    } POBoxDict;

    // 使用可能な辞書リストの取得
    POBOX_INT pobox_getdictlist(POBoxDict *dictlist[], POBOX_INT limit);
引数 | diclist | 辞書構造体へのポインタを格納する配列
limit | 最大辞書数
返り値 | 使用可能な辞書の数を返す。 使用可能な辞書がない場合は0を返す。

    // 使用する辞書の指定
    POBOX_INT pobox_usedict(POBoxDict *dict);
引数 | dict | 使用する辞書構造体へのポインタ
返り値 | 辞書使用開始に成功した場合は0を返し、失敗した場合は-1を返す。
備考 | `dict`には `pobox_getdictlist()`で得られた辞書のひとつを指定する。 引数にNULLを指定するとデフォルトの辞書を中止する。 `pobox_usedict()`を複数回呼び出すと 複数の辞書を検索対象とすることができる。 この場合、最後に指定した辞書が最初の検索対象となる。

    // 辞書の属性を設定
    POBOX_INT pobox_setattr(POBoxDict *dict, POBoxDict *newdict);
引数 | dict | 使用可能な辞書
newdict | 設定したい属性をもつ辞書構造体へのポインタ
返り値 | 属性設定に成功すると0を返し、失敗すると-1を返す。
備考 | 辞書の種別、読み出し専用属性などを設定する。

単語管理API

    // 辞書に単語を登録
    POBOX_INT pobox_regword(POBoxDict *dict, unsigned char *word,
            unsigned char *pattern, unsigned char *context);
引数 | dict | 単語を登録する辞書
word | 登録単語
pattern | 単語の検索パタン
context | 例文辞書のコンテクスト。NULLの場合コンテクストは登録しない。
返り値 | 単語登録に成功した場合は0を返し、失敗した場合は-1を返す。

    // 辞書から単語を削除
    POBOX_INT pobox_delword(POBoxDict *dict, unsigned char *word,
            unsigned char *pattern);
引数 | dict | 単語を削除する辞書
word | 削除単語
pattern | 単語の削除パタン
返り値 | 単語削除に成功した場合は0を返し、失敗した場合は-1を返す。

以下は携帯電話用に追加されたAPI

    // 登録単語数の取得
    POBOX_INT pobox_entries(POBoxDict *dict);
引数 | dict | 対象となる辞書
| 返り値 | 辞書に登録されている単語数を返す。 辞書が存在しない場合は-1を返す。

    // n番目の登録単語の取得
    POBOX_INT pobox_getent(POBoxDict *dict, POBOX_INT nth,
    	unsigned char *word, unsigned char *pattern);
引数 | dict | 対象となる辞書
nth | n番目
word | 単語バッファ
pattern | パタンバッファ
返り値 | 単語取得に成功すると0を返し、失敗すると-1を返す。
備考 | -

    // n番目のエントリに単語を登録
    POBOX_INT pobox_regent(POBoxDict *dict, POBOX_INT nth,
    	unsigned char *word, unsigned char *pattern, unsigned char *context);
引数 | dict | 対象となる辞書
nth | n番目
word | 登録する単語
pattern | 単語の検索パタン
context | 例文辞書のコンテクスト。NULLの場合コンテクストは登録しない。
返り値 | 単語登録に成功すると0を返し、失敗すると-1を返す。

    // n番目の登録単語の削除
    POBOX_INT pobox_delent(POBoxDict *dict, POBOX_INT nth);
引数 | dict | 対象となる辞書
nth | n番目
返り値 | 単語削除に成功すると0を返し、失敗すると-1を返す。

検索API

    // 辞書検索の実行
    POBOX_INT pobox_search(unsigned char *pattern);
引数 | pattern | 検索パタン
返り値 | 検索にマッチした候補数(>=0)を返す。エラーの場合-1を返す。
備考 | パタンには辞書に応じてASCII文字 / 平仮名 / 漢字を指定する。 (e.g. "kanji", "かんじ") パタンに平仮名を使う場合は 平仮名文字列をEUC表現したものの下位バイトを指定する。 (e.g. "かんじ"で検索を行なう場合は patternに{0xab, 0xf3, 0xb8, 0x00}を指定する) パタンには文字クラスを使用可能。(e.g. "k[aiueo]", "[かしちせこ]") 濁音などを無視して検索したい場合は文字クラスを使って指定する。 (e.g. "[かが]ん[しじ]") ptnが空文字列またはNULLの場合は辞書中の全単語数を返す。 曖昧検索を行なうか、完全一致/前方一致の切換えなどは pobox_searchmode()で指定する。

    // インデクスを指定して検索結果の単語を得る
    POBOX_INT pobox_getcands(unsigned char **cands,
            unsigned char **patterns, POBOX_INT first, POBOX_INT n);
引数 | cands | 候補文字列のリスト
patterns | 候補文字列に対応する読みパタンのリスト
first | 候補の最初のインデクス
n | 要求する候補数
返り値 | 得られた候補数(>=0)を返す。エラーの場合-1を返す。
備考 | cands[first], cands[first+1], ... cansd[first+(n-1)]に 候補文字列が格納される。 cands[]に得られた各候補の読みパタンが patterns[first],...に格納される。 先頭10個の候補を取得する場合は pobox_getcands(cands,patterns,0,10); となる。

    // 検索モードの指定
    void pobox_searchmode(POBOX_INT mode);
引数 | mode | 検索モード
返り値 | なし
備考 | 検索モードは、以下の値のORを指定する。 POBOX_EXACT - (先頭マッチでなく)完全マッチを指定 POBOX_APPROXIMATE - 動的曖昧検索を指定
    #define POBOX_EXACT 1
    #define POBOX_APPROXIMATE 2

    // コンテクストの指定
    void pobox_context(unsigned char *context, POBOX_INT contextlen);
引数 | context | 入力コンテクスト
contextlen | コンテクスト長
返り値 | なし
備考 | 予測に必要な入力位置直前のコンテクストを通知する。 e.g. pobox_context("よろしく",8);

    // 選択単語の指定 / 単語学習処理
    void pobox_select(POBOX_INT selindex);
引数 | selindex | 選択した候補のインデクス
返り値 | なし
備考 | 直前に呼んだ`pobox_getcands()`のいくつめの候補を ユーザが選択したかを指定する。 辞書の学習に使用する

検索API使用例

「よろしく」という文字列の直後にカーソルを移動して 入力を続ける場合の例

    // カーソル移動操作後。
    // context = "よろしく"
    pobox_context(context,8);
    (ユーザの入力から検索パタンpatを計算する。
    たとえばユーザがローマ字入力モードで"c"を入力した場合、
    ca/ci/cha/chi/cu/ce/co などの可能性があるので
    patを"[かしちくせこ]"などとする)
    n = pobox_search(pat); // 候補単語を検索
    n = pobox_getcands(cands,patterns,0,n); // 検索された単語を取得
    for(i=0;i < n;i++){
        (i番目の候補cands[i]を表示)
    }
    (ユーザがk番目候補を選ぶ)
    pobox_select(k); // k番目の候補を学習
    ...

    #endif