Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

B    Compatibility Guide

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

Part V: Appendixes

B Compatibility Guide

2.0 New Feature Set

Launch Codes

Functions

Existing Functions that Changed

Other Changes

3.0 New Feature Set

Launch Codes

Font

Functions

Existing Functions that Changed

Other Changes

3.1 New Feature Set

Functions

Changes to the Character Encoding

Other Changes in 3.1

3.2 New Feature Set

Functions

Existing Functions that Changed

Other Changes in 3.2

International Feature Set

Functions

Japanese Feature Set

Wireless Internet Feature Set

Launch Codes

Events

Functions

New Serial Manager Feature Set

New Serial Manager Feature Set Version 1

New Serial Manager Feature Set Version 2

Connection Manager Feature Set

Functions

3.5 New Feature Set

Launch Codes

Events

Functions

Existing Functions that Changed

New Data Types

Changes to Events

Other Changes

Notification Feature Set

4.0 New Feature Set

Launch Codes

Notifications

Functions

Existing Functions that Changed

Expansion Manager Feature Set

Functions

VFS Manager Feature Set

Functions

Bluetooth Library Feature Set

Functions

High-Density Display Feature Set

New Data Types

Functions

1.5x Display Feature Set

New Data Types

Functions

Sound Stream Feature Set

Sound Stream Data Structures and Types

Sound Stream Enums and Constants

Sound Stream Functions

5.0 New Feature Set

Notifications

Functions

Virtual Ports

Functions and Traps not Supported by PACE

5.1 New Feature Set

Net Library Interface Settings

CPM Library

SSL Library

Pen Input Manager Feature Set

Pen Input Manager Version 1.0

Pen Input Manager Version 1.0

Graffiti 2 Feature Set

5.3SC New Feature Set

Functions

Notifications

Existing Functions that Changed

5.4 New Feature Set

New Data Types, Enums, Constants

Existing Functions that Changed

Other Changes

Bluetooth Sleep and Wake Scheduling Feature Set

ARM Debug Nub Feature Set

Palm OS Cobalt Feature Set

PACE

Design Objectives

API Restrictions

Accessing the PIM Application Databases

New Functions and Macros

New Data Structures and Constants

Existing Functions that Changed

One-Handed Navigation Feature Set

New Functions and Macros

New Data Structures and Types

     

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
Connection Manager Feature Set
3.5 New Feature Set
Notification Feature Set
4.0 New Feature Set
Expansion Manager Feature Set
VFS Manager Feature Set
Bluetooth Library Feature Set
High-Density Display Feature Set
1.5x Display Feature Set
Sound Stream Feature Set
5.0 New Feature Set
5.1 New Feature Set
Graffiti 2 Feature Set
5.3SC New Feature Set
5.4 New Feature Set
Bluetooth Sleep and Wake Scheduling Feature Set
ARM Debug Nub Feature Set
Palm OS Cobalt Feature Set
One-Handed Navigation Feature Set

2.0 New Feature Set ^TOP^

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

This feature set adds the following launch codes:

Functions ^TOP^

This feature set adds the following functions:

Existing Functions that Changed ^TOP^

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

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

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 greater than or equal to 0x03003000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(3,0,0,sysROMStageRelease,0) 

Launch Codes ^TOP^

This feature set adds the following launch codes:

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

This feature set adds the following font:

largeBoldFont

Functions ^TOP^

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, vol. I.

Font Functions

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

Progress Manager Functions

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

File Streaming Functions

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

Sound Functions

Exchange Manager Functions

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

IR Library Functions

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

Miscellaneous Functions

Existing Functions that Changed ^TOP^

Two functions that existed in 2.0 were changed in 3.0:

CategoryEdit() (old function renamed CategoryEditV20())

SysBatteryInfo() (old function renamed SysBatteryInfoV20())

Other Changes ^TOP^

  • 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, vol. I.
  • 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, vol. I.
  • 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 "System Boot and Reset" of the Palm OS Programmer's Companion, vol. I.

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

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

frmGotoEvent

3.1 New Feature Set ^TOP^

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 greater than or equal to 0x03103000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(3,1,0,sysROMStageRelease,0) 

Functions ^TOP^

This feature set adds the following functions:


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

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

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

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 greater than or equal to 0x03203000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(3,2,0,sysROMStageRelease,0) 

Functions ^TOP^

This feature set adds the following functions:

Note that the NetLib... functions, although present in the 3.2 New Feature Set, are first declared in the Palm OS Garnet SDK.

Existing Functions that Changed ^TOP^

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

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

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, vol. I.


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

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

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, vol. I.

Wireless Internet Feature Set ^TOP^

You can check that this feature set is implemented by checking for the existence of the Web Clipping Application Viewer (Viewer) and iMessenger applications. Here's an example of how to check for Viewer:


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

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


NOTE: The Viewer was formerly described as the Clipper.

You can learn more about the Palm.Net system for wireless Internet access and the programmatic interfaces to the Viewer and iMessenger applications by reading the chapter "Internet and Messaging Applications" in the Palm OS Programmer's Companion, vol. II, Communications. For a more complete description, see the Web Clipping Developer's Guide.

Launch Codes ^TOP^

This feature set adds the following launch codes:

Events ^TOP^

This feature set adds the following events:

This feature set also adds the following keyDownEvent key codes:

vchrHardAntenna
vchrRadioCoverageOK
vchrRadioCoverageFail

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

Functions ^TOP^

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, vol. II, Communications.

New Serial Manager Feature Set ^TOP^

The New Serial Manager feature set has two different versions.

New Serial Manager Feature Set Version 1 ^TOP^

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 Serial Manager" and "The Connection Manager" in the Palm OS Programmer's Companion, vol. II, Communications.

This feature set adds the following functions.

Serial Manager Functions

Virtual Driver Functions

Connection Manager Functions

Serial Link Manager Function

SlkSocketPortID()

New Serial Manager Feature Set Version 2 ^TOP^

You can check that version 2 of the new Serial Manager feature set is implemented by checking the Serial Manager version number and the Palm OS version number. You can check by calling FtrGet() as follows:


err = FtrGet(sysFileCSerialMgr,  
  sysFtrNewSerialVersion, &value); 
err = FtrGet(sysFtrCreator,  
  sysFtrNumROMVersion, &romVersion); 

The new Serial Manager is present if:

  • Both calls to FtrGet return zero (for no error).
  • The value parameter is 2.
  • The romVersion parameter is 0x04003000, which can be constructed using the sysMakeROMVersion macro:

    sysMakeROMVersion(4,0,0,sysROMStageRelease,0)  
    

This feature set adds the following functions.

Serial Manager Functions

Virtual Driver Functions


IMPORTANT: Some Handspring devices ship with Palm OS version 3.5 but have new Serial Manager feature set version 2. These devices support the SignalCheckPtr virtual driver function and have expanded functionality for USB support, but they do not support the other function calls in this feature set.

