< Home < Developers < Development Support < Documentation

## B Compatibility Guide

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference 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 |  |  |  | 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 PalmTM 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 ## 2.0 New Feature Set You can check that this feature set is implemented by checking that the system version is 2.0 or higher. Use this FtrGet call:
    err = FtrGet(sysFtrCreator,
    sysFtrNumROMVersion, &romversion);
The romversion parameter should be 0x02003000 or greater. ## Launch Codes This feature set adds the following launch codes: #####
sysAppLaunchCmdLookup sysAppLaunchCmdPanelCalledFromApp sysAppLaunchCmdReturnFromPanel sysAppLaunchCmdSystemLock
## Functions This feature set adds the following functions: #####
CategoryInitialize | CategorySetName
DmDeleteCategory | DmDatabaseProtect
EvtAddUniqueEventToQueue EvtSysEventAvail | EvtEventAvail
FldGetNumberOfBlankLines FldSetInsertionPoint | FldGetScrollValues
FntGetScrollValues FntWordWrapReverseNLines | FntWordWrap
FrmPointInTitle FrmSetObjectBounds | FrmSetMenu
KeySetMask | LocGetNumberSeparators
LstScrollList | LstGetVisibleItems
MemCmp | MenuSetActiveMenuRscID
PhoneNumberLookup |
PrefSetPreference | PrefGetPreference
SclDrawScrollBar SclHandleEvent | SclGetScrollBar SclSetScrollBar
SerControl |
StrDelocalizeNumber StrNCaselessCompare StrNCompare StrPrintF | StrLocalizeNumber StrNCat StrNCopy StrVPrintF
SysBinarySearch SysCreatePanelList SysGraffitiReferenceDialog SysStringByIndex | SysCreateDataBaseList SysErrString SysLibLoad SysTicksPerSecond
TblHasScrollBar TblSetColumnEditIndicator | TblSetBounds TblSetRowStaticHeight
WinSetWindowBounds |
## Existing Functions that Changed Several functions that existed in 1.0 were changed in 2.0: #####
CategoryCreateList (old function renamed CategoryCreateListV10)
CategoryEdit (old function renamed CategoryEditV10)
CategoryFreeList (old function renamed CategoryFreeListV10)
CategorySelect (old function renamed CategorySelectV10)
SelectDay (old function renamed SelectDayV10)
DmFindSortPosition (old function renamed DmFindSortPositionV10)
PrefGetAppPreferences (old function renamed PrefGetAppPreferencesV10)
PrefOpenPreferenceDB (old function renamed PrefOpenPreferenceDBV10)
PrefSetAppPreferences (old function renamed PrefSetAppPreferencesV10)
SerReceive (old function renamed SerReceive10)
SerSend (old function renamed SerSend10)
SysKeyboardDialog (old function renamed SysKeyboardDialogV10)
## Other Changes As a rule, all Palm OS applications developed with the 1.0 SDK should run error-free on the latest device. There are two possible pitfalls for 1.0 applications: fldChangedEvent Change-The operating system now correctly sends a fldChangedEvent whenever a field object is changed. Previously, the event was at times not sent, especially when a FldSetText operation was performed. If your application doesn't catch the events that are now sent, it may have problems. Non-standard tools-If your application was not developed with Metrowerks Code Warrior for the Palm OS, it may run into problems. One known problem can occur if the application: - was compiled with optimization turned on - uses system preferences ## 3.0 New Feature Set You can check that this feature set is implemented by checking that the system version is 3.0 or higher. Use this FtrGet call:
    err = FtrGet(sysFtrCreator,
    sysFtrNumROMVersion, &romVersion);
