B Compatibility Guide

This appendix lists groups of functions and other features (such as events and launch codes) that have been added to the Palm OS^® after version 1.0.

Before you use any new functions or features in an application, you must check to ensure that they are implemented in the OS version your application is running on. Checking the OS version number is not a reliable indicator that a specific feature is present, since some later OS versions do not include features present in earlier versions. In order to ensure that your code is supported, you must check for the presence of individual features.

To make this check easier, this appendix lists new functions and features in groups such that all functions and features in a group are always implemented together in the ROM of a Palm device. This means that you can check for a single feature in that group and be assured that if that feature is present than all functions and features in that group are implemented.

Each group includes a recommended test to check if it is implemented. The following groups are described:

• 2.0 New Feature Set
  
  
• 3.0 New Feature Set
  
  
• 3.1 New Feature Set
  
  
• 3.2 New Feature Set
  
  
• International Feature Set
  
  
• Japanese Feature Set
  
  
• Wireless Internet Feature Set
  
  
• New Serial Manager Feature Set
  
  
• 3.5 New Feature Set
  
  
• Notification Feature Set
  

2.0 New Feature Set

You can check that this feature set is implemented by checking that the system version is 2.0 or higher. Use this FtrGet call:

err = FtrGet(sysFtrCreator, sysFtrNumROMVersion, &romversion);

The romversion parameter should be 0x02003000 or greater.

Launch Codes

This feature set adds the following launch codes:

sysAppLaunchCmdLookup sysAppLaunchCmdPanelCalledFromApp sysAppLaunchCmdReturnFromPanel sysAppLaunchCmdSystemLock

Functions

This feature set adds the following functions:

CategoryInitialize	CategorySetName
DmDeleteCategory	DmDatabaseProtect
EvtAddUniqueEventToQueue EvtSysEventAvail	EvtEventAvail
FldGetNumberOfBlankLines FldSetInsertionPoint	FldGetScrollValues
FntGetScrollValues FntWordWrapReverseNLines	FntWordWrap
FrmPointInTitle FrmSetObjectBounds	FrmSetMenu
KeySetMask	LocGetNumberSeparators
LstScrollList	LstGetVisibleItems
MemCmp	MenuSetActiveMenuRscID
PhoneNumberLookup
PrefSetPreference	PrefGetPreference
SclDrawScrollBar SclHandleEvent	SclGetScrollBar SclSetScrollBar
SerControl
StrDelocalizeNumber StrNCaselessCompare StrNCompare StrPrintF	StrLocalizeNumber StrNCat StrNCopy StrVPrintF
SysBinarySearch SysCreatePanelList SysGraffitiReferenceDialog SysStringByIndex	SysCreateDataBaseList SysErrString SysLibLoad SysTicksPerSecond
TblHasScrollBar TblSetColumnEditIndicator	TblSetBounds TblSetRowStaticHeight
WinSetWindowBounds

Existing Functions that Changed

Several functions that existed in 1.0 were changed in 2.0:

CategoryCreateList (old function renamed CategoryCreateListV10)

CategoryEdit (old function renamed CategoryEditV10)

CategoryFreeList (old function renamed CategoryFreeListV10)

CategorySelect (old function renamed CategorySelectV10)

SelectDay (old function renamed SelectDayV10)

DmFindSortPosition (old function renamed DmFindSortPositionV10)

PrefGetAppPreferences (old function renamed PrefGetAppPreferencesV10)

PrefOpenPreferenceDB (old function renamed PrefOpenPreferenceDBV10)

PrefSetAppPreferences (old function renamed PrefSetAppPreferencesV10)

SerReceive (old function renamed SerReceive10)

SerSend (old function renamed SerSend10)

SysKeyboardDialog (old function renamed SysKeyboardDialogV10)

Other Changes

As a rule, all Palm OS applications developed with the 1.0 SDK should run error-free on the latest device. There are two possible pitfalls for 1.0 applications:

• fldChangedEvent Change--The operating system now correctly sends a fldChangedEvent whenever a field object is changed. Previously, the event was at times not sent, especially when a FldSetText operation was performed. If your application doesn't catch the events that are now sent, it may have problems.
  
  
• Non-standard tools--If your application was not developed with Metrowerks Code Warrior for the Palm OS, it may run into problems. One known problem can occur if the application:
  
  • was compiled with optimization turned on
  • uses system preferences

