< Home < Developers < Development Support < Documentation

## 41 Overlay Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 41 Overlay Manager Overlay Manager Data Structures OmLocaleType Overlay Manager Constants Overlay Manager Functions OmGetCurrentLocale OmGetIndexedLocale OmGetNextSystemLocale OmGetRoutineAddress OmGetSystemLocale OmLocaleToOverlayDBName OmOverlayDBNameToLocale OmSetSystemLocale |  |  |  | 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 "Maintaining Backward Compatibility" in the "Localized Applications" chapter of the Palm OS Programmer's Companion, vol. I. ## Overlay Manager Data Structures ## OmLocaleType The OmLocaleType struct specifies a locale.
    typedef struct {
      UInt16   language;
      UInt16   country;
    } OmLocaleType;
#### Field Descriptions #####
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 #####
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 ## OmGetCurrentLocale #### Purpose Return the current locale. #### Prototype void OmGetCurrentLocale (LmLocaleType *currentLocale) #### Parameters #####
<- currentLocale | Points to an LmLocaleType 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. 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 76, "PalmOSGlue Library." #### See Also OmGetSystemLocale ## OmGetIndexedLocale #### Purpose Return a system locale by index. #### 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.
#### Result 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. 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 ## New OmGetNextSystemLocale #### Purpose Return a system locale. #### 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.
#### Result 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. ## 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. #### See Also IntlGetRoutineAddress, SysGetTrapAddress ## OmGetSystemLocale #### Purpose Return the system locale. #### Prototype void OmGetSystemLocale (LmLocaleType *systemLocale) #### Parameters #####
<- systemLocale | Points to an LmLocaleType 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. 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 76, "PalmOSGlue Library." #### 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 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.
#### 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, LmLocaleType *overlayLocale) #### Parameters #####
-> overlayDBName | The name of the overlay database.
#####
<- overlayLocale | Points to an LmLocaleType 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 LmLocaleType *systemLocale) #### Parameters #####
-> systemLocale | An LmLocaleType 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 PoweredTM 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. 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. #### See Also OmGetSystemLocale |