37 Overlay Manager

This chapter describes the overlay manager API as declared in the header file OverlayMgr.h. It discusses the following topics:

• Overlay Manager Data Structures
  
  
• Overlay Manager Constants
  
  
• Overlay Manager Functions
  

For more information on the overlay manager, see the section "Using Overlays to Localize Resources" in the "Localized Applications" chapter of the Palm OS Programmer's Companion.

Overlay Manager Data Structures

OmLocaleType

The OmLocaleType struct specifies a locale.

typedef struct {

    UInt16 language;
    UInt16 country;
} OmLocaleType;

Field Descriptions

OmOverlayRscType

The OmOverlayRscType struct specifies an overlay of one resource. You create a resource overlay using the tools provided in the Palm OS^® SDK.

typedef struct {

    OmOverlayKind overlayType;
    UInt32 rscType;
    UInt16 rscID;
    UInt32 rscLength;
    UInt32 rscChecksum;
} OmOverlayRscType;

Your code should treat the OmOverlayRscType structure as opaque. Do not attempt to change structure member values directly.

Field Descriptions

OmOverlaySpecType

The OmOverlaySpecType struct defines a resource of type 'ovly'. This resource is required in the overlay database and may optionally exist in the corresponding base database as well.

typedef struct {

    UInt16 version;
    UInt32 flags;
    UInt32 baseChecksum;
    OmLocaleType targetLocale;
    UInt32 baseDBType;
    UInt32 baseDBCreator;
    UInt32 baseDBCreateDate;
    UInt32 baseDBModDate;
    UInt16 numOverlays;
    OmOverlayRscType overlays[0];
} OmOverlaySpecType;

Your code should treat the OmOverlaySpecType structure as opaque. Do not attempt to change structure member values directly.

Field Descriptions

Overlay Manager Constants

Overlay Manager Functions

OmGetCurrentLocale

Purpose

Return the current locale.

Prototype

void OmGetCurrentLocale (OmLocaleType *currentLocale)

Parameters

<- currentLocale

Points to an OmLocaleType struct that identifies the current locale.

Result

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.

See Also

OmGetSystemLocale

OmGetIndexedLocale

Purpose

Return a system locale by index.

Prototype

Err OmGetIndexedLocale (UInt16 localeIndex, OmLocaleType *theLocale)

Parameters

-> localeIndex

Zero-based index of the locale to return.

<- theLocale

Points to an OmLocaleType struct that identifies the locale at that index.

Result

Returns errNone upon success, or omErrInvalidLocaleIndex if the index is out of bounds.

Comments

You can use this function in a loop to determine how many 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.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

OmGetSystemLocale

OmGetRoutineAddress

Purpose

Return the address of an overlay manager function.

Prototype

void *OmGetRoutineAddress (OmSelector inSelector)

Parameters

-> inSelector

One of the routine selectors defined in OverlayMgr.h.

Result

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

Purpose

Return the system locale.

Prototype

void OmGetSystemLocale (OmLocaleType *systemLocale)

Parameters

<- systemLocale

Points to an OmLocaleType struct that identifies the system locale.

Result

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.

See Also

OmGetCurrentLocale

OmLocaleToOverlayDBName

Purpose

Return the overlay database's name given the base database name and the locale.

Prototype

Err OmLocaleToOverlayDBName (const Char *baseDBName, const OmLocaleType *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 OmLocaleType. 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.

Result

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.

See Also

OmOverlayDBNameToLocale

OmOverlayDBNameToLocale

Purpose

Return an overlay database's locale given its name.

Prototype

Err OmOverlayDBNameToLocale (const Char *overlayDBName, OmLocaleType *overlayLocale)

Parameters

-> overlayDBName

The name of the overlay database.

<- overlayLocale

Points to an OmLocaleType structure identifying the overlay's locale.

Result

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

OmLocaleToOverlayDBName

OmSetSystemLocale

Purpose

Set the system locale and reset the device.

Prototype

Err OmSetSystemLocale
(const OmLocaleType *systemLocale)

Parameters

-> systemLocale

An OmLocaleType structure specifying the locale to switch the system to.

Result

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 OS device has a default system 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.

See Also

OmGetSystemLocale