The romVersion parameter should be 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: #####
sysAppLaunchCmdExgAskUser sysAppLaunchCmdExgReceiveData
In addition, the launch code sysAppLaunchCmdGoto is now also sent by the exchange manager, in addition to its use by the global find operation. ## Font This feature set adds the following font: largeBoldFont ## Functions This feature set adds the following functions: #### Dynamic User Interface Functions #####
CtlNewControl CtlValidatePointer FldNewField FrmNewBitmap FrmNewForm FrmNewGadget | FrmNewLabel FrmRemoveObject FrmValidatePtr LstNewList WinValidateHandle
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 #####
FontSelect FntDefineFont
For more information on these functions and the support for custom fonts, see the section "Fonts in Palm OS 3.0 and Later" of the Palm OS Programmer's Companion, vol. I. #### Progress Manager Functions #####
PrgHandleEvent PrgStartDialog PrgStopDialog | PrgUpdateDialog PrgUserCancel
For more information, see the section "Progress Dialogs" of the Palm OS Programmer's Companion, vol. I. #### File Streaming Functions #####
FileClearerr FileClose FileControl FileDelete FileDmRead FileEOF FileError FileFlush FileGetLastError | FileOpen FileRead FileReadLow (system use only) FileRewind FileSeek FileTell FileTruncate FileWrite
For more information, see the section "File Streaming Application Program Interface" of the Palm OS Programmer's Companion, vol. I. #### Sound Functions #####
SndCreateMidiList SndPlaySmf SndDoCmd (enhanced in 3.0)
#### Exchange Manager Functions #####
ExgAccept ExgDBRead ExgDBWrite ExgDisconnect | ExgPut ExgReceive ExgRegisterData ExgSend
For more information, see the chapter Beaming (Infrared Communication) in the Palm OS Programmer's Companion, vol. II, Communications. #### IR Library Functions #####
IrAdvanceCredit IrBind IrClose IrConnectIrLap IrConnectReq IrConnectRsp IrDataReq IrDisconnectIrLap IrDiscoverReq IrIAS_Add IrIAS_GetInteger IrIAS_GetIntLsap IrIAS_GetObjectID IrIAS_GetOctetString IrIAS_GetOctetStringLen IrIAS_GetType IrIAS_GetUserString IrIAS_GetUserStringCharSet | IrIAS_GetUserStringLen IrIAS_Next IrIAS_Query IrIAS_SetDeviceName IrIAS_StartResult IrIsIrLapConnected IrIsMediaBusy IrIsNoProgress IrIsRemoteBusy IrLocalBusy IrMaxRxSize IrMaxTxSize IrOpen IrSetConTypeLMP IrSetConTypeTTP IrSetDeviceInfo IrTestReq IrUnbind
For more information, see the chapter Beaming (Infrared Communication) in the Palm OS Programmer's Companion, vol. II, Communications. #### Miscellaneous Functions #####
FrmRestoreActiveState FrmSaveActiveState ScrDisplayMode SysGetAppInfo (system use only) SysGetOSVersionString | SysGetROMToken SysGetStackInfo SysGremlins TblGetItemFont TblSetItemFont
## Existing Functions that Changed Two functions that existed in 2.0 were changed in 3.0: #####
CategoryEdit (old function renamed CategoryEditV20)
SysBatteryInfo (old function renamed SysBatteryInfoV20)
## Other Changes The dynamic heap has been increased in size to 96 KB. Storage RAM is no longer subdivided into multiple storage heaps of 64 KB each. All storage RAM on a memory card is configured as a single storage heap. Each flash ROM-based Palm device holds a serial number that identifies it uniquely and can be retrieved via SysGetROMToken. For more information, see "Retrieving the ROM Serial Number" of the Palm OS Programmer's Companion, 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 "Sound" of the Palm OS Programmer's Companion, vol. I. The following functions existed in the system previously, but were not documented: #####
RctCopyRectangle RctGetIntersection RctInsetRectangle | RctOffsetRectangle RctPtInRectangle RctSetRectangle
The following event type existed in the system previously, but was not previously documented: frmGotoEvent ## 3.1 New Feature Set You can check that this feature set is implemented by checking that the system version is 3.1 or higher. Use this FtrGet call:
    err = FtrGet(sysFtrCreator,
    sysFtrNumROMVersion, &romVersion);