You can learn more about the new Serial Manager by reading the chapter "Serial Communication" of Palm OS Programmer's Companion, vol. II, Communications.

Connection Manager Feature Set ^TOP^

You can check that the Connection Manager feature set is implemented by checking the value of the Connection Manager feature. You can check by calling FtrGet() as follows:


err = FtrGet(kCncFtrCncMgrCreator,
kCncFtrCncMgrVersion, &version); 

The version parameter should be greater than or equal to 0x00040001. In the 4.0 Palm OS SDK, this value is represented by the kCncMgrVersion constant.


NOTE: An earlier version of the Connection Manager is available if New Serial Manager Feature Set Version 1 is present.

Functions ^TOP^

This feature set adds the following functions:

3.5 New Feature Set ^TOP^

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 greater than or equal to 0x03503000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(3,5,0,sysROMStageRelease,0) 

Launch Codes ^TOP^

This feature set adds the following launch codes:

Events ^TOP^

This feature set adds the following events:

Functions ^TOP^

This feature set adds the following functions:

Bitmaps

For more information on creating and using bitmaps, see the section "Bitmaps" of the Palm OS Programmer's Companion, vol. I.

Controls

These functions add support for graphical buttons and slider controls. For more information, see the section "Offscreen Windows" of the Palm OS Programmer's Companion, vol. I.

Forms

Among the changes to form functions is extended gadget support. For more information on gadgets and extended gadgets, see the section "Custom UI Objects (Gadgets)" of the Palm OS Programmer's Companion, vol. I.

Menus

For more information on using menu functions, see the section "Menus" of the Palm OS Programmer's Companion, vol. I.

Overlay Manager

For more information on using the overlay manager, see the section "Using Overlays to Localize Resources" of the Palm OS Programmer's Companion, vol. I.

Private Records

Tables

UI Colors

For more information on using the UI Colors API, see the section "Color and Grayscale Support" of the Palm OS Programmer's Companion, vol. I.

UI Controls

Windows

For more information on using the window functions, see the section "Drawing on the Palm Powered Handheld" of the Palm OS Programmer's Companion, vol. I.

Miscellaneous New Functions

Existing Functions that Changed ^TOP^

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

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

  • 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.
  • EvtSetNullEventTick() is now a function. In previous releases it was a macro.

Other Changes ^TOP^

  • 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" of the Palm OS Programmer's Companion, vol. I.

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

Table B.1  Dynamic heap size

Device RAM Size

Heap Size

x < 2MB

64KB

2MB š x < 4MB

128KB

x 4MB

256KB

Notification Feature Set ^TOP^

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

To learn more about the notification manager, see the section "Notifications" of the Palm OS Programmer's Companion, vol. I.

4.0 New Feature Set ^TOP^

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


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

The romVersion parameter should be greater than or equal to 0x04003000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(4,0,0,sysROMStageRelease,0) 

Launch Codes ^TOP^

This feature set adds the following launch codes:

Notifications ^TOP^

This feature set adds the following notifications:

Functions ^TOP^

This feature set adds the following functions:

Attention Manager

Date and Time Manager

Exchange Manager

For more information on the Exchange Manager, see the chapter Chapter 1, "Object Exchange," of the Palm OS Programmer's Companion, vol. II, Communications.

Exchange Library

For more information on the Exchange Library API, see Chapter 63, "Exchange Library," of the Palm OS Programmer's Companion, vol. II, Communications.

Locale Manager

Miscellaneous UI

Notification Manager

PDI Library Functions

For more information, see the chapter Chapter 3, "Personal Data Interchange," in Palm OS Programmer's Companion, vol. II, Communications.

Sound Manager Functions

For more information, see the chapter Chapter 11, "Palm System Support," in Palm OS Programmer's Companion, vol. I.

Telephony Manager Functions


For more information about the Telephony Manager, see Chapter 10, "Telephony Manager," in Palm OS Programmer's Companion, vol. II, Communications.

Windows Manager

Internationalization Functions

The following functions have been added to aid with creating localized applications:

Existing Functions that Changed ^TOP^

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

ExgRegisterData() has been deprecated. The preferred function is now ExgRegisterDatatype().

ExgGet() was previously unimplemented. It has been implemented in release 4.0

ExgNotifyReceive() was previously a private function. It is now a public function, intended to be used by exchange libraries.

FldRecalculateField() now updates the word-wrapping information whenever FldRecalculateField is called, regardless of the value of the redraw parameter. Prior to Palm OS 4.0 it updated the word-wrapping information only if the redraw parameter was set to true.

StrNCaselessCompare() now requires both of its string parameters to be null-terminated.

StrNCompare() now requires both of its string parameters to be null-terminated.

Expansion Manager Feature Set ^TOP^

Because not every system has (or needs) Expansion Manager services, applications wishing to use these services should check to make sure they are present before calling them. This is accomplished by checking for the Expansion Manager's system feature with a call to FtrGet(), supplying sysFileCExpansionMgr for the feature creator and expFtrIDVersion for the feature number.

The following code shows how to check for the presence and proper version of the Expansion Manger. Note that expectedExpMgrVersionNum should be replaced by the actual version number you expect.


UInt32 expMgrVersion; 
Err err; 
  
err = FtrGet(sysFileCExpansionMgr,
  expFtrIDVersion, &expMgrVersion); 
if(err){   
    // Expansion Manager not installed 
} else { 
    // check version number of Expansion Manager, 
    // if necessary 
    if(expMgrVersion == expectedExpMgrVersionNum) 
        // everything is OK 
} 

You can learn more about the expansion manager by reading Chapter 33, "Expansion Manager,".

Functions ^TOP^

This feature set adds the following functions.

Expansion Manager Functions

VFS Manager Feature Set ^TOP^

Because not every system has (or needs) Virtual File System (VFS) Manager services, applications wishing to use these services should check to make sure they are present before calling them. This is accomplished by checking for the VFS Manager's system feature with a call to FtrGet(), supplying sysFileCVFSMgr for the feature creator and vfsFtrIDVersion for the feature number.

The following code shows how to check for the presence and proper version of the VFS Manger. Note that expectedVFSMgrVersionNum should be replaced by the actual version number you expect.


UInt32 vfsMgrVersion; 
Err err; 
  
err = FtrGet(sysFileCVFSMgr,
  vfsFtrIDVersion, &vfsMgrVersion); 
if(err){   
    // VFS Manager not installed 
} else { 
    // check version number of VFS Manager, 
    // if necessary 
    if(vfsMgrVersion == expectedVFSMgrVersionNum) 
        // everything is OK 
} 

You can learn more about the VFS manager by reading Chapter 58, "Virtual File System Manager,".

Functions ^TOP^

This feature set adds the following functions.

VFS Manager Functions

Bluetooth Library Feature Set ^TOP^

