This chapter describes the overlay manager API as declared in the header file OverlayMgr.h
. It discusses the following topics:
For more information on the overlay manager, see "Using Overlays to Localize Resources" of the Palm OS Programmer's Companion, vol. I.
Overlay Manager Data Structures
OmLocaleType Struct
Purpose
The OmLocaleType
struct specifies a locale.
Prototype
typedef struct { UInt16 language; UInt16 country; } OmLocaleType;
Fields
-
language
- The language spoken in the locale. This value is one of the
LanguageType
constants. -
country
- The country or region where the language is spoken. This value is one of the
CountryType
constants.
Compatibility
If Palm OS® 4.0 New Feature Set is present, the LmLocaleType
replaces OmLocaleType
. For backward compatibility, OmLocaleType
is mapped to LmLocaleType
.
Overlay Manager Constants
Symbolic name of an overlay resource that is contained in both the base database and the overlay database. |
||
Resource ID of the overlay resource in both the base database and the overlay database. |
||
Feature that specifies the default locale stored in the ROM. The default locale is used in cases where the system is attempting to open a "stripped" database (one that requires an overlay) and an overlay matching the current locale cannot be found. In this case, the system then looks for an overlay matching the default locale. Use |
||
Feature that controls the number of error messages displayed by the overlay manager. If this feature is set to |
Overlay Manager Functions
OmGetCurrentLocale Function
Purpose
Declared In
OverlayMgr.h
Prototype
void OmGetCurrentLocale( LmLocaleType *currentLocale )
Parameters
-
←
currentLocale
- Points to an
LmLocaleType
struct that identifies the current locale.
Returns
Comments
This function returns the current locale. The current locale controls which overlays are used for resource databases. For example, suppose you have one application and two associated overlays installed, one for US English and one for British English. In this case, if the country specified in the locale returned by this function is cUnitedKingdom
, the British English overlay is used for the application. If the country returned is cUnitedStates
, the US English overlay is used.
Compatibility
Implemented only if 3.5 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call OmGlueGetCurrentLocale. For more information, see Chapter 80, "PalmOSGlue Library."
See Also
OmGetIndexedLocale Function
Purpose
Return a system locale by index.
Declared In
OverlayMgr.h
Prototype
Err OmGetIndexedLocale ( UInt16 localeIndex, LmLocaleType *theLocale )
Parameters
-
→
localeIndex
- Zero-based index of the locale to return.
-
←
theLocale
- Points to an
LmLocaleType
struct that identifies the locale at that index.
Returns
Returns errNone
upon success, or omErrInvalidLocaleIndex
if the index is out of bounds.
Comments
OmGetIndexedLocale
is used in a loop to discover how many system overlays are installed for system resources.
If the 4.0 New Feature Set is present, use OmGetNextSystemLocale()
instead of this function. OmGetIndexedLocale
can be slow on ROMs that contain many valid system locales.
Compatibility
Implemented only if 3.5 New Feature Set is present. If Palm OS Cobalt Feature Set is present, however, this function is unimplemented.
In Palm OS 3.5, this function would not return a system overlay that was located in RAM. The Palm OS 4.0 version of this function does return system overlays located in RAM.
See Also
OmGetSystemLocale()
, OmGetNextSystemLocale()
OmGetNextSystemLocale Function
Purpose
Declared In
OverlayMgr.h
Prototype
Err OmGetNextSystemLocale ( Boolean iNewSearch, OmSearchStateType *ioStateInfoP, LmLocaleType *oLocaleP )
Parameters
-
→
iNewSearch
-
true
if this function call is starting a new search, orfalse
if this function call is a continuation of a search. -
↔
ioStateInfoP
- If
iNewSearch
isfalse
, this must point to the same data used for the previous invocation. -
←
oLocaleP
- The found locale.
Returns
Returns errNone
if no error or omErrNoNextSystemLocale
if no matches were found.
Comments
You can call this function successively to discover how many system overlays are installed for system resources. Each system overlay found determines a separate valid system locale. Any locale returned by this function can be sent to OmSetSystemLocale()
to change the system locale.
To start the search, pass true
for iNewSearch
. Allocate an OmSearchStateType
structure and pass its address as ioStateInfoP
. OmGetNextSystemLocale
stores private information in ioStateInfoP
and uses it if the search is continued.
To continue a search where the previous one left off, pass false
for iNewSearch
and pass the same ioStateInfoP
that you used during the previous call to this function.
When called successively, this function eventually returns all system overlays that are in ROM or RAM.
Compatibility
Implemented only if 4.0 New Feature Set is present. If Palm OS Cobalt Feature Set is present, however, this function is unimplemented.
OmGetRoutineAddress Function
Purpose
Return the address of an overlay manager function.
Declared In
OverlayMgr.h
Prototype
void *OmGetRoutineAddress ( OmSelector inSelector )
Parameters
Returns
Returns the address of the corresponding function. Returns NULL
if an invalid routine selector is passed.
Comments
You typically use this function to determine whether an overlay manager function exists on the device. As future releases of Palm OS add new functions, older devices with earlier versions of the overlay manager will not implement these newer functions. If OmGetRoutineAddress
returns NULL
, the function is unavailable.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
IntlGetRoutineAddress()
, SysGetTrapAddress()
OmGetSystemLocale Function
Purpose
Declared In
OverlayMgr.h
Prototype
void OmGetSystemLocale( LmLocaleType *systemLocale )
Parameters
-
←
systemLocale
- Points to an
LmLocaleType
struct that identifies the system locale.
Returns
Comments
You typically don't use this function. Instead, use OmGetCurrentLocale()
, which returns the locale that determines which overlays are used.
The system locale is saved in the storage heap header and persists across soft resets. When the device is reset, the system locale is used to set the current locale.
Compatibility
Implemented only if 3.5 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call OmGlueGetSystemLocale. For more information, see Chapter 80, "PalmOSGlue Library."
See Also
OmGetCurrentLocale()
, LmGlueGetSystemLocale()
OmLocaleToOverlayDBName Function
Purpose
Return the overlay database's name given the base database name and the locale.
Declared In
OverlayMgr.h
Prototype
Err OmLocaleToOverlayDBName( const Char *baseDBName, const LmLocaleType *targetLocale, Char *overlayDBName )
Parameters
-
→
baseDBName
- The name of the base resource database associated with the overlay.
-
→
targetLocale
- The locale to which this overlay applies. See
LmLocaleType
. PassNULL
to use the current locale. -
←
overlayDBName
- The overlay database name given the base database name and the target locale. This buffer must be at least
dmDBNameLength
bytes.
Returns
Returns errNone
upon success, or omErrUnknownLocale
if the targetLocale
parameter is invalid.
Comments
The appropriate overlay database name is currently:
baseDBName_llCC
-
baseDBName
- The name of the base database as you passed it in.
-
ll
- A two-character code identifying the language.
-
CC
- A two-character code identifying the country.
The base database name is truncated if necessary to allow for this suffix.
For example, the base database "MemoPad" might have an overlay for US English named "MemoPad_enUS".
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
OmOverlayDBNameToLocale Function
Purpose
Return an overlay database's locale given its name.
Declared In
OverlayMgr.h
Prototype
Err OmOverlayDBNameToLocale( const Char *overlayDBName, LmLocaleType *overlayLocale )
Parameters
-
→
overlayDBName
- The name of the overlay database.
-
←
overlayLocale
- Points to an
LmLocaleType
structure identifying the overlay's locale.
Returns
Returns errNone
upon success, omErrBadOverlayDBName
if the string overlayDBName
is not long enough to have a locale suffix, or omErrUnknownLocale
if the locale cannot be determined.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
OmSetSystemLocale Function
Purpose
Set the system locale and reset the device.
Declared In
OverlayMgr.h
Prototype
Err OmSetSystemLocale( const LmLocaleType *systemLocale )
Parameters
-
→
systemLocale
- An
LmLocaleType
structure specifying the locale to switch the system to.
Returns
Returns errNone
upon success, or one of the following if an error occurs:
-
omErrUnknownLocale
- There is no system overlay for
systemLocale
. -
omErrInvalidLocale
- The system overlay for
systemLocale
has been found but is invalid. -
dmErrInvalidParam
- An error occurred while opening the overlay.
-
dmErrMemError
- A memory error occurred while opening the overlay.
-
dmErrDatabaseOpen
- The system overlay was already open.
Comments
This function changes the system locale to the specified locale if it exists. It first determines that the system overlay exists for the requested locale and that it matches the base system database. If so, it updates the system locale information saved in the storage heap header and resets the device. After the device is reset, the current locale is set to the system locale.
A Palm Powered™ device has a default locale hard-coded into the ROM. This locale is used to set the system locale after a hard reset or any time that the storage heap header is invalid. The storage heap header is typically only invalid when the device is turned on for the first time.
Compatibility
Implemented only if 3.5 New Feature Set is present. If Palm OS Cobalt Feature Set is present, however, this function is unimplemented.
In Palm OS 3.5, this function would not switch to a system overlay that was located in the RAM. The Palm OS 4.0 version of this function does return system overlays located in the RAM.