The romVersion parameter should be 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: #####
ChrHorizEllipsis ChrNumericSpace ContrastAdjust FntWidthToOffset FtrPtrNew FtrPtrFree FtrPtrResize SelectOneTime WinDrawChar WinDrawTruncChars
NOTE: The PalmOSGlue.lib provides compatibility functions and macros for ChrHorizEllipsis, ChrNumericSpace, WinDrawChar, and WinDrawTruncChars. If you want to use these functions on systems that don't have the 3.1 feature set, you can link your application with PalmOSGlue.lib. See the chapter "PalmOSGlue Library" for more information. ## Changes to the Character Encoding Starting in Palm OS 3.1, the character encoding used on most systems is Microsoft Windows code page 1252. Versions prior to 3.1 used an encoding that was very similar to code page 1252 but did not follow it exactly. The following changes to the character set are introduced in Palm OS 3.1: Some of the special Palm OS glyphs in the high ASCII range (such as the shortcut stroke and the command stroke) have been moved down into the control code range, and other characters (such as the numeric space and horizontal ellipsis) have been copied into the control range so that they're guaranteed to exist in every encoding. For the numeric space and horizontal ellipsis, you can use the macros ChrNumericSpace and ChrHorizEllipsis to return the appropriate character regardless of the character map. In PalmOSGlue.lib, these two macros are named TxtGlueGetNumericSpaceChar and TxtGlueGetHorizEllipsisChar, respectively. The four playing-card characters have been moved from the high ASCII range in the standard four fonts to the 9-point Symbol font. ## Other Changes in 3.1 Palm OS 3.1 supports a new processor: the EZ Dragonball processor. This processor is compatible with the existing Dragonball processor, so your application should run without changes as long as it doesn't access registers or system globals directly. If your application needs to know if it is running on an EZ Dragonball, it can check using the following code:
    DWord id, chip;
    Word revision;
    Err err;
    err = FtrGet(sysFtrCreator,
          sysFtrNumProcessorID, &id);
    if (!err) {
      chip = id & sysFtrNumProcessorMask;
      revision = id & 0x0ffff;
      if (chip==sysFtrNumProcessor328)
        // traditional Dragonball
      else if (chip==sysFtrNumProcessorEZ)
        // Dragonball EZ
    }
The constant preferenceDataVersion was removed and replaced with preferenceDataVerLatest. Character variables are now two bytes long. The type WChar defines a character variable. The keyDownEvent structure's chr field (which contains the input character) has been changed from a Word to a WChar. The string manager functions StrChr and StrStr now treat buffers as characters, not arbitrary byte arrays. If you previously used these functions to search data buffers, your code may no longer work. The string manager function StrToLower can now handle any type of characters, including accented characters. The underline attribute of FieldAttrType now has support for the value 2. Previously, the only underline modes available were no underline (0) and gray underline (1). In Palm OS 3.1 and higher, the value 2 is interpreted as solid underline. The UnderlineModeType enum defined in Window.h defines the possible values for the underline attribute. The use of the DmGetNextDatabaseByTypeCreator onlyLatestVers parameter changed in 3.1. If onlyLatestVers is true, you only receive one matching database for each type/creator pair. In version 3.0 and earlier, you could receive multiple matching databases if onlyLatestVers was true. See that function's description for a more detailed description. ## 3.2 New Feature Set You can check that this feature set is implemented by checking that the system version is 3.2 or higher. Use this FtrGet call:
    err = FtrGet(sysFtrCreator, sysFtrNumROMVersion, &romVersion);
The romVersion parameter should be 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: #####
AlmGetProcAlarm AlmSetProcAlarm ClipboardAppendItem DmGetDatabaseLockState ErrAlert SndPlaySmfResource
## Existing Functions that Changed Two functions that existed in 3.0 were changed in 3.2: #####
SysGremlins was removed and replaced with a SysGremlins macro that maps it to the function HostGremlinIsRunning. The prototype is slightly different, but you can still call SysGremlins in the same way you did before.
PrgStartDialog (old function renamed PrgStartDialogV31)
## Other Changes in 3.2 The prototype for the system use only function AlmDisplayAlarm changed from no return value to a Boolean return value. This change may affect system patches and extensions that intercept AlmDisplayAlarm calls. ## International Feature Set You can check that this feature set is implemented by checking for the existence of the international manager. You can check by calling FtrGet as follows:
    err = FtrGet(sysFtrCreator, sysFtrNumIntlMgr, &value);