Because not every system has (or needs) Bluetooth Library services, applications wishing to use these services should check to make sure they are present before calling them. This is accomplished by checking for the Bluetooth Library's system feature with a call to FtrGet(), supplying btLibFeatureCreator for the feature creator and btLibFeatureVersion for the feature number.

The following code shows how to check for the presence of the Bluetooth Library.


UInt32 btVersion; 
 
// Make sure Bluetooth components are installed 
// This check also ensures Palm OS 4.0 or greater 
if (FtrGet(btLibFeatureCreator, btLibFeatureVersion, 
    &btVersion) != errNone) { 
    // Alert the user if it's the active application 
    if ((launchFlags & sysAppLaunchFlagNewGlobals) && 
        (launchFlags & sysAppLaunchFlagUIApp)) 
        FrmAlert (MissingBtComponentsAlert); 
    return sysErrRomIncompatible; 
} 

You can learn more about the Bluetooth Library by reading Chapter 6, "Bluetooth," of the Palm OS Programmer's Companion, vol. II, Communications.

Functions ^TOP^

This feature set adds the following functions.

Bluetooth Library Security Functions

Bluetooth Library Utility Functions and Macros

Bluetooth Library Management Functions

Bluetooth Library Socket Functions

Bluetooth Library Service Discovery Protocol Functions

High-Density Display Feature Set ^TOP^

You can verify that this feature set is implemented by checking the version of the Window Manager. If the Window Manager version is 4 or greater, the High-Density Display feature set is supported. To check the version of the Window Manager, use this call:


err = FtrGet(sysFtrCreator, sysFtrNumWinVersion, &version); 

Upon return, if version has a value of 4 or greater, the High-Density Display feature set is present. Note that just because the High-Density Display feature set is present, it isn't necessarily being used. You may want to check the density of the screen, as follows:


WinScreenGetAttribute(winScreenDensity, &attr); 
if (attr == kDensityDouble) { 
  //the screen is double density 
} 

The 5.0 New Feature Set incorporates all of the functionality present in the High-Density Display Feature Set, so if your application is running on Palm OS Garnet you can assume that the High-Density Display Feature Set is present as well.

New Data Types ^TOP^

This feature set adds the following new data types.

Bitmap Data Types

In addition, the definition of BitmapType changed.

Font Data Types

In addition, this feature set defines a new Extended Font Resource.

Window Constants

This feature set adds a new set of Window Coordinate System Constants.

Functions ^TOP^

This feature set adds the following functions.

Bitmap Functions

System Event Manager Functions

Window Functions

1.5x Display Feature Set ^TOP^

You can verify that this feature set is implemented by checking the version of the Window Manager. If the Window Manager version is 5 or greater, the 1.5x Display feature set is supported. To check the version of the Window Manager, use this call:


err = FtrGet(sysFtrCreator, sysFtrNumWinVersion, &version); 

Upon return, if version has a value of 5 or greater, the 1.5x Display feature set is present. Note that just because the 1.5x Display feature set is present, it isn't necessarily being used. You may want to check the density of the screen, as follows:


WinScreenGetAttribute(winScreenDensity, &attr); 
if (attr == kDensityOneAndAHalf) { 
  //the screen is one-and-a-half density 
} 

New Data Types ^TOP^

This feature set adds the following new data types.

Window Constants

This feature set adds a new set of Scaling Mode Values.

Functions ^TOP^

This feature set adds the following functions.

Window Functions

Sound Stream Feature Set ^TOP^

The Sound Stream feature set adds a number of "stream" functions and constants to the Sound Manager. You can verify that this feature set is supported by checking for the Sound Manager's version number. If the Sound Manager's version feature is defined, the Sound Stream feature set is supported.

The following code shows how to check for the presence and proper version of the Sound Manger. Note that expectedSndMgrVersionNum should be replaced by the actual version number you expect (typically, sndMgrVersionNum).


UInt32 version; 
Err err; 
  
err = FtrGet(sysFileCSoundMgr, sndFtrIDVersion, &version); 
if(err){     
    // Sound Stream Feature Set not present 
} else { 
    // The Sound Stream Feature Set is present. 
    // Check version number of Sound Manager, 
    // if necessary 
    if(version == expectedSndMgrVersionNum) 
        // everything is OK 
} 

Sound Stream Data Structures and Types ^TOP^

This feature set adds the following data structures:

Sound Stream Enums and Constants ^TOP^

This feature set adds the following enums and constants:

Sound Stream Enums and Constants

Sound Stream Functions ^TOP^

This feature set adds the following functions.

Sound Stream Functions

In addition, the Sound Stream Feature Set defines the following callback functions:

SndStreamBufferCallback()

SndStreamVariableBufferCallback()

5.0 New Feature Set ^TOP^

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


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

The romVersion parameter should be greater than or equal to 0x05003000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(5,0,0,sysROMStageRelease,0) 

This feature set corresponds to version 5.0 of Palm OS Garnet.

The Palm OS Application Compatibility Environment (PACE) has its own version associated with it. You can obtain this version number with:


err = FtrGet('pace', 0, &paceVersion); 

Notifications ^TOP^

This feature set adds the following database-related notifications:

It also broadcasts the following notifications:

Functions ^TOP^

This feature set adds the following functions.

ARM-Native Functions

Virtual Ports ^TOP^

Virtual drivers and virtual serial ports are not supported on Palm OS Garnet.

Functions and Traps not Supported by PACE ^TOP^

For various reasons a number of functions and traps are not supported by PACE. The following sections list those functions, grouped according to the reason that they are not implemented.

Unimplemented "System Use Only" Functions

The following functions, which are documented as "System Use Only," are not supported by the Palm OS Application Compatibility Environment (PACE).

AlmAlarmCallback
AlmCancelAll
AlmDisplayAlarm
AlmInit
AlmTimeChange
DmInit
EvtDequeueKeyEvent
EvtGetSysEvent1
EvtInitialize
EvtSetKeyQueuePtr
EvtSetPenQueuePtr
EvtSysInit
ExgInit
FrmAddSpaceForObject
FtrInit
GrfFree
GrfInit
InsPtCheckBlink
InsPtInitialize
IntlInit
MemCardFormat
MemHandleFlags
MemHandleOwner
MemHandleResetLock1
MemHeapFreeByOwnerID
MemHeapInit
MemInit
MemInitHeapTable
MemKernelInit
MemPtrFlags
MemPtrOwner

MemPtrResetLock
MemStoreSetInfo
PenClose
PenGetRawPen
PenOpen
ScrCompressScanLine
ScrCopyRectangle
ScrDeCompressScanLine
ScrDrawChars
ScrDrawNotify
ScrLineRoutine
ScrRectangleRoutine
ScrScreenInfo
ScrSendUpdateArea
SlkProcessRPC
SlkSysPktDefaultResponse
SndInit
SysBatteryDialog
SysColdBoot
SysDoze
SysInit
SysNewOwnerID
SysSemaphoreSet
SysUILaunch
SysWantEvent
TimInit
UIInitialize
UIReset
WinAddWindow
WinRemoveWindow

