(68K) Overlay Manager | Palm OS® Programmer's API Reference

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 ^TOP^

OmLocaleType Struct ^TOP^

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 ^TOP^

Constant	Value	Description
`omOverlayRscType`	`'ovly'`	Symbolic name of an overlay resource that is contained in both the base database and the overlay database.
`omOverlayRscID`	1000	Resource ID of the overlay resource in both the base database and the overlay database.
`omFtrCreator`	`'ovly'`	Creator value used for the `omFtrShowErrorsFlag` feature.
`omFtrDefaultLocale`	1	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 `FtrGet()` and `FtrSet()` to retrieve and set this value.
`omFtrShowErrorsFlag`	0	Feature that controls the number of error messages displayed by the overlay manager. If this feature is set to `true`, the overlay manager may display several more error messages when validating an overlay against its base database. This feature only takes effect when the error checking level is set to full (common on debug ROMs, not on release ROMs). Use `FtrGet()` and `FtrSet()` to retrieve and set this value.

Overlay Manager Functions ^TOP^

OmGetCurrentLocale Function ^TOP^

Purpose

Return the current locale.

Declared In

OverlayMgr.h

Prototype

void OmGetCurrentLocale(
   LmLocaleType *currentLocale
)

Parameters

← currentLocale: Points to an LmLocaleType struct that identifies the current locale.

Returns

Returns nothing.

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."

OmGetIndexedLocale Function ^TOP^

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.

OmGetNextSystemLocale Function ^TOP^

Purpose

Return a system locale.

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, or false if this function call is a continuation of a search.
↔ ioStateInfoP: If iNewSearch is false, 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 ^TOP^

Purpose

Return the address of an overlay manager function.

Declared In

OverlayMgr.h

Prototype

void *OmGetRoutineAddress (
   OmSelector inSelector
)

Parameters

→ inSelector: One of the routine selectors defined in OverlayMgr.h.

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.

OmGetSystemLocale Function ^TOP^

Purpose

Return the system locale.

Declared In

OverlayMgr.h

Prototype

void OmGetSystemLocale(
   LmLocaleType *systemLocale
)

Parameters

← systemLocale: Points to an LmLocaleType struct that identifies the system locale.

Returns

Returns nothing.

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."

OmLocaleToOverlayDBName Function ^TOP^

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. Pass NULL 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

where:

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.

OmOverlayDBNameToLocale Function ^TOP^

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.

OmSetSystemLocale Function ^TOP^

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.

44 Overlay Manager

Overlay Manager Data Structures ^TOP^

OmLocaleType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

Overlay Manager Constants ^TOP^

Overlay Manager Functions ^TOP^

OmGetCurrentLocale Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

OmGetIndexedLocale Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

OmGetNextSystemLocale Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

OmGetRoutineAddress Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

OmGetSystemLocale Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

OmLocaleToOverlayDBName Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

OmOverlayDBNameToLocale Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Compatibility

See Also

OmSetSystemLocale Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also