3.0 New Feature Set

You can check that this feature set is implemented by checking that the system version is 3.0 or higher. Use this FtrGet call:

err = FtrGet(sysFtrCreator, sysFtrNumROMVersion, &romversion);

The romversion parameter should be 0x03003000 or greater.

Launch Codes

This feature set adds the following launch codes:

sysAppLaunchCmdExgAskUser sysAppLaunchCmdExgReceiveData

In addition, the launch code sysAppLaunchCmdGoto is now also sent by the exchange manager, in addition to its use by the global find operation.

Font

This feature set adds the following font:

largeBoldFont

Functions

This feature set adds the following functions:

Dynamic User Interface Functions

For more information on creating and using dynamic user interface elements, see the section "Dynamic UI" of the Palm OS Programmer's Companion.

Font Functions

For more information on these functions and the support for custom fonts, see the section "Fonts in Palm OS 3.0 and Later" of the Palm OS Programmer's Companion.

Progress Manager Functions

For more information, see the section "Progress Dialogs" of the Palm OS Programmer's Companion.

File Streaming Functions

For more information, see the section "File Streaming Application Program Interface" of the Palm OS Programmer's Companion.

Sound Functions

Exchange Manager Functions

For more information, see the chapter Beaming (Infrared Communication) in the Palm OS Programmer's Companion.

IR Library Functions

For more information, see the chapter Beaming (Infrared Communication) in the Palm OS Programmer's Companion.

Miscellaneous Functions

Existing Functions that Changed

Two functions that existed in 2.0 were changed in 3.0:

CategoryEdit (old function renamed CategoryEditV20)

SysBatteryInfo (old function renamed SysBatteryInfoV20)

Other Changes

• The dynamic heap has been increased in size to 96 KB.
  
  
• Storage RAM is no longer subdivided into multiple storage heaps of 64 KB each. All storage RAM on a memory card is configured as a single storage heap.
  
  
• Each flash ROM-based Palm device holds a serial number that identifies it uniquely and can be retrieved via SysGetROMToken. For more information, see "Retrieving the ROM Serial Number" of the Palm OS Programmer's Companion.
  
  
• The Application Launcher (accessed via the silkscreen "Applications" button) is now an application, rather than a popup. The SysAppLauncherDialog function, which provides the API to the old popup launcher, is still present in Palm OS 3.0 for compatibility purposes, but has not been updated and generally should not be used. For more information, see "Application Launcher" of the Palm OS Programmer's Companion.
  
  
• The sound manager supports MIDI sound files, adding new sounds, asynchronous playback, and other features. There are also new selectors for setting the volume preferences. For more information, see the section "Sound" of the Palm OS Programmer's Companion.
  

  The following functions existed in the system previously, but were not documented:

  RctCopyRectangle RctGetIntersection RctInsetRectangle	RctOffsetRectangle RctPtInRectangle RctSetRectangle

  The following event type existed in the system previously, but was not previously documented:

  frmGotoEvent

3.1 New Feature Set

You can check that this feature set is implemented by checking that the system version is 3.1 or higher. Use this FtrGet call:

err = FtrGet(sysFtrCreator, sysFtrNumROMVersion, &romversion);

The romversion parameter should be 0x03103000 or greater.

Functions

This feature set adds the following functions:

ChrHorizEllipsis ChrNumericSpace ContrastAdjust FntWidthToOffset FtrPtrNew FtrPtrFree FtrPtrResize SelectOneTime WinDrawChar WinDrawTruncChars

---

NOTE:  

The PalmOSGlue.lib provides compatibility functions and macros for ChrHorizEllipsis, ChrNumericSpace, WinDrawChar, and WinDrawTruncChars. If you want to use these functions on systems that don't have the 3.1 feature set, you can link your application with PalmOSGlue.lib. See the chapter "PalmOSGlue Library" for more information.

---

Changes to the Character Encoding

Starting in Palm OS 3.1, the character encoding used on most systems is Microsoft Windows code page 1252. Versions prior to 3.1 used an encoding that was very similar to code page 1252 but did not follow it exactly. The following changes to the character set are introduced in Palm OS 3.1:

• Some of the special Palm OS glyphs in the high ASCII range (such as the shortcut stroke and the command stroke) have been moved down into the control code range, and other characters (such as the numeric space and horizontal ellipsis) have been copied into the control range so that they're guaranteed to exist in every encoding. For the numeric space and horizontal ellipsis, you can use the macros ChrNumericSpace and ChrHorizEllipsis to return the appropriate character regardless of the character map. In PalmOSGlue.lib, these two macros are named TxtGlueGetNumericSpaceChar and TxtGlueGetHorizEllipsisChar, respectively.
  
  
• The four playing-card characters have been moved from the high ASCII range in the standard four fonts to the 9-point Symbol font.
  

Other Changes in 3.1

• Palm OS 3.1 supports a new processor: the EZ Dragonball processor. This processor is compatible with the existing Dragonball processor, so your application should run without changes as long as it doesn't access registers or system globals directly.
  

  If your application needs to know if it is running on an EZ Dragonball, it can check using the following code:

  
  DWord id, chip;
  

  Word revision;
Err err;
err = FtrGet(sysFtrCreator,
    sysFtrNumProcessorID, &id);
if (!err) {
    chip = id & sysFtrNumProcessorMask;
    revision = id & 0x0ffff;
    if (chip==sysFtrNumProcessor328)
    // traditional Dragonball
    else if (chip==sysFtrNumProcessorEZ)
    // Dragonball EZ
}
  

  
  
  • The constant preferenceDataVersion was removed and replaced with preferenceDataVerLatest.
    
    
  • Character variables are now two bytes long. The type WChar defines a character variable.
    
    
  • The keyDownEvent structure's chr field (which contains the input character) has been changed from a Word to a WChar.
    
    
  • The string manager functions StrChr and StrStr now treat buffers as characters, not arbitrary byte arrays. If you previously used these functions to search data buffers, your code may no longer work.
    
    
  • The string manager function StrToLower can now handle any type of characters, including accented characters.
    
    
  • The underline attribute of FieldAttrType now has support for the value 2. Previously, the only underline modes available were no underline (0) and gray underline (1). In Palm OS 3.1 and higher, the value 2 is interpreted as solid underline. The UnderlineModeType enum defined in Window.h defines the possible values for the underline attribute.
    
    
  • The use of the DmGetNextDatabaseByTypeCreator onlyLatestVers parameter changed in 3.1. If onlyLatestVers is true, you only receive one matching database for each type/creator pair. In version 3.0 and earlier, you could receive multiple matching databases if onlyLatestVers was true. See that function's description for a more detailed description.
    

3.2 New Feature Set

You can check that this feature set is implemented by checking that the system version is 3.2 or higher. Use this FtrGet call:

err = FtrGet(sysFtrCreator, sysFtrNumROMVersion, &romversion);

The romversion parameter should be 0x03203000 or greater.

Functions

This feature set adds the following functions:

AlmGetProcAlarm AlmSetProcAlarm ClipboardAppendItem DmGetDatabaseLockState ErrAlert SndPlaySmfResource

Existing Functions that Changed

Two functions that existed in 3.0 were changed in 3.2:

SysGremlins was removed and replaced with a SysGremlins macro that maps it to the function HostGremlinIsRunning. The prototype is slightly different, but you can still call SysGremlins in the same way you did before.

PrgStartDialog (old function renamed PrgStartDialogV31)

Other Changes in 3.2

• The prototype for the system use only function AlmDisplayAlarm changed from no return value to a Boolean return value. This change may affect system patches and extensions that intercept AlmDisplayAlarm calls.
  

International Feature Set

You can check that this feature set is implemented by checking for the existence of the international manager. You can check by calling FtrGet as follows:

err = FtrGet(sysFtrCreator, sysFtrNumIntlMgr, &value);

If the international manager is installed, the value parameter will be non-zero and the returned error should also be zero (for no error).

You can learn more about the international manager by reading the chapter "Localized Applications" in the Palm OS Programmer's Companion.

---

NOTE:  

If you want to use international functions on systems that don't have the international feature, you can link your application with PalmOSGlue.lib. The functions in this library are the same as those listed below except that they use the prefix "TxtGlue" instead of "Txt." For more information, see the chapter "PalmOSGlue Library" .

---

Functions