1. Implemented on release ROMs but flagged as illegal on debug ROMs.

As a rule, functions and traps that are not documented should be treated as if they are unimplemented and should not be used by applications.

Implemented "System Use Only" Functions and Traps

Although marked "System Use Only," a number of functions and traps are required by applications in the ROM, by Palm Debugger, by test applications, by scripting, or by some popular applications. Because of this, the following System Use Only functions and traps are supported by PACE. Because they are intended only for system use, however, applications should do what they can to avoid using them.

AlmEnableNotification
AttnAllowClose
AttnEnableNotification
AttnIndicatorAllow
AttnIndicatorAllowed
AttnIndicatorGetBlinkPattern
AttnIndicatorSetBlinkPattern
AttnReopen
DmResetRecordStates
EvtEnqueuePenPoint
EvtGetSilkscreenAreaList()
FileReadLow
Find
FrmActiveState
FrmHandleEvent()
HwrDelay

HwrDockStatus
HwrLEDAttributes
HwrMemReadable
HwrMemWritable
HwrVibrateAttributes
MemChunkNew
MemHeapPtr
PenRawToScreen
PenScreenToRaw
SysGetAppInfo
SysLaunchConsole
SndSetDefaultVolume
SysLCDContrast
SysSetA5
SysSetPerformance
SysSleep
SysUIBusy
WinDrawWindowFrame

Obsolete Functions and Traps

The following functions are not supported by PACE because they are obsolete.

FplAdd()1
FplAToF()1
FplBase10Info()1
FplDiv()1
FplFloatToLong()1
FplFloatToULong()1

FplFToA()1
FplLongToFloat()1
FplMul()1
FplSub()1
WiCmdV32()

1. Implemented on release ROMs but flagged as illegal on debug ROMs.

'NOP' Functions and Traps

These functions and traps should not be called by applications (many are documented as "System Use Only"). Because some third-party applications do call them, for backward compatibility they act as NOPs.

FplFree()
FplInit()
HwrEnableDataWrites
HwrDisableDataWrites
HwrTimerSleep
HwrTimerWake
KeyResetDoubleTap
KeySleep
KeyWake
PenSleep
PenWake

SerReceiveISP
SrmSleep
SrmWake
SysDisableInts
SysRestoreStatus
TimHandleInterrupt
TimSleep
TimWake
WinDisableWindow
WinEnableWindow
WinInitializeWindow

Unimplemented Rare Functions and Traps

These functions and traps are only used internally by Palm OS, by serial drivers, by OEM extensions, and the like. They are not implemented by PACE.

ConGetS
ConPutS
DayDrawDays()
DayDrawDaySelector()
DbgCommSettings
DbgGetMessage
DlkDispatchRequest
DlkStartServer
DmMoveOpenDBContext
DmOpenDBWithLocale
FlashCompress

FlashErase
FlashProgram
IntlSetRoutineAddress()
MemGetRomNVParams
MemNVParams
OEMDispatch1
ResLoadForm()
SlkSetSocketListener()
SysNotifyDatabaseAdded
SysNotifyDatabaseRemoved
SysSetTrapAddress()

1. Supported if the OEM supports the trap.

5.1 New Feature Set ^TOP^

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


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

The romVersion parameter should be greater than or equal to 0x05103000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(5,1,0,sysROMStageRelease,0) 

This feature set corresponds to version 5.1 of Palm OS Garnet.

Net Library Interface Settings ^TOP^

This feature set adds the following Net Library Interface Settings:

DriverVersion
FirmwareVersion
FirmwareDate
80211Device
80211ESSID

80211AccessPointBSSID
80211AssociationStatus
80211MKKCallSign
80211CountryTest

See NetLibIFSettingGet() for a description of each of the above settings.

CPM Library ^TOP^

This feature set includes the Cryptographic Provider Manager (CPM) shared library. The CPM library isn't automatically loaded upon system boot: before making use of the CPM library you must first load it, using SysLibFind and SysLibLoad.

The CPM library defines a number of constants:

The following structures are defined as part of the CPM library:

Finally, the CPM library contains the following functions:

SSL Library ^TOP^

The 5.1 New Feature Set includes the Secure Sockets Layer (SSL) shared library. The SSL library isn't automatically loaded upon system boot: before making use of the SSL library you must first load it and open it, using code similar to the following:


Err error; 
UInt16 libRef; 
 
if ( SyLibFind( kSslDBName, &libRef ) != 0 )  
{ 
  error = SysLibLoad(kSslLibType, kSslLibCreator, &libRef); 
} 
/* error checking goes here. */ 
 
error = SslLibOpen( libRef ); 
... 

SSL Library Structures and Data Types

The SSL library defines a number of structures and data types:

SSL Library Functions

In addtion, the SSL library defines one callback function:

SSL Library Attributes and Macros

You interact with SSL attributes using the macros declared in SslLibMac.h. The attributes themselves are documented in Chapter 8, "Secure Sockets Layer (SSL)," of Palm OS Programmer's Companion, vol. II, Communications.

Pen Input Manager Feature Set ^TOP^

To see if a device contains a dynamic input area controlled by the Pen Input Manager, check the pinFtrAPIVersion feature as shown in Listing 89.1

Listing 89.1  Checking the dynamic input area feature


err = FtrGet(pinCreator, pinFtrAPIVersion, &version); 
if (!err && version) { 
   //PINS exists 
} 

Pen Input Manager Version 1.0 ^TOP^

If the value of the Pen Input Manager feature is pinAPIVersion1_0, the following functions are defined:

And the following notification is defined:

sysNotifyDisplayResizedEvent

Pen Input Manager Version 1.0 ^TOP^

If the value of the Pen Input Manager feature is pinAPIVersion1_1, the following functions are defined in addition to the ones listed in the previous section:

and the winDisplayChangedEvent is defined as well.

Graffiti 2 Feature Set ^TOP^

Version 4.1.2 of Palm OS and version 5.2 of Palm OS Garnet use the Graffiti® 2 handwriting recognition engine, which is based on Jot® technology. The Graffiti Manager still provides the interface to the new engine; however, some functions have been deprecated.

You can check that this feature set is implemented by checking for the existence of the Graffiti 2 dynamic ID, which is set by the Graffiti 2 library. Use code similar to the following:


if (!FtrGet('grft', 1110, &g2DynamicID) || 
  !FtrGet('grf2', 1110, &g2DynamicID)) {
    // Graffiti 2 feature set is present. 
} 

Note that the Graffiti 2 creator code changed between version 4.1.2 and version 5.2, so both FtrGet() calls are necessary.

Deprecated Functions

The following functions are deprecated if this feature set is present:

In addition, the capsLock and numLock parameters to GrfSetState() and GrfGetState() do not apply for the Graffiti 2 recognizer.

