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
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:
|
Functions
This feature set adds the following functions:
Existing Functions that Changed
Several functions that existed in 1.0 were changed in 2.0:
|
|
|
|
|
|
|
|
|
|
|
|
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 aFldSetText
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:
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 greater than or equal to 0x03003000
, which can be constructed using the sysMakeROMVersion
macro:
sysMakeROMVersion(3,0,0,sysROMStageRelease,0)
Launch Codes
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
This feature set adds the following font:
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, 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
Two functions that existed in 2.0 were changed in 3.0:
|
|
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, 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:
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 greater than or equal to 0x03103000
, which can be constructed using the sysMakeROMVersion
macro:
sysMakeROMVersion(3,1,0,sysROMStageRelease,0)
Functions
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
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()
andChrHorizEllipsis()
to return the appropriate character regardless of the character map. InPalmOSGlue.lib
, these two macros are namedTxtGlueGetNumericSpaceChar
andTxtGlueGetHorizEllipsisChar
, 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 withpreferenceDataVerLatest
. - Character variables are now two bytes long. The type
WChar
defines a character variable. - The
keyDownEvent
structure'schr
field (which contains the input character) has been changed from aWord
to aWChar
. - The string manager functions
StrChr()
andStrStr()
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. TheUnderlineModeType
enum defined inWindow.h
defines the possible values for the underline attribute. - The use of the
DmGetNextDatabaseByTypeCreator()
onlyLatestVers
parameter changed in 3.1. IfonlyLatestVers
istrue
, you only receive one matching database for each type/creator pair. In version 3.0 and earlier, you could receive multiple matching databases ifonlyLatestVers
wastrue
. 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 greater than or equal to 0x03203000
, which can be constructed using the sysMakeROMVersion
macro:
sysMakeROMVersion(3,2,0,sysROMStageRelease,0)
Functions
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
Two functions that existed in 3.0 were changed in 3.2:
|
|
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 interceptAlmDisplayAlarm
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, 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
This feature set adds the following functions:
Text Manager Functions
Other Functions
Removed Functions and Macros
If the international feature set exists, then the following functions and macros are no longer available:
|
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, vol. I.
Wireless Internet Feature Set
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
.
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
This feature set adds the following launch codes:
|
Events
This feature set adds the following events:
This feature set also adds the following keyDownEvent
key codes:
These key codes are described in the section Wireless 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, vol. II, Communications.
New Serial Manager Feature Set
The New Serial Manager feature set has two different versions.
New Serial Manager Feature Set Version 1
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
New Serial Manager Feature Set Version 2
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 is0x04003000
, which can be constructed using thesysMakeROMVersion
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
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
This feature set adds the following functions:
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 greater than or equal to 0x03503000
, which can be constructed using the sysMakeROMVersion
macro:
sysMakeROMVersion(3,5,0,sysROMStageRelease,0)
Launch Codes
This feature set adds the following launch codes:
Events
This feature set adds the following events:
Functions
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
The following functions that existed prior to 3.5 have changed in release 3.5:
|
|
|
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 theEventType
structure. ThetapCount
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
andctlSelectEvent
have avalue
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 akeyDownEvent
with thevchrMenu
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
toSysEvent.h
. - The
winEnterEvent
is now not generated untilFrmDrawForm()
is called. Make sure to draw your form in response tofrmOpenEvent
, notwinEnterEvent
. -
EvtSetNullEventTick()
is now a function. In previous releases it was a macro.
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 toFrmDrawForm
, not before. If you have drawn before the call toFrmDrawForm
, your changes are lost. On debug ROMs, the window handle is invalid untilFrmDrawForm
is called so that draws beforeFrmDrawForm
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
orlongStrLength
debugging bytes, depending on thedateFormat
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 inDateTime.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()
- Dynamic heap
The dynamic heap is now sized based on the amount of memory available to the system.
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
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
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
This feature set adds the following launch codes:
Notifications
This feature set adds the following notifications:
Functions
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
The following functions that existed prior to 4.0 have changed in release 4.0:
|
|
|
|
|
|
Expansion Manager Feature Set
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.
UInt32expMgrVersion
; 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
This feature set adds the following functions.
Expansion Manager Functions
VFS Manager Feature Set
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
This feature set adds the following functions.
VFS Manager Functions
Bluetooth Library Feature Set
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
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
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
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
This feature set adds the following functions.
Bitmap Functions
System Event Manager Functions
Window Functions
1.5x Display Feature Set
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
This feature set adds the following new data types.
Window Constants
This feature set adds a new set of Scaling Mode Values.
Functions
This feature set adds the following functions.
Window Functions
Sound Stream Feature Set
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
This feature set adds the following data structures:
Sound Stream Enums and Constants
This feature set adds the following enums and constants:
Sound Stream Enums and Constants
Sound Stream Functions
This feature set adds the following functions.
Sound Stream Functions
In addition, the Sound Stream Feature Set defines the following callback functions:
SndStreamVariableBufferCallback()
5.0 New Feature Set
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
This feature set adds the following database-related notifications:
It also broadcasts the following notifications:
Functions
This feature set adds the following functions.
ARM-Native Functions
Virtual Ports
Virtual drivers and virtual serial ports are not supported on Palm OS Garnet.
Functions and Traps not Supported by PACE
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).
|
|
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.
|
|
Obsolete Functions and Traps
The following functions are not supported by PACE because they are obsolete.
|
|
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.
|
|
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.
|
|
1. Supported if the OEM supports the trap.
|
5.1 New Feature Set
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
This feature set adds the following Net Library Interface Settings:
|
|
See NetLibIFSettingGet()
for a description of each of the above settings.
CPM Library
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:
- AP Capability Constants
- Block Encryption Mode Constants
- Cipher Algorithm Constants
- Export Encoding Constants
- Hashing Algorithm Constants
- Key Class Constants
- Key Usage Constants
- Plaintext Padding Constants
The following structures are defined as part of the CPM library:
Finally, the CPM library contains the following functions:
SSL Library
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
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
If the value of the Pen Input Manager feature is pinAPIVersion1_0
, the following functions are defined:
And the following notification is defined:
Pen Input Manager Version 1.0
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
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
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
This feature set adds the following functions.
Glue Functions
Notifications
This feature set adds the following notifications.
sysNotifyInputAreaDrawingEvent
sysNotifyInputAreaPendownEvent
Existing Functions that Changed
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
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
The following data types, enums, and constants are new. They support socket notifications:
-
NetSocketNoticeType
-
SysNotifyNetSocketType
See "Socket Notification Specific Data" -
NoticeTypeEnum
- netSocketNotice. . . constants
See "Socket Notice Trigger Conditions."
For details on socket notices and socket notifications, see Chapter 7, "Socket Notices," in Palm OS Programmer's API Reference.
Existing Functions that Changed
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
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
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
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
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
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
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
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
Accessing the PIM Application Databases
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()
andDmArchiveRecord()
—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
anddataBytes
sizes returned fromDmDatabaseSize()
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()
andDmDeleteCategory()
. - 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
New Functions and Macros
The Palm OS Cobalt feature set adds the following functions.
Certificate Manager Functions
Certificate Manager Macros
New Data Structures and Constants
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:
- X509Cert Element Fields
- RSA Element Fields
- RDN Element Fields
- X509Extensions Element Fields
- Data Types
- Certificate Formats
- Certificate Manager Error Codes
- Certificate Verification Failure Codes
Existing Functions that Changed
The coordinate scaling algorithm changed slightly for the following functions:
Window Manager Functions
One-Handed Navigation Feature Set
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
The One-Handed Navigation feature set adds the following functions.
Form Functions
New Data Structures and Types
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.