If the international manager is installed, the value parameter will be non-zero and the returned error should also be zero (for no error). You can learn more about the international manager by reading the chapter "Localized Applications" in the Palm OS Programmer's Companion, 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 #####
TxtByteAttr TxtCaselessCompare TxtCharAttr TxtCharBounds TxtCharEncoding TxtCharIsAlNum TxtCharIsAlpha TxtCharIsCntrl TxtCharIsDigit TxtCharIsGraph TxtCharIsHardKey TxtCharIsHex TxtCharIsLower TxtCharIsPrint TxtCharIsPunct TxtCharIsSpace TxtCharIsUpper TxtCharSize | TxtCharXAttr TxtCompare TxtEncodingName TxtFindString TxtGetChar TxtGetNextChar TxtGetPreviousChar TxtCharIsValid TxtMaxEncoding TxtNextCharSize TxtPreviousCharSize TxtReplaceStr TxtSetNextChar TxtStrEncoding TxtTransliterate TxtGetTruncationOffset TxtWordBounds
#### Other Functions IntlGetRoutineAddress #### Removed Functions and Macros If the international feature set exists, then the following functions and macros are no longer available: #####
GetCharAttr GetCharCaselessValue GetCharSortValue IsAscii IsAlNum IsAlpha IsCntrl IsDigit IsGraph IsLower IsPrint IsPunct IsSpace IsUpper IsHex IsDelim
## Japanese Feature Set You can check that the Japanese feature set is implemented by checking if the unit is Japanese. You can check by calling FtrGet as follows:
    err = FtrGet(sysFtrCreator, sysFtrNumEncoding, &value);
The unit has the Japanese OS if the value parameter is charEncodingCP932. For further information about the Japanese implementation, see the section "Notes on the Japanese Implementation" in the Palm OS Programmer's Companion, 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 iMessengerTM applications. Here's an example of how to check for Viewer:
    DmSearchStateType searchState;
    UInt 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.NetTM 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: #####