Note that the Graffiti Shift Indicator APIs work as normal.

5.3SC New Feature Set ^TOP^

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


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

The romVersion parameter should be greater than or equal to 0x05303000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(5,3,0,sysROMStageRelease,0) 

This feature set corresponds to version 5.3SC of Palm OS Garnet.

Functions ^TOP^

This feature set adds the following functions.

Glue Functions

LmGlueGetSystemLocale()

Notifications ^TOP^

This feature set adds the following notifications.

sysNotifyGsiDrawIndicator

sysNotifyInputAreaDrawingEvent

sysNotifyInputAreaPendownEvent

sysNotifySelectDay

Existing Functions that Changed ^TOP^

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

The capsLock and numLock parameters to GrfSetState() and GrfGetState() now apply to the Graffiti 2 recognizer. In the Palm OS Garnet operating system, Graffiti 2 was introduced in version 5.2. In that initial implementation, these two parameters did not apply.

In version 5.2, GrfInitState() was deprecated and nonfunctional. This function is now supported again in version 5.3SC. (Actually, it was reinstated in version 5.2.1 and later.)

In the following functions, the numOfElements parameter was changed to a UInt16 type: SysBinarySearch, SysInsertionSort, and SysQSort.

5.4 New Feature Set ^TOP^

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


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

The romVersion parameter should be greater than or equal to 0x05403000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(5,4,0,sysROMStageRelease,0) 

This feature set corresponds to version 5.4 of Palm OS Garnet.

New Data Types, Enums, Constants ^TOP^

The following data types, enums, and constants are new. They support socket notifications:

For details on socket notices and socket notifications, see Chapter 7, "Socket Notices," in Palm OS Programmer's API Reference.

Existing Functions that Changed ^TOP^

The following function that existed prior to 5.4 has changed in release 5.4:

The optionValueP parameter of NetLibSocketOptionSet()is now of type NetSocketNoticeType when you are also passing in parameters netSocketOptLevelSocket and netSocketOptSocketNotice. This call is made when you are registering to receive socket notifications.

Other Changes ^TOP^

Two former Palm OS limits are no longer dictated by PalmSource, Inc: the maximum number of simultaneous active sockets and the maximum size of the stack available to Net Library. Licensees now decide on the number of sockets and the stack size they deem appropriate.

Bluetooth Sleep and Wake Scheduling Feature Set ^TOP^

You can check that this feature set is implemented by checking for the sysFtrBtSupportsScheduledWakeup feature. Use this FtrGet() call:


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

If Bluetooth sleep and wake scheduling is available, the value parameter will be non-zero and the returned error should also be zero (for no error).

For more information about sleep and wake scheduling, see Chapter 6, "Radio Power Management."

ARM Debug Nub Feature Set ^TOP^

You can check that this feature set is implemented by checking for the adnFtrCreator feature. Use this FtrGet() call:


err = FtrGet(adnFtrCreator, adnFtrNumVersion, &value); 

If the ARM debug nub feature set is present, the returned error should be errNone.

ARM Debug Nub Functions and Macros

Palm OS Cobalt Feature Set ^TOP^

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


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

The romVersion parameter should be greater than or equal to 0x06003000, which can be constructed using the sysMakeROMVersion macro:


sysMakeROMVersion(6,0,0,sysROMStageRelease,0) 

This feature set corresponds to version 6.0.1 of Palm OS Cobalt.

PACE ^TOP^

The Palm Application Compatibility Environment, or PACE, is a 68K emulator that supports execution of well-behaved 68K-based Palm OS applications on devices that use an ARM processor.

PACE allows the majority of existing 68K-based Palm OS applications to run on devices that use an ARM processor. Users can beam an application from a 68K device to an ARM-based device and run the application. The Palm Application Compatibility Environment helps provide a migration path for developers. The developer can continue to use existing 68K-based tools to build their application.


NOTE: Both Palm OS Garnet and Palm OS Cobalt use PACE to provide 68K emulation. PACE relies on the underlying operating system to provide much of its functionality. Because Palm OS Garnet is architecturally very similar to 68K-native versions of Palm OS, the version of PACE running on Palm OS Garnet provides a high degree of compatibility with a Palm Powered device containing a 68K-family processor. Palm OS Cobalt, however, is architecturally very different than all earlier Palm OS versions. Reflecting this, PACE on Palm OS Cobalt is not as compatible as PACE on Palm OS Garnet. So that your 68K applications will run on the widest range of Palm Powered devices, take careful note of the following sections which describe the behavior of PACE on Palm OS Cobalt.

Design Objectives ^TOP^

The Palm Application Compatibility Environment is designed to allow well-behaved 68K applications to run at 68K speeds or faster on an ARM-based device, with minimum code and memory overhead. A well-behaved application is one that:

  • only uses documented Palm OS APIs
  • does not access hardware directly
  • does not access the display memory directly
  • does not access low memory globals
  • does not access the fields of Palm OS structures directly
  • runs on Palm OS Emulator with a debug Palm OS Garnet ROM without encountering any errors

Performance

Performance of a 68K application varies greatly depending on how much time it spends executing 68K instructions compared to the time it spends calling Palm OS functions.

