201 lines
7.8 KiB
C
201 lines
7.8 KiB
C
/******************************************************************************
|
||
*
|
||
* Copyright (c) 1999-2000 Palm, Inc. or its subsidiaries.
|
||
* All rights reserved.
|
||
*
|
||
* File: OverlayMgr.h
|
||
*
|
||
* Release: Palm OS SDK 4.0 (63220)
|
||
*
|
||
* Description:
|
||
* Public header for routines that support overlays.
|
||
*
|
||
* History:
|
||
* 06/24/99 kwk Created by Ken Krugler.
|
||
* 07/06/99 CS Added omSpecAttrForBase
|
||
* (and renumbered omSpecAttrStripped).
|
||
* 07/29/99 CS Added omOverlayKindBase for the entries in the base
|
||
* DBs 'ovly' resource (they had been set to
|
||
* omOverlayKindReplace before).
|
||
* 07/29/99 CS Bumped version to 3, since now we're supposed to
|
||
* support omOverlayKindAdd.
|
||
* 09/29/99 kwk Bumped version to 4, since we added the baseChecksum
|
||
* field to OmOverlaySpecType, as a way of speeding up
|
||
* overlay validation.
|
||
* 09/29/99 CS Actually bumped version to 4, which Ken forgot.
|
||
* 10/08/99 kwk Added OmGetRoutineAddress selector/declaration.
|
||
* Moved OmDispatch, OmInit, and OmOpenOverlayDatabase
|
||
* into OverlayPrv.h
|
||
* ===== Palm OS 3.5 Released =====
|
||
* 03/12/00 kwk Fixed comment for omOverlayKindHide.
|
||
* 05/18/00 kwk Added omFtrDefaultLocale feature selector.
|
||
* Added OmGetNextSystemLocale routine. Changed OmLocaleType
|
||
* to LmLocaleType. Deleted omOverlayDBType (use sysFileTOverlay).
|
||
* Moved more private stuff into OverlayPrv.h.
|
||
* 07/29/00 kwk Added note about using OmGetNextSystemLocale vs OmGetIndexedLocale.
|
||
* 09/14/00 kwk Added didNoOverlaySystem & foundSystem to OmSearchStateType,
|
||
* plus 6 more reserved bytes for future expansion.
|
||
* 09/18/00 kwk Added omErrNoNextSystemLocale.
|
||
*
|
||
*****************************************************************************/
|
||
|
||
#ifndef __OVERLAYMGR_H__
|
||
#define __OVERLAYMGR_H__
|
||
|
||
// Include elementary types
|
||
#include <PalmTypes.h>
|
||
#include <DataMgr.h>
|
||
#include <LocaleMgr.h> // For LmLocaleType
|
||
|
||
/***********************************************************************
|
||
* Overlay Manager constants
|
||
**********************************************************************/
|
||
|
||
#define omOverlayRscType 'ovly' // Overlay desc resource type
|
||
#define omOverlayRscID 1000 // Overlay desc resource ID
|
||
|
||
#define omFtrCreator 'ovly' // For get/set of Overlay features.
|
||
#define omFtrShowErrorsFlag 0 // Boolean - True => display overlay errors.
|
||
#define omFtrDefaultLocale 1 // LmLocaleType record => default locale to
|
||
// try with stripped bases & no valid overlay.
|
||
|
||
// OmFindOverlayDatabase called with stripped base, and no appropriate overlay was found.
|
||
#define omErrBaseRequiresOverlay (omErrorClass | 1)
|
||
|
||
// OmOverlayDBNameToLocale or OmLocaleToOverlayDBName were passed an unknown locale.
|
||
#define omErrUnknownLocale (omErrorClass | 2)
|
||
|
||
// OmOverlayDBNameToLocale was passed a poorly formed string.
|
||
#define omErrBadOverlayDBName (omErrorClass | 3)
|
||
|
||
// OmGetIndexedLocale was passed an invalid index.
|
||
#define omErrInvalidLocaleIndex (omErrorClass | 4)
|
||
|
||
// OmSetSystemLocale was passed an invalid locale (doesn't correspond to available
|
||
// system overlay).
|
||
#define omErrInvalidLocale (omErrorClass | 5)
|
||
|
||
// OmSetSystemLocale was passed a locale that referenced an invalid system overlay
|
||
// (missing one or more required resources)
|
||
#define omErrInvalidSystemOverlay (omErrorClass | 6)
|
||
|
||
// OmGetNextSystemLocale was called, but there were no more valid system
|
||
// locales to return.
|
||
#define omErrNoNextSystemLocale (omErrorClass | 7)
|
||
|
||
/***********************************************************************
|
||
* Selectors & macros used for calling Overlay Manager routines
|
||
**********************************************************************/
|
||
|
||
#ifdef DIRECT_OVERLAY_CALLS
|
||
#define OMDISPATCH_TRAP(omSelectorNum)
|
||
#else
|
||
#define OMDISPATCH_TRAP(sel) \
|
||
_SYSTEM_API(_CALL_WITH_SELECTOR)(_SYSTEM_TABLE, sysTrapOmDispatch, sel)
|
||
#endif
|
||
|
||
// Selectors used for getting to the right Overlay Manager routine via
|
||
// the OmDispatch trap.
|
||
|
||
#define omInit 0
|
||
#define omOpenOverlayDatabase 1
|
||
#define omLocaleToOverlayDBName 2
|
||
#define omOverlayDBNameToLocale 3
|
||
#define omGetCurrentLocale 4
|
||
#define omGetIndexedLocale 5
|
||
#define omGetSystemLocale 6
|
||
#define omSetSystemLocale 7
|
||
#define omGetRoutineAddress 8
|
||
#define omGetNextSystemLocale 9
|
||
|
||
#define omMaxSelector omGetNextSystemLocale
|
||
|
||
typedef UInt16 OmSelector;
|
||
|
||
/***********************************************************************
|
||
* Overlay Manager types
|
||
**********************************************************************/
|
||
|
||
// DOLATER kwk - decide how to deprecate this.
|
||
typedef LmLocaleType OmLocaleType;
|
||
|
||
// Structure passed to OmGetNextSystemLocale.
|
||
typedef struct {
|
||
DmSearchStateType searchState;
|
||
DmOpenRef systemDBRef;
|
||
UInt16 systemDBCard;
|
||
Char systemDBName[dmDBNameLength];
|
||
Int16 systemDBNameLen;
|
||
LmLocaleType curLocale;
|
||
Boolean didNoOverlaySystem;
|
||
Boolean foundSystem;
|
||
UInt8 reserved[6];
|
||
} OmSearchStateType;
|
||
|
||
/***********************************************************************
|
||
* Overlay Manager routines
|
||
**********************************************************************/
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
// Return in <overlayDBName> an overlay database name that's appropriate
|
||
// for the base name <baseDBName> and the locale <targetLocale>. If the
|
||
// <targetLocale> param in NULL, use the current locale. The <overlayDBName>
|
||
// buffer must be at least dmDBNameLength bytes.
|
||
Err OmLocaleToOverlayDBName(const Char *baseDBName, const LmLocaleType *targetLocale,
|
||
Char *overlayDBName)
|
||
OMDISPATCH_TRAP(omLocaleToOverlayDBName);
|
||
|
||
// Given the name of an overlay database in <overlayDBName>, return back
|
||
// the overlay in overlayLocale. If the name isn't an overlay name,
|
||
// return omErrBadOverlayDBName.
|
||
Err OmOverlayDBNameToLocale(const Char *overlayDBName, LmLocaleType *overlayLocale)
|
||
OMDISPATCH_TRAP(omOverlayDBNameToLocale);
|
||
|
||
// Return the current locale in <currentLocale>. This may not be the same as
|
||
// the system locale, which will take effect after the next reset.
|
||
void OmGetCurrentLocale(LmLocaleType *currentLocale)
|
||
OMDISPATCH_TRAP(omGetCurrentLocale);
|
||
|
||
// Return the nth valid system locale in <theLocale>. Indexes are zero-based,
|
||
// and omErrInvalidLocaleIndex will be returned if <localeIndex> is out of
|
||
// bounds. Note that OmGetNextSystemLocale should be used on Palm OS 4.0 or
|
||
// later, since OmGetIndexedLocale can be slow on ROMs with more than few
|
||
// valid system locales.
|
||
Err OmGetIndexedLocale(UInt16 localeIndex, LmLocaleType *theLocale)
|
||
OMDISPATCH_TRAP(omGetIndexedLocale);
|
||
|
||
// Return the system locale in <systemLocale>. This may not be the same as
|
||
// the current locale. WARNING!!! This routine should only be used in very
|
||
// special situations; typically OmGetCurrentLocale should be used to determine
|
||
// the "active" locale.
|
||
void OmGetSystemLocale(LmLocaleType *systemLocale)
|
||
OMDISPATCH_TRAP(omGetSystemLocale);
|
||
|
||
// Set the post-reset system locale to be <systemLocale>. Return omErrInvalidLocale if
|
||
// the passed locale doesn<73>t correspond to a valid System.prc overlay.
|
||
Err OmSetSystemLocale(const LmLocaleType *systemLocale)
|
||
OMDISPATCH_TRAP(omSetSystemLocale);
|
||
|
||
// Return back the address of the routine indicated by <inSelector>. If
|
||
// <inSelector> isn't a valid routine selector, return back NULL.
|
||
void *OmGetRoutineAddress(OmSelector inSelector)
|
||
OMDISPATCH_TRAP(omGetRoutineAddress);
|
||
|
||
// NEW in 4.0. Return back the next valid system locale in <oLocaleP>. The first
|
||
// time the routine is called, <iNewSearch> must be true. When there are no more
|
||
// valid system locales, omErrInvalidLocaleIndex will be returned. This routine
|
||
// should be used in place of OmGetIndexedLocale on Palm OS 4.0 or later, since
|
||
// it's much faster.
|
||
Err OmGetNextSystemLocale(Boolean iNewSearch, OmSearchStateType* ioStateInfoP, LmLocaleType* oLocaleP)
|
||
OMDISPATCH_TRAP(omGetNextSystemLocale);
|
||
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif
|