sysAppLaunchCmdAddRecord (for iMessenger application; existed for Mail in 3.0) sysAppLaunchCmdGoToURL sysAppLaunchCmdOpenDB sysAppLaunchCmdURLParams
## Events This feature set adds the following events: #####
inetSockReadyEvent inetSockStatusChangeEvent
This feature set also adds the following keyDownEvent key codes: #####
vchrHardAntenna vchrRadioCoverageOK vchrRadioCoverageFail
These key codes are described in the section 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. #####
INetLibCacheGetObject INetLibCacheList INetLibCheckAntennaState INetLibClose INetLibConfigAliasGet INetLibConfigAliasSet INetLibConfigDelete INetLibConfigIndexFromName INetLibConfigList INetLibConfigMakeActive INetLibConfigRename INetLibConfigSaveAs INetLibGetEvent INetLibOpen INetLibSettingGet INetLibSettingSet | INetLibSockClose INetLibSockConnect INetLibSockHTTPAttrGet INetLibSockHTTPAttrSet INetLibSockHTTPReqCreate INetLibSockHTTPReqSend INetLibSockOpen INetLibSockRead INetLibSockSettingGet INetLibSockSettingSet INetLibSockStatus INetLibURLCrack INetLibURLGetInfo INetLibURLOpen INetLibURLsAdd INetLibWiCmd
## New Serial Manager Feature Set 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 #####
SrmClearErr SrmClose SrmControl SrmGetDeviceCount SrmGetDeviceInfo SrmGetStatus SrmOpen SrmOpenBackground SrmPrimeWakeupHandler SrmReceive SrmReceiveCheck | SrmReceiveFlush SrmReceiveWait SrmReceiveWindowClose SrmReceiveWindowOpen SrmSend SrmSendCheck SrmSendFlush SrmSendWait SrmSetReceiveBuffer SrmSetWakeupHandler WakeupHandlerProcPtr
#### Virtual Driver Functions #####
DrvEntryPoint GetSizeProcPtr GetSpaceProcPtr VdrvControlProcPtr VdrvOpenProcPtr | VdrvStatusProcPtr VdrvWriteProcPtr WriteBlockProcPtr WriteByteProcPtr
#### Connection Manager Functions #####
CncAddProfile CncDeleteProfile | CncGetProfileInfo CncGetProfileList
#### Serial Link Manager Function SlkSocketPortID ## 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 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 #####
SrmCustomControl SrmExtOpenBackground | SrmExtOpen
#### Virtual Driver Functions #####
VdrvControlCustomProcPtr SignalCheckPtr | VdrvOpenProcV4Ptr
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: #####
CncProfileCloseDB CncProfileCount CncProfileCreate CncProfileDelete CncProfileGetCurrent CncProfileGetIDFromIndex | CncProfileGetIDFromName CncProfileGetIndex CncProfileOpenDB CncProfileSetCurrent CncProfileSettingGet CncProfileSettingSet
## 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: #####
sysAppLaunchCmdNotify
## Events This feature set adds the following events: #####
frmGadgetEnterEvent frmGadgetMiscEvent menuCmdBarOpenEvent menuOpenEvent
## Functions This feature set adds the following functions. #### Bitmaps #####
BmpBitsSize BmpColortableSize BmpCompress BmpCreate BmpDelete | BmpGetBits BmpGetColortable BmpSize ColorTableEntries
For more information on creating and using bitmaps, see the section "Bitmaps" of the Palm OS Programmer's Companion, vol. I. #### Controls #####
CtlGetSliderValues CtlNewGraphicControl CtlNewSliderControl | CtlSetGraphics CtlSetSliderValues
These functions add support for graphical buttons and slider controls. For more information, see the section "Controls" of the Palm OS Programmer's Companion, vol. I. #### Forms #####
FrmCustomResponseAlert FrmNewGsi | FrmSetGadgetHandler
Among the changes to form functions is extended gadget support. For more information on gadgets and extended gadgets, see the section "Custom UI Objects" of the Palm OS Programmer's Companion, vol. I. #### Menus #####
MenuAddItem MenuCmdBarDisplay MenuHideItem | MenuCmdBarAddButton MenuCmdBarGetButtonData MenuShowItem
For more information on using menu functions, see the section "Menus" of the Palm OS Programmer's Companion, vol. I. #### Overlay Manager #####
OmGetCurrentLocale OmGetIndexedLocale OmGetRoutineAddress OmGetSystemLocale | OmLocaleToOverlayDBName OmOverlayDBNameToLocale OmSetSystemLocale
For more information on using the overlay manager, see the section "Maintaining Backward Compatibility" of the Palm OS Programmer's Companion, vol. I. #### Private Records #####
SecSelectViewStatus | SecVerifyPW
#### Tables #####
TblGetItemPtr TblRowMasked | TblSetColumnMasked TblSetRowMasked
#### UI Colors #####
UIColorGetTableEntryIndex UIColorGetTableEntryRGB | UIColorSetTableEntry
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 #####
UIBrightnessAdjust | UIPickColor
#### Windows #####
WinCreateBitmapWindow WinDrawPixel WinErasePixel WinGetBitmap WinGetPatternType WinGetPixel WinIndexToRGB WinInvertPixel WinPaintBitmap WinPaintChar WinPaintChars WinPaintLine WinPaintLines WinPaintPixel WinPaintPixels | WinPaintRectangle WinPaintRectangleFrame WinPalette WinPopDrawState WinPushDrawState WinRGBToIndex WinScreenLock WinScreenMode WinScreenUnlock WinSetBackColor WinSetDrawMode WinSetForeColor WinSetPatternType WinSetTextColor
For more information on using the window functions, see the section "Drawing on the Palm OS Device" of the Palm OS Programmer's Companion, vol. I. #### Miscellaneous New Functions #####
DmOpenDBNoOverlay ExgDoDialog DateToAscii | ResLoadConstant TxtParamString
## Existing Functions that Changed The following functions that existed prior to 3.5 have changed in release 3.5: #####
ScrDisplayMode was changed to WinScreenMode.
ContrastAdjust was changed to UIContrastAdjust.
SelectTime (old function renamed SelectTimeV33)
## New Data Types The data types Byte, Word, DWord and so on are now deprecated. It is recommend that you use the corresponding new data types. For example, use Int16 instead of SWord and UInt32 instead of DWord. In particular, the unfortunate distinction between Handle/VoidHand has been fixed; use MemHandle instead. To learn in general how the type names changed, see the header file PalmOSCompatibility.h. This file provides a mapping from the old type name to the new type name. If you need to move forward without modifying your code, you can include this file in your project to provide declarations for the old type names. ## Changes to Events The tapCount field has been added to the EventType structure. The tapCount field specifies the number of times the user tapped the pen at the current location; in fields, two taps selects a word, and three taps selects a line. IMPORTANT: Because the tapCount field has been added to the EventType structure, it has become more critical that you clear the event structure before using it to add a new event to the queue. Otherwise, the tapCount will be incorrect for the new event. The structures for ctlRepeatEvent and ctlSelectEvent have a value field added to them. This new field is used only for sliders; it holds the current value of the slider. Form objects now handle the frmTitleSelectEvent by adding a keyDownEvent with the vchrMenu character to the event queue (which causes the form's menu to display). Some of the structure definitions for system-level events have moved from Event.h to SysEvent.h. The winEnterEvent is now not generated until FrmDrawForm is called. Make sure to draw your form in response to frmOpenEvent, not winEnterEvent. 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 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 "Maintaining Backward Compatibility" in 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 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 #####
SysNotifyBroadcast SysNotifyBroadcastDeferred | SysNotifyRegister SysNotifyUnregister
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: #####
sysAppLaunchCmdAttention sysAppLaunchCmdExgGetData sysAppLaunchCmdExgPreview
## Notifications This feature set adds the following notifications: #####
cncNotifyProfileEvent sysExternalConnectorAttachEvent sysExternalConnectorDetachEvent sysNotifyCardInsertedEvent sysNotifyCardRemovedEvent sysNotifyDBDeletedEvent sysNotifyDeleteProtectedEvent sysNotifyDeviceUnlocked sysNotifyGotUsersAttention sysNotifyHelperEvent sysNotifyLocaleChangedEvent sysNotifyNetLibIFMediaEvent sysNotifyRetryEnqueueKey sysNotifyVolumeMountedEvent sysNotifyVolumeUnmountedEvent
## Functions This feature set adds the following functions: #### Attention Manager #####
AttnDoSpecialEffects AttnForgetIt AttnGetAttention AttnGetCounts | AttnIndicatorEnable AttnIndicatorEnabled AttnIterate AttnListOpen AttnUpdate
#### Date and Time Manager #####
TimeZoneToAscii TimTimeZoneToUTC TimUTCToTimeZone |
#### Exchange Manager #####
ExgGetTargetApplication ExgGetDefaultApplication ExgGetRegisteredApplications ExgSetDefaultApplication | ExgControl ExgNotifyGoto ExgNotifyPreview ExgRequest ExgGetRegisteredTypes
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 #####
ExgLibAccept ExgLibClose ExgLibConnect ExgLibControl ExgLibDisconnect ExgLibGet ExgLibHandleEvent | ExgLibOpen ExgLibPut ExgLibReceive ExgLibRequest ExgLibSend ExgLibSleep ExgLibWake
For more information on the Exchange Library API, see Chapter 59, "Exchange Library," of the Palm OS Programmer's Companion, vol. II, Communications. #### Locale Manager #####
LmGetLocaleSetting LmLocaleToIndex | LmGetNumLocales
#### Miscellaneous UI #####
PhoneNumberLookupCustom |
#### Notification Manager #####
SysNotifyBroadcastFromInterrupt |
#### PDI Library Functions #####
PdiDefineReaderDictionary PdiDefineResizing PdiEnterObject PdiLibClose PdiLibOpen PdiParameterPairTest PdiReaderDelete PdiReaderNew PdiReadParameter PdiReadProperty PdiReadPropertyField PdiReadPropertyName | PdiSetEncoding PdiWriteBeginObject PdiWriteEndObject PdiWriteParameter PdiWriteParameterStr PdiWriteProperty PdiWritePropertyBinaryValue PdiWritePropertyFields PdiWritePropertyStr PdiWritePropertyValue PdiWriterDelete PdiWriterNew
For more information, see the chapter Chapter 3, "Personal Data Interchange" in the Palm OS Programmer's Companion. #### Sound Manager Functions #####
SndInterruptSmfIrregardless SndPlaySmfResourceIrregardless | SndPlaySmfIrregardless
For more information, see the chapter Chapter 10, "Palm System Support" in the Palm OS Programmer's Companion. #### Telephony Manager Functions #####
TelCancel TelCgfGetPhoneNumber TelCfgGetSmsCenter TelCfgGetSmsCenter TelClose TelClosePhoneConnection TelDtcCallNumber TelDtcCloseLine TelDtcReceiveData TelDtcSendData TelEmcCall TelEmcCloseLine TelEmcGetNumber TelEmcGetNumberCount TelEmcSelectNumber TelEmcSetNumber TelGetCallState TelGetEvent TelGetTelephonyEvent | TelInfGetInformation TelIs<FunctionName>Supported TelIs<ServiceSet>Available TelIsCfgServiceAvailable TelIsDtcServiceAvailable TelIsEmcServiceAvailable TelIsInfServiceAvailable TelIsNwkServiceAvailable TelIsOemServiceAvailable TelIsPhbServiceAvailable TelIsPhoneConnected TelIsPowServiceAvailable TelIsSmsServiceAvailable TelIsSndServiceAvailable TelIsSpcServiceAvailable TelIsStyServiceAvailable TelMatchPhoneDriver
#####
TelNwkGetLocation TelNwkGetNetworkName TelNwkGetNetworks TelNwkGetNetworkType TelNwkGetSearchMode TelNwkGetSelectedNetwork TelNwkGetSignalLevel TelNwkSelectNetwork TelNwkSetSearchMode TelOemCall TelOpen TelOpenPhoneConnection | TelPhbAddEntry TelPhbDeleteEntry TelPhbGetAvailablePhonebooks TelPhbGetEntries TelPhbGetEntry TelPhbGetEntryCount TelPhbGetEntryMaxSizes TelPhbGetSelectedPhonebook TelPhbSelectPhonebook TelPowGetBatteryStatus TelPowGetPowerLevel TelPowSetPhonePower TelSendCommandString
#####
TelSmsDeleteMessage TelSmsGetAvailableStorage TelSmsGetDataMaxSize TelSmsGetMessageCount TelSmsGetSelectedStorage TelSmsGetUniquePartId TelSmsReadMessage TelSmsReadMessages TelSmsReadReport TelSmsReadReports TelSmsReadSubmittedMessage TelSmsReadSubmittedMessages TelSmsSelectStorage TelSmsSendManualAcknowledge TelSmsSendMessage TelSndMute | TelSndPlayKeyTone TelSndStopKeyTone TelSpcAcceptCall TelSpcCallNumber TelSpcCloseLine TelSpcConference TelSpcGetCallerNumber TelSpcHoldLine TelSpcPlayDTMF TelSpcRejectCall TelSpcRetrieveHeldLine TelSpcSelectLine TelSpcSendBurstDTMF TelSpcStartContinuousDTMF TelSpcStopContinuousDTMF TelStyChangeAuthenticationCode TelStyEnterAuthenticationCode TelStyGetAuthenticationState
For more information about the Telephony Manager, see Chapter 8, "Telephony Manager" in the Palm OS Programmer's Companion. #### Windows Manager #####
WinGetPixelRGB WinSetForeColorRGB | WinSetBackColorRGB WinSetTextColorRGB
#### Internationalization Functions The following functions have been added to aid with creating localized applications: #####
FntWCharWidth StrCompareAscii TxtGetWordWrapOffset IntlSetRoutineAddress | OmGetNextSystemLocale TxtConvertEncoding TxtNameToEncoding
## Existing Functions that Changed 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 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 30, "Expansion Manager,". ## Functions This feature set adds the following functions. #### Expansion Manager Functions #####
ExpCardGetSerialPort ExpCardInfo ExpCardPresent ExpSlotDriverInstall | ExpSlotDriverRemove ExpSlotEnumerate ExpSlotLibFind
## 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 54, "Virtual File System Manager,". ## Functions This feature set adds the following functions. #### VFS Manager Functions #####
VFSCustomControl | VFSFileSize
VFSCustomControl | VFSFileTell
VFSDirEntryEnumerate | VFSFileWrite
VFSExportDatabaseToFile | VFSGetDefaultDirectory
VFSExportDatabaseToFileCustom | VFSImportDatabaseFromFile
VFSFileClose | VFSImportDatabaseFromFileCustom
VFSFileCreate | VFSInstallFSLib
VFSFileDBGetRecord | VFSRegisterDefaultDirectory
VFSFileDBGetResource | VFSRemoveFSLib
VFSFileDBInfo | VFSUnregisterDefaultDirectory
VFSFileDelete | VFSVolumeEnumerate
VFSFileEOF | VFSVolumeFormat
VFSFileGetAttributes | VFSVolumeGetLabel
VFSFileGetDate | VFSVolumeInfo
VFSFileOpen | VFSVolumeMount
VFSFileRead | VFSVolumeSetLabel
VFSFileReadData | VFSVolumeSize
VFSFileRename | VFSVolumeUnmount
VFSFileResize |
VFSFileSetAttributes |
VFSFileSetDate |
VFSFileSeek |