Code that consists only of 68K instructions, such as a prime number generator, will run slower than an ARM-native version of the same code since the 68K instructions are emulated. For reference, the time it takes to execute emulated 68K instructions on a 70 MHz ARM device is roughly the same as the time it takes to execute the same instructions on a Palm Vx device. Most applications spend a great deal of time inside operating system calls, however, and those calls execute at the full speed of the ARM processor (note that there may be additional overhead for some Palm OS functions, depending on how close the native function's API is to the 68K API). Thus most 68K applications running under PACE will actually run much faster than they would on a device with a 68K processor.

Developer SDK

Because an application that runs under PACE is like any other 68K application, when writing applications to run under PACE you continue to use the tools and headers you would use to create a 68K-based Palm OS application.

Applications are no longer allowed access to many internal, publicly-defined structures (such as the ControlType structure). To make up for this, some accessor functions were added in Palm OS 4.0, and additional accessor functions were added to the Palm OS glue library shipped with the Palm OS Garnet SDK.

The 68K Palm debugger and other tools which depend on the 68K debugger APIs (such as the Metrowerks debugger) are supported by the Palm Application Compatibility Environment.

API Restrictions ^TOP^

Most well-behaved applications run under the Palm OS Garnet version of PACE with no problems. Due to differences in the underlying operating system in Palm OS Cobalt, however, PACE is somewhat more restricting on Palm OS Cobalt devices. The following sections detail those restrictions.

Deprecated APIs

Very few deprecated APIs (such as CategoryEditV20()) are supported for native ARM applications. The Palm Application Compatibility Environment still supports these deprecated APIs, unless they are listed in Table 89.2.

Unsupported APIs

A number of Palm OS APIs are not supported by PACE. These are APIs that either are documented as private, are internal-only APIs (yet appear in public header files), or are APIs that developer support has advised developers to not use. A list of unsupported APIs can be found under "Unsupported Palm OS Functions."

Card Number Argument

The native ARM version of Palm OS no longer has the concept of memory cards. For this reason, the card number concept is faked for emulated 68K applications. If an application calls MemNumCards(), a value of 1 is always returned. If an application calls any function that takes cardNum as an argument and the value for cardNum is not zero, an error is returned to the application.

Record Unique IDs

In previous versions of Palm OS, only 24 bits of a record's unique ID were stored in the record header. In Palm OS Cobalt, however, all 32 bits are unique. The function that returns a record's unique ID returns a 32-bit value; to ensure the greatest degree of compatiblity an application should save all 32 bits of the record's unique ID, and not truncate the result to 24 bits.

Effect of Calling an Unsupported or Deprecated Palm OS Function

If a 68K application calls an unsupported or deprecated Palm OS function, an alert is displayed and the application is terminated. The alert contains the message "An error occurred in the application you are using. Note the error code and contact the developer of this application" followed by an error number in parentheses. When the user presses the OK button, the application is forced to exit. The debug version of this error alert has two more numbers displayed (to help you pinpoint the problem) and a Cancel button. If you tap the Cancel button, PACE tries to connect to the 68K Palm Debugger so you can determine why and where the error is occurring.

Unsupported Palm OS Functions

Table 89.2 is a list of Palm OS functions that are not supported by PACE in Palm OS Cobalt. The following are the reasons why these functions are not supported.

Documented as "System Use Only"
These functions are documented as "System Use Only" in the Palm OS Programmer's API Reference and thus should never have been called by applications.
Should have been documented as "system use only"
These functions were intended for internal PalmSource use only but were documented.
Obsolete
These functions are not implemented because they have long been obsolete. Current Palm OS applications should no longer be using them.
Implemented as a "NOP" function
Typically, these are functions that should not have been called by applications. Because some applications may call them, however, PACE supports them. However, they do nothing and simply return.
Rarely-used function
Functions that are only used internally by Palm OS, by serial drivers, or by OEM extensions. They are not functions that an application would use. PACE does not implement these functions.
Unimplemented in Palm OS Cobalt
Functions that were supported by PACE in Palm OS Garnet but are no longer supported by PACE in Palm OS Cobalt. The vast majority of these are intended for system use only, and the remaining few are very rarely used by applications.

Table 89.2  Unsupported Palm OS functions 

Function

Unsupported because...

AlmAlarmCallback()

Documented as "System Use Only"

AlmCancelAll()

Documented as "System Use Only"

AlmDisplayAlarm()

Documented as "System Use Only"

AlmTimeChange()

Documented as "System Use Only"

ConGetS()

Rarely-used function

ConPutS()

Rarely-used function

DayDrawDays()

Rarely-used function

DayDrawDaySelector()

Rarely-used function

DayHandleEvent()

Should have been documented as "System Use Only"

DbgCommSettings()

Rarely-used function

DbgGetMessage()

Rarely-used function

DlkControl()

Rarely-used function

DlkDispatchRequest()

Rarely-used function

DlkStartServer()

Rarely-used function

DmInit()

Documented as "System Use Only"

EvtDequeueKeyEvent()

Documented as "System Use Only"

EvtEnqueuePenPoint()

Was documented as "System Use Only." In Palm OS Cobalt, returns sysErrNotAllowed. On debug ROMs, displays a fatal alert.

EvtGetPenBtnList()

Rarely-used function

EvtGetSilkscreenAreaList()

Rarely-used function

EvtGetSysEvent()

Documented as "System Use Only"

EvtKeyQueueSize()

In Palm OS Cobalt, returns sysErrNotAllowed. On debug ROMs, displays a fatal alert.

EvtPenQueueSize()

In Palm OS Cobalt, returns sysErrNotAllowed. On debug ROMs, displays a fatal alert.

EvtProcessSoftKeyStroke()

In Palm OS Cobalt, returns sysErrNotAllowed. On debug ROMs, displays a fatal alert.

EvtSetKeyQueuePtr()

Documented as "System Use Only"

EvtSetPenQueuePtr()

Documented as "System Use Only"

EvtSysInit()

Documented as "System Use Only"

ExpCardGetSerialPort()

Unimplemented in Palm OS Cobalt

ExpCardInserted()

Documented as "System Use Only"

ExpCardRemoved()

Documented as "System Use Only"

ExpSlotDriverInstall()

Unimplemented in Palm OS Cobalt

ExpSlotDriverRemove()

Unimplemented in Palm OS Cobalt

ExpSlotLibFind()

Unimplemented in Palm OS Cobalt

ExpSlotRegister()

Documented as "System Use Only"

ExpSlotUnregister()

Documented as "System Use Only"

FplAdd()

Obsolete

FplAToF()

Obsolete

FplBase10Info()

Obsolete

FplDiv()

Obsolete

FplFloatToLong()

Obsolete

FplFloatToULong()

Obsolete

FplFree()

Implemented as a "NOP" function

FplFToA()

Obsolete

FplInit()

Implemented as a "NOP" function

FplLongToFloat()

Obsolete

FplMul()

Obsolete

FplSub()

Obsolete

FrmAddSpaceForObject()

Documented as "System Use Only"

FtrInit()

Documented as "System Use Only"

GrfFree()

Documented as "System Use Only"

GrfInit()

Documented as "System Use Only"

InsPtCheckBlink()

Documented as "System Use Only"

InsPtEnable()

Implemented as a "NOP" function

InsPtEnabled()

Implemented as a "NOP" function

InsPtGetHeight()

Implemented as a "NOP" function

InsPtGetLocation()

Implemented as a "NOP" function

InsPtInitialize()

Documented as "System Use Only"

InsPtSetHeight()

Implemented as a "NOP" function

InsPtSetLocation()

Implemented as a "NOP" function

KbdDraw()

Documented as "System Use Only"

KbdErase()

Documented as "System Use Only"

KbdGetLayout()

Documented as "System Use Only"

KbdGetPosition()

Documented as "System Use Only"

KbdGetShiftState()

Documented as "System Use Only"

KbdHandleEvent()

Documented as "System Use Only"

KbdSetLayout()

Documented as "System Use Only"

KbdSetPosition()

Documented as "System Use Only"

KbdSetShiftState()

Documented as "System Use Only"

KeyboardStatusFree()

Documented as "System Use Only"

KeyboardStatusNew()

Documented as "System Use Only"

MemCardFormat()

Documented as "System Use Only"

MemHandleFlags()

Documented as "System Use Only"

MemHandleOwner()

Documented as "System Use Only"

MemHandleResetLock()

Documented as "System Use Only"

MemHeapFreeByOwnerID()

Documented as "System Use Only"

MemHeapInit()

Documented as "System Use Only"

MemInit()

Documented as "System Use Only"

MemInitHeapTable()

Documented as "System Use Only"

MemKernelInit()

Documented as "System Use Only"

MemPtrFlags()

Documented as "System Use Only"

MemPtrOwner()

Documented as "System Use Only"

MemPtrResetLock()

Documented as "System Use Only"

MemSemaphoreRelease()

Documented as "System Use Only"

MemSemaphoreReserve()

Documented as "System Use Only"

MemStoreSetInfo()

Documented as "System Use Only"

OmGetIndexedLocale()

Unimplemented in Palm OS Cobalt

OmGetNextSystemLocale()

Unimplemented in Palm OS Cobalt

OmSetSystemLocale()

Unimplemented in Palm OS Cobalt

PenCalibrate()

Implemented as a "NOP" function

PenClose()

Documented as "System Use Only"

PenGetRawPen()

Documented as "System Use Only"

PenOpen()

Documented as "System Use Only"

PenRawToScreen()

Was documented as "System Use Only." In Palm OS Cobalt, returns sysErrNotAllowed. On debug ROMs, displays a fatal alert.

PenResetCalibration()

Implemented as a "NOP" function

PenScreenToRaw()

Was documented as "System Use Only." In Palm OS Cobalt, returns sysErrNotAllowed. On debug ROMs, displays a fatal alert.

PenSleep()

Was documented as "System Use Only." In Palm OS Cobalt this is implemented as a "NOP" function.

PenWake()

Was documented as "System Use Only." In Palm OS Cobalt this is implemented as a "NOP" function.

ResLoadForm()

Rarely-used function

SerReceiveISP()

Implemented as a "NOP" function

SlkProcessRPC()

Documented as "System Use Only"

SlkSetSocketListener()

Rarely-used function

SlkSysPktDefaultResponse()

Documented as "System Use Only"

SndInit()

Documented as "System Use Only"

SndInterruptSmfIrregardless()

Rarely-used function

SndPlaySmfIrregardless()

Rarely-used function

SndPlaySmfResourceIrregardless()

Rarely-used function

SrmOpenBackground()

Rarely-used function

SrmSleep()

Implemented as a "NOP" function

SrmWake()

Implemented as a "NOP" function

SysBatteryDialog()

Documented as "System Use Only"

SysColdBoot()

Documented as "System Use Only"

SysDisableInts()

Was documented as "System Use Only." In Palm OS Cobalt this is implemented as a "NOP" function.

SysDoze()

Documented as "System Use Only"

SysFatalAlertInit()

Undocumented "system use only"function.

SysInit()

Documented as "System Use Only"

SysLaunchConsole()

Documented as "System Use Only"

SysNewOwnerID()

Documented as "System Use Only"

SysNotifyBroadcastFromInterrupt()

Rarely-used function

SysRestoreStatus()

Was documented as "System Use Only." In Palm OS Cobalt this is implemented as a "NOP" function.

SysSemaphoreSet()

Documented as "System Use Only"

SysSetTrapAddress()

Rarely-used function

SysUILaunch()

Documented as "System Use Only"

SysUnimplemented()

Documented as "System Use Only"

TimInit()

Documented as "System Use Only"

VFSInstallFSLib()

Unimplemented in Palm OS Cobalt

VFSRemoveFSLib()

Unimplemented in Palm OS Cobalt

WinAddWindow()

Documented as "System Use Only"

WinDisableWindow()

Was documented as "System Use Only." In Palm OS Cobalt this is implemented as a "NOP" function.

WinEnableWindow()

Was documented as "System Use Only." In Palm OS Cobalt this is implemented as a "NOP" function.

WinGetFirstWindow()

Rarely-used function

WinInitializeWindow()

Was documented as "System Use Only." In Palm OS Cobalt this is implemented as a "NOP" function.

WinMoveWindowAddr()

Documented as "System Use Only"

WinRemoveWindow()

Documented as "System Use Only"

WinScreenInit()

Documented as "System Use Only"

Accessing the PIM Application Databases ^TOP^

Some 68K applications access the PIM application databases. In Palm OS Cobalt the PIM applications are ARM-native applications, and those applications now use schema databases to hold application data. Although the "classic" PIM application databases are no longer present, PACE does what it can to "do the right thing" when it detects that a 68K application is attempting to access a PIM application database.


NOTE: The PIM database access solution described here depends entirely on the presence of the ARM-native PIM applications. As well, those applications must correctly support the sysAppLaunchCmdImportRecord, sysAppLaunchCmdExportRecord and sysAppLaunchCmdDeleteRecord launch commands. PACE further assumes that the database names, database schema names, and field IDs haven't changed (additional fields may be present, however, and the field order can be changed).

When an application tries to access a 68K PIM application database—either to open or to find it—PACE creates the 68K database, opens it, initializes its application info block (using category names from the corresponding native PIM app) and creates a cache of all records in the corresponding ARM-native PIM application database. Each cache entry contains the following information:

  • the unique ID of the native record
  • handle to the 68K record
  • index of the 68K record
  • category that the record belongs to
  • attribute flags (dirty and deleted)

Each entry is initialized with the unique ID and category information. All other fields are cleared.

When the application then tries to read a record (for example, by calling DmQueryRecord() or DmGetRecord()), PACE sends a sysAppLaunchCmdExportRecord request to the native application. In response, the native application returns the record in vCard format. PACE converts the vCard information into a 68K PIM application record and stores that record into the 68K PIM application database that was created when the database was opened. The index and record handle of this record are stored in the cache; any further requests for the record will return the record handle from the cache.

If the application creates a new record, PACE creates a record in the 68K PIM application database, adds an entry to the cache, and initializes the cache entry's unique ID to NULL.

When the application writes to the new record, PACE marks the record in the cache as "dirty" so that it will be written back to the ARM-native PIM application database when the database is flushed. At that time, PACE converts the 68K record to its vCard representation and then sends a sysAppLaunchCmdImportRecord request to the native application. Records are flushed:

  • when a database is closed
  • whenever another record is created
  • before a unique ID is returned to an application (in response to a call to DmGetRecordInfo()).

When an application deletes a PIM database record, PACE marks the record in the cache as "deleted" and sends a sysAppLaunchCmdDeleteRecord request to the native application.

Once the 68K application closes the PIM application database, PACE flushes any dirty records that have yet to be written, frees up memory allocated for the cache, and closes and deletes the 68K PIM application database.

The two functions DmFindDatabase() and DmGetNextDatabaseByTypeCreator() have the side effect of leaving the 68K PIM application database around. To clean up these stray databases, PACE deletes any existing 68K PIM application databases whenever a 68K application exits. Note that if you call DmOpenDatabase() after locating a database with either of these two functions, and later call DmCloseDatabase(), the database will be deleted when the close function is called.

Although DmFindDatabase() leaves the 68K PIM application database around, other Data Manager calls may cause PACE to delete it. Because of this, if you are going to open a PIM application database by calling DmFindDatabase() followed by DmOpenDatabase() (as opposed to the more common method of using DmOpenDatabaseByTypeCreator()), avoid making other Data Manager calls on the PIM application database between the call to DmFindDatabase() and DmOpenDatabase().

Limitations

The PIM application database access solution provided by PACE has a number of limitations. For one, not all database access functions are supported. Here is a list of the known limitations:

  • It can be slow. The ARM-native PIM applications are sub-launched for each PIM database read, write, or delete.
  • Category changes are not reflected back to the native PIM application. Category information should be treated as read-only.
  • All three "varieties" of record delete—DmDeleteRecord(), DmRemoveRecord() and DmArchiveRecord()—become requests for the native PIM application to delete the record.
  • Some things in the application info blocks are "hard-coded." For example, the ToDo sort order is always priority/due date and the Address Book labels are hard-coded to English text labels.
  • The totalBytes and dataBytes sizes returned from DmDatabaseSize() come from the 68K database and thus are usually wrong. They would only be correct if every record has been read in from the ARM-native PIM application database.
  • Some database record access functions are not supported, including DmRemoveSecretRecords(), DmMoveCategory() and DmDeleteCategory().
  • There are some limitations with private records. Private records will be masked or hidden when a 68K PIM application is run, but changing the "maskedness" or "hiddenness" has no effect while running the 68K PIM application.
  • Because records are not immediately written to the ARM-native PIM application databases, some data may be lost while running a 68K PIM application replacement if the system is reset while the application is running.

Summary of PIM Database Access APIs

Table 89.3 lists those functions for which PACE checks to see if a PIM application database is being accessed. If so, PACE acts as described in the second column.

Table 89.3  Functions that PACE monitors for PIM database access 

Function

How treated by PACE 

CategoryCreateList()

Calls through to the native OS.

CategoryEdit()

Calls through to the native OS.

CategoryFind()

Calls through to the native OS.

CategoryFreeList()

Calls through to the native OS.

CategoryGetName()

Calls through to the native OS.

CategoryGetNext()

Calls through to the native OS.

CategorySelect()

Calls through to the native OS.

CategorySetName()

Calls through to the native OS.

DmArchiveRecord()

PACE handles calls to this function.

DmAttachRecord()

PACE handles calls to this function.

DmCloseDatabase()

PACE handles calls to this function.

DmDatabaseInfo()

Calls through to the native OS.

DmDatabaseProtect()

Calls through to the native OS. Note that applications are not expected to call this function with a PIM database.

DmDatabaseSize()

PACE handles calls to this function.

DmDeleteCategory()

Not supported when accessing a PIM database. sysErrNotAllowed is returned.

DmDeleteDatabase()

Calls through to the native OS. Note that applications are not expected to call this function with a PIM database.

DmDeleteRecord()

PACE handles calls to this function.

DmDetachRecord()

PACE handles calls to this function.

DmFindDatabase()

PACE handles calls to this function.

DmFindRecordByID()

PACE handles calls to this function.

DmFindRecordByOffsetInCategory()

PACE handles calls to this function.

DmFindSortPosition()

PACE handles calls to this function.

DmGetAppInfoID()

Calls through to the native OS.

DmGetDatabaseLockState()

Calls through to the native OS. Note that applications rarely call this function with a PIM database.

DmGetNextDatabaseByTypeCreator()

PACE handles calls to this function.

DmGetRecord()

PACE handles calls to this function.

DmInsertionSort()

PACE handles calls to this function.

DmMoveCategory()

Not supported when accessing a PIM database. sysErrNotAllowed is returned.

DmMoveRecord()

PACE handles calls to this function.

DmNewHandle()

PACE handles calls to this function.

DmNewRecord()

PACE handles calls to this function.

DmNextOpenDatabase()

Calls through to the native OS. Note that applications rarely call this function with a PIM database.

DmNumDatabases()

PACE handles calls to this function.

DmNumRecordsInCategory()

PACE handles calls to this function.

DmOpenDatabase()

PACE handles calls to this function.

DmOpenDatabaseByTypeCreator()

PACE handles calls to this function.

DmOpenDatabaseInfo()

Calls through to the native OS.

DmOpenDBNoOverlay()

PACE handles calls to this function.

DmPositionInCategory()

PACE handles calls to this function.

DmQueryNextInCategory()

PACE handles calls to this function.

DmQueryRecord()

PACE handles calls to this function.

DmQuickSort()

PACE handles calls to this function.

DmRecordInfo()

PACE handles calls to this function.

DmReleaseRecord()

PACE handles calls to this function.

DmRemoveRecord()

PACE handles calls to this function.

DmRemoveSecretRecords()

Not supported when accessing a PIM database. sysErrNotAllowed is returned.

DmResetRecordStates()

(System Use Only function) Calls through to the native OS. Note that applications rarely call this function with a PIM database.

DmResizeRecord()

PACE handles calls to this function.

DmSetDatabaseInfo()

Calls through to the native OS.

DmSetRecordInfo()

PACE handles calls to this function.

New Functions and Macros ^TOP^

The Palm OS Cobalt feature set adds the following functions.

Certificate Manager Functions

Certificate Manager Macros

New Data Structures and Constants ^TOP^

The following data structures are new. They support the Certificate Manager:

Certificate Manager Data Structures

A number of constants are also defined in the header file that declares the Certificate Manager APIs. They are organized into the following categories:

Existing Functions that Changed ^TOP^

The coordinate scaling algorithm changed slightly for the following functions:

Window Manager Functions

One-Handed Navigation Feature Set ^TOP^

You can check that this feature set is implemented by checking for the presence of the the sysFtrNumFiveWayNavVersion feature. Use this FtrGet() call:


err = FtrGet(sysFtrCreator, sysFtrNumFiveWayNavVersion, &value); 
if (err == errNone){ 
   // One-handed navigation is supported 
} else { 
   // No support for one-handed navigation 
} 

On Handspring devices from palmOne (such as the Treo 600), you use a similar technique but check for the hsFtrIDNavigationSupported instead. For convenience, the Palm OS Glue library—which contains "glue" equivalents of a number of one-handed navigation functions that will run on devices where either feature is present—contains a function that will check for the presence of either feature. If FrmGlueNavIsSupported() returns true, one or the other features is present on the device. Note, however, that you should use the Palm OS Glue versions of the FrmNav... functions since the functions declared in Form.h only work on devices where the sysFtrNumFiveWayNavVersion feature is present.

New Functions and Macros ^TOP^

The One-Handed Navigation feature set adds the following functions.

Form Functions

New Data Structures and Types ^TOP^

The following data structures and types are new. They support the one-handed navigation feature:

Form Data Structures and Types

In addition this feature set contains a number of constants specific to the one-handed navigation feature.