This feature set adds the following functions:

Text Manager Functions

Other Functions

IntlGetRoutineAddress

Removed Functions and Macros

If the international feature set exists, then the following functions and macros are no longer available:

GetCharAttr GetCharCaselessValue GetCharSortValue IsAscii IsAlNum IsAlpha IsCntrl IsDigit IsGraph IsLower IsPrint IsPunct IsSpace IsUpper IsHex IsDelim

Japanese Feature Set

You can check that the Japanese feature set is implemented by checking if the unit is Japanese. You can check by calling FtrGet as follows:

err = FtrGet(sysFtrCreator, sysFtrNumEncoding, &value);

The unit has the Japanese OS if the value parameter is charEncodingCP932.

For further information about the Japanese implementation, see the section "Notes on the Japanese Implementation" in the Palm OS Programmer's Companion.

Wireless Internet Feature Set

You can check that this feature set is implemented by checking for the existence of the Clipper and iMessenger^™ applications. Here's an example of how to check for Clipper:

DmSearchStateType searchState;

UInt cardNo;
LocalID dbID;
err = DmGetNextDatabaseByTypeCreator(true, &searchState, sysFileTApplication, sysFileCClipper, true, &cardNo, &dbID);

If Clipper is not present, the DmGetNextDatabaseByTypeCreator routine returns an error. To check for iMessenger, you can use the creator type sysFileCMessaging.

You can learn more about the Palm.Net^™ system for wireless Internet access and the programmatic interfaces to the Clipper and iMessenger applications by reading the chapter "Internet and Messaging Applications" in the Palm OS Programmer's Companion.

Launch Codes

This feature set adds the following launch codes:

sysAppLaunchCmdAddRecord (for iMessenger application; existed for Mail in 3.0) sysAppLaunchCmdGoToURL sysAppLaunchCmdOpenDB sysAppLaunchCmdURLParams

Events

This feature set adds the following events:

inetSockReadyEvent inetSockStatusChangeEvent

This feature set also adds the following keyDownEvent key codes:

vchrHardAntenna vchrRadioCoverageOK vchrRadioCoverageFail

These key codes are described in the section New keyDownEvent Key Codes.

Functions

This feature set adds the following functions.

Internet Library Functions

For more information, see the chapter "Network Communication" in the Palm OS Programmer's Companion.

INetLibCacheGetObject INetLibCacheList INetLibCheckAntennaState INetLibClose INetLibConfigAliasGet INetLibConfigAliasSet INetLibConfigDelete INetLibConfigIndexFromName INetLibConfigList INetLibConfigMakeActive INetLibConfigRename INetLibConfigSaveAs INetLibGetEvent INetLibOpen INetLibSettingGet INetLibSettingSet

INetLibSockClose INetLibSockConnect INetLibSockHTTPAttrGet INetLibSockHTTPAttrSet INetLibSockHTTPReqCreate INetLibSockHTTPReqSend INetLibSockOpen INetLibSockRead INetLibSockSettingGet INetLibSockSettingSet INetLibSockStatus INetLibURLCrack INetLibURLGetInfo INetLibURLOpen INetLibURLsAdd INetLibWiCmd

New Serial Manager Feature Set

You can check that this feature set is implemented by checking for the existence of the new serial manager. You can check by calling FtrGet as follows:

err = FtrGet(sysFileCSerialMgr, sysFtrNewSerialPresent, &value);

If the new serial manager is installed, the value parameter will be non-zero and the returned error should also be zero (for no error).

You can learn more about the new serial manager and connection manager by reading the sections "The New Serial Manager" and "The Connection Manager" in the Palm OS Programmer's Companion.

Functions

This feature set adds the following functions.

New Serial Manager Functions

Serial Driver Functions

Virtual Driver Functions

Connection Manager Functions

Serial Link Manager Function

SlkSocketPortID

3.5 New Feature Set

You can check that this feature set is implemented by checking that the system version is 3.5 or higher. Use this FtrGet call:

err = FtrGet(sysFtrCreator, sysFtrNumROMVersion, &romversion);

The romversion parameter should be 0x03503000 or greater.

Launch Codes

This feature set adds the following launch codes:

sysAppLaunchCmdNotify

Events

This feature set adds the following events:

frmGadgetEnterEvent frmGadgetMiscEvent menuCmdBarOpenEvent menuOpenEvent

Functions

This feature set adds the following functions.

Bitmaps

Controls

Forms

Menus

Overlay Manager

Private Records

Tables

UI Colors

UI Controls

Windows

Miscellaneous New Functions

Existing Functions that Changed

The following functions that existed prior to 3.5 have changed in release 3.5:

ScrDisplayMode was changed to WinScreenMode.

ContrastAdjust was changed to UIContrastAdjust.

SelectTime (old function renamed SelectTimeV33)

New Data Types

The data types Byte, Word, DWord and so on are now deprecated. It is recommend that you use the corresponding new data types. For example, use Int16 instead of SWord and UInt32 instead of DWord. In particular, the unfortunate distinction between Handle/VoidHand has been fixed; use MemHandle instead.

To learn in general how the type names changed, see the header file PalmOSCompatibility.h. This file provides a mapping from the old type name to the new type name. If you need to move forward without modifying your code, you can include this file in your project to provide declarations for the old type names.

Changes to Events

• The tapCount field has been added to the EventType structure. The tapCount field specifies the number of times the user tapped the pen at the current location; in fields, two taps selects a word, and three taps selects a line.
  

  
  

  ---

  
  IMPORTANT: Because the tapCount field has been added to the EventType structure, it has become more critical that you clear the event structure before using it to add a new event to the queue. Otherwise, the tapCount will be incorrect for the new event.
  

  ---

  
  

  
  
• The structures for ctlRepeatEvent and ctlSelectEvent have a value field added to them. This new field is used only for sliders; it holds the current value of the slider.
  
  
• Form objects now handle the frmTitleSelectEvent by adding a keyDownEvent with the vchrMenu character to the event queue (which causes the form's menu to display).
  
  
• Some of the structure definitions for system-level events have moved from Event.h to SysEvent.h.
  
  
• The winEnterEvent is now not generated until FrmDrawForm is called. Make sure to draw your form in response to frmOpenEvent, not winEnterEvent.
  

Other Changes

• FrmDrawForm
  

  On release 3.5, FrmDrawForm erases the window's rectangle before it draws, so you must perform custom drawing after the call to FrmDrawForm, not before. If you have drawn before the call to FrmDrawForm, your changes are lost. On debug ROMs, the window handle is invalid until FrmDrawForm is called so that draws before FrmDrawForm result in a bus error.

  
  
• Resource Manager
  

  The resource manager functions have been updated to work with overlay databases. See "Using Overlays to Localize Resources" in the Palm OS Programmer's Companion.

  
  
• DmGetDatabase
  

  The order in which this call returns databases has changed. Previously all of the databases from ROM were returned first, then all from RAM. Now they are intermingled. Developers should not rely on the order in which databases are returned from this call.

  
  
• StrToLower
  

  This function is different in 3.5 Latin ROMs. Previously it only changed A through Z. Now it also changes high ASCII characters.

  
  
• Time Manager
  

  If you are using a debug ROM, the string buffer is filled with dateStringLength or longStrLength debugging bytes, depending on the dateFormat parameter. For the routines that return the day-of-week name in addition to the date, the size of the buffers has been expanded, so developers need to check the max lengths defined in DateTime.h.

  
  
• The format of the storage heap header has changed, thus any existing saved Simulator card images are invalid and should be tossed.
  
  
• Category Data Structures
  

  The data structure AppInfoType has been documented.

  CategoryCreateList now has a "hide" function with two new constants; categoryHideEditCategory, and categoryDefaultEditCategoryString.

  
  
• FtrPtrNew
  

  FtrPtrNew now allows allocating chunks larger than 64KB.

  
  
• Dynamic heap
  

  The dynamic heap is now sized based on the amount of memory available to the system.

  Device RAM Size	Heap Size
  x < 2MB	64KB
  2MB ð x < 4MB	128KB
  x 4MB	256KB

Notification Feature Set

You can check that this feature set is implemented by checking for the existence of the notification manager. You can check by calling FtrGet as follows:

err = FtrGet(sysFtrCreator, sysFtrNumNotifyMgrVersion, &value);

If the notification manager is part of the system, the value parameter will be non-zero and the returned error should also be zero (for no error).

Notification Manager