Palm Programmer's Laboratory
Palm OS Programmer's API Reference/44
この章の索引
44 オーバレイ マネージャ
この章では、ヘッダファイル OverlayMgr.h で定義されているオーバレイ マネージャ API について説明します。以下の内容について説明します。
オーバレイ マネージャについての更なる情報は、Palm OS Programmer's Companion, vol. I の「リソースローカライズのためのオーバレイの使用」を参照してください。
オーバレイ マネージャ データ構造体 ^TOP^
OmLocaleType 構造体 ^TOP^
目的
OmLocaleType 構造体はロケールを指定します。
Prototype
typedef struct {
UInt16 language;
UInt16 country;
} OmLocaleType;
フィールド
- language
- ロケールの中で話される言語。この値は、LanguageType 定数の 1 つです。
- country
- その言語が話されているカントリーまたは地域。この値は、CountryType 定数の 1 つです。
互換性
4.0 New Feature Set が満たされる場合に、LmLocaleType が OmLocaleType を置き換えます。下位互換性のために、OmLocaleType は LmLocaleType へマッピングされます。
オーバレイ マネージャ定数 ^TOP^
| 定数 | 値 | 説明 |
|---|---|---|
| omOverlayRscType | 'ovly' | ベース データベースとオーバレイ データベースの両方の中で保持されているオーバレイ リソースの記号的な名前（原文: symbolic name）。 |
| omOverlayRscID | 1000 | ベース データベースとオーバレイ データベースの両方の中で保持されているオーバレイ リソースのリソース ID。 |
| omFtrCreator | 'ovly' | omFtrShowErrorsFlag 機能のために使用される作成者値。 |
| omFtrDefaultLocale | 1 | ROM に保存されているデフォルトのロケールを指定する機能。デフォルトのロケールは、システムが「分割された」データベース（オーバレイを要求するデータベース）をオープンしようと試みて、かつ、現在のロケールに一致するオーバレイが見つからなかったというケースで、使用されます。このケースでは、システムはデフォルトのロケールに一致するオーバレイを探します。FtrGet()|Palm OS Programmer's API Reference/34 と FtrSet()|Palm OS Programmer's API Reference/34 を使用してこの値を取得、セットします。 |
| omFtrShowErrorsFlag | 2 | オーバレイ マネージャによって表示されるエラー メッセージの数を制御する機能。この機能が true にセットされている場合、オーバレイ マネージャは、オーバレイをそのベース データベースに対して検証しているときに、さらに数個のエラー メッセージを表示するかもしれません。この機能は、エラー チェック レベルが最高にセットされている（デバッグ ROM では一般にそのようになっていて、リリース ROM ではそのようになっていません）場合にのみ、効果を発揮します。FtrGet()|Palm OS Programmer's API Reference/34 と FtrSet()|Palm OS Programmer's API Reference/34 を使用してこの値を取得、セットします。 |
オーバレイ マネージャ関数 ^TOP^
OmGetCurrentLocale 関数 ^TOP^
目的
現在のロケールを返します。
宣言されている場所
OverlayMgr.h
Prototype
void OmGetCurrentLocale( LmLocaleType *currentLocale )
パラメータ
- ← currentLocale
- 現在のロケールを指定する LmLocaleType 構造体へのポインタ。
返り値
返り値はありません。
コメント
この関数は現在のロケールを返します。現在のロケールは、リソース データベースのためにどのオーバレイが使用されるかを制御します。例えば、あるアプリケーションとそれに関連付けされた 2 つのオーバレイをインストールしたとします。1 つのオーバレイは US English のためで、もう 1 つは British English のためのものです。このケースでは、この関数によって返されるロケールの中で指定されているカントリーが cUnitedKingdom である場合、アプリケーションのために British English オーバレイが使用されます。返されるカントリーが cUnitedStates である場合、US English オーバレイが使用されます。
互換性
3.5 New Feature Set が満たされる場合にのみ、実装されます。それより前のバージョンの Palm OS で実行させることを意図したコードの中でこの関数を使用するには、PalmOSGlue ライブラリにリンクをはり、OmGlueGetCurrentLocale を呼び出します。更なる情報は、第 80 章 「PalmOSGlue ライブラリ」? を参照してください。
参照
OmGetIndexedLocale 関数 ^TOP^
目的
インデックスで指定されたシステム ロケールを返します。
宣言されている場所
OverlayMgr.h
Prototype
Err OmGetIndexedLocale ( UInt16 localeIndex, LmLocaleType *theLocale )
パラメータ
- → localeIndex
- 返されるロケールの 0-ベース インデックス
- ← theLocale
- インデックスで指定されたロケールを指定する LmLocaleType へのポインタ
返り値
成功時には true を返します。インデックスが領域から外れている場合は、omErrInvalidLocaleIndex を返します。
コメント
OmGetIndexedLocale は、システム リソースのためにインストールされたシステム オーバレイがいくつあるのか調べるためのループの中で、使用されます。
4.0 New Feature Set が満たされる場合、この関数の代わりに OmGetNextSystemLocale() を使用します。OmGetIndexdLocale は多くの有効なシステム ロケールを保持している ROM 上では遅くなる可能性があります。
互換性
3.5 New Feature Set が満たされる場合にのみ、実装されます。しかしながら、Palm OS Cobalt Feature Set が満たされる場合、この関数は実装されません。
Palm OS 3.5 では、この関数は RAM の中に保存されているシステム オーバレイを返しません。この関数の Palm OS 4.0 バージョンは RAM の中のシステム オーバレイを返します。
参照
OmGetSystemLocale(), OmGetNextSystemLocale()
OmGetNextSystemLocale 関数 ^TOP^
目的
システム ロケールを返します。
宣言されている場所
OverlayMgr.h
Prototype
Err OmGetNextSystemLocale ( Boolean iNewSearch, OmSearchStateType *ioStateInfoP, LmLocaleType *oLocaleP )
パラメータ
- → iNewSearch
- この関数呼び出しが新しい検索を開始する場合は true、この関数呼び出しが検索の続きである場合は、false
- ←→ ioStateInfoP
- iNewSearch が false の場合、これは前回の検索で使用されたのと同じデータを指さなくてはなりません。
- ← oLocaleP
- 見つかったロケール
返り値
エラーが無い場合、errNone を返します。一致するものが見つからなかった場合は、omErrNoNextSystemLocale を返します。
コメント
この関数を続けて呼び出すことにより、システム リソースのためにインストールされているシステム オーバレイがいくつあるのか調べることができます。見つかった各システム オーバレイは個々の有効なシステム ロケールを決定します。この関数によって返されるいずれかのロケールを、システム ロケールを変更するために、OmSetSystemLocale() へ送ることができます。
検索を開始するには、iNewSearch に true を渡します。OmSearchStateType 構造体を割り当て、ioStateInfoP としてそれのアドレスを渡します。OmGetNextSystemLocale は ioStateInfoP の中にプライベート情報を保存し、検索が継続される場合はそれを使用します。
前回の検索が終了したところで検索を継続するには、iNewSearch に false を渡し、前回のこの関数呼び出しで使用したのと同じ ioStateInfoP を渡します。
呼び出しが続けられた場合、この関数は結果的に ROM または RAM の中にあるすべてのシステム オーバレイを返します。
互換性
4.0 New Feature Set が満たされる場合にのみ、実装されます。しかしながら、Palm OS Cobalt Feature Set が満たされる場合、この関数は実装されません。
OmGetRoutineAddress 関数 ^TOP^
目的
オーバレイ マネージャ関数のアドレスを返します。
宣言されている場所
OverlayMgr.h
Prototype
void *OmGetRoutineAddress ( OmSelector inSelector )
パラメータ
- → inSelector
- OverlayMgr.h の中で定義されているルーチン セレクタの 1 つ
返り値
対応する関数のアドレスを返します。無効なルーチン セレクタが渡された場合は、NULL を返します。
コメント
通常、この関数を、デバイス上にあるオーバレイ マネージャ関数が存在するかどうか調べるために、使用します。Palm OS の将来のリリースは新しい関数を追加するため、前のバージョンのオーバレイ マネージャを持つ古いデバイスは、それらの新しい関数を実装していないかもしれません。OmGetRoutineAddress が NULL を返す場合、その関数は使用できません。
互換性
3.5 New Feature Set が満たされる場合にのみ、実装されます。
参照
IntlGetRoutineAddress()|Palm OS Programmer's API Reference/60, SysGetTrapAddress()|Palm OS Programmer's API Reference/54
OmGetSystemLocale 関数 ^TOP^
目的
システム ロケールを返します。
宣言されている場所
OverlayMgr.h
Prototype
void OmGetSystemLocale( LmLocaleType *systemLocale )
パラメータ
- ← systemLocale
- システム ロケールを指定する LmLocaleType 構造体へのポインタ
返り値
返り値はありません。
コメント
通常、この関数を使用することはありません。代わりに、どのオーバレイが使用されるのかを決定するロケールを返す OmGetCurrentLocale() を使用します。
システム ロケールはストレージ ヒープ ヘッダの中に保存され、ソフト リセットがかかっても維持されます。デバイスがリセットされるとき、システム ロケールは現在のロケールをセットするために使用されます。
互換性
3.5 New Feature Set が満たされる場合にのみ、実装されます。それより前のバージョンの Palm OS で実行させることを意図したコードの中でこの関数を使用するには、PalmOSGlue ライブラリにリンクをはり、OmGlueGetSystemLocale を呼び出します。更なる情報は、第 80 章 「PalmOSGlue ライブラリ」? を参照してください。
参照
OmGetCurrentLocale(), LmGlueGetSystemLocale()|Palm OS Programmer's API Reference/80
OmLocaleToOverlayDBName 関数 ^TOP^
目的
与えられたベース データベース名とロケールから、オーバレイ データベースの名前を返します。
宣言されている場所
OverlayMgr.h
Prototype
Err OmLocaleToOverlayDBName( const Char *baseDBName, const LmLocaleType *targetLocale, Char *overlayDBName )
パラメータ
- → baseDBName
- オーバレイに関連付けられたベース リソース データベースの名前
- → targetLocale
- このオーバレイが適用されるロケール。LmLocaleType を参照してください。現在のロケールを使用するためには NULL を渡します。
- ← overlayDBName
- ベース データベース名とターゲット ロケールを与えられたオーバレイ データベース。このバッファは少なくとも dmDBNameLength バイトなけらばなりません。
返り値
成功時には errNone を返します。targetLocale パラメータが無効の場合は、omErrUnknownLocale を返します。
コメント
適切なオーバレイ データベース名は現在のところ:
baseDBName_llCC
ここで:
- baseDBName
- 渡したベース データベースの名前
- ll
- 言語を指定する 2 文字のコード
- CC
- カントリーを指定する 2 文字のコード
ベース データベース名は、この接尾辞のために必要があれば、切り詰められます。
例えば、ベース データベース "MemoPad" は、US English のための "MemoPad_enUS" という名前のオーバレイを持つかもしれません。
互換性
3.5 New Feature Set が満たされる場合にのみ、実装されます。
参照
OmOverlayDBNameToLocale 関数 ^TOP^
目的
名前が与えられたオーバレイ データベースのロケールを返します。
宣言されている場所
OverlayMgr.h
Prototype
Err OmOverlayDBNameToLocale( const Char *overlayDBName, LmLocaleType *overlayLocale )
パラメータ
- → overlayDBName
- オーバレイ データベースの名前
- ← overlayLocale
- オーバレイのロケールを指定する LmLocaleType 構造体へのポインタ
返り値
成功時には errNone を返します。文字列 overlayDBName がロケール接尾辞を持つにはもはや十分でない場合は、omErrBadOverlayDBName を返し、また、ロケールを決定できない場合は、omErrUnknownLocale を返します。
参照
OmSetSystemLocale 関数 ^TOP^
目的
システム ロケールをセットし、デバイスをリセットします。
宣言されている場所
OverlayMgr.h
Prototype
Err OmSetSystemLocale( const LmLocaleType *systemLocale )
パラメータ
- → systemLocale
- システムを切り替えるロケールを指定する LmLocaleType 構造体
返り値
成功時には errNone を返します。エラーが起きた場合は、以下の 1 つを返します。
- omErrUnknownLocale
- systemLocale のためのシステム オーバレイがありません。
- omErrInvalidLocale
- systemLocale のためのシステム オーバレイは見つかりましたが、無効です。
- dmErrInvalidParam
- オーバレイをオープンする間にメモリ エラーが起こりました。
- dmErrDatabaseOpen
- システム オーバレイはすでにオープンされています。
コメント
この関数はシステム ロケールを指定されたロケール（もしそれがあれば）に変更します。最初に要求されたロケールのためのシステム ロケールが存在するかどうかを決定し、ベース システム データベースを照合します。そうであれば、ストレージ ヒープ ヘッダの中に保存されるシステム ロケール情報を更新し、デバイスをリセットします。デバイスのリセット後は、現在のロケールはそのシステム ロケールにセットされています。
Palm デバイスは ROM の中にハード-コードされたデフォルトのロケールを持ちます。このロケールは、ハード リセット後、または、ストレージ ヒープ ヘッダが無効である場合いつでも、システム ロケールをセットするために使用されます。ストレージ ヒープ ヘッダは、通常、最初にデバイスが ON になったときにのみ、無効です。
互換性
3.5 New Feature Set が満たされる場合にのみ、実装されます。しかしながら、Palm OS Cobalt Feature Set が満たされる場合、この関数は実装されません。
Palm OS 3.5 では、この関数は RAM の中に位置するシステム オーバレイを切り替えません。この関数の Palm OS 4.0 バージョンは RAM の中に位置するシステム オーバレイを返します。
参照
