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

34    Feature Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides reference material for the feature manager. The feature manager API is declared in the header file FeatureMgr.h.

For more information on the feature manager, see the section "Features" in the Palm OS Programmer's Companion, vol. I.

To learn how to use the predefined Palm OS® features to test for the existence of certain OS features, see the "Compatibility Guide" appendix.

Feature Constants ^TOP^

This section lists the feature constants that various parts of Palm OS define to identify how the system works. You can obtain the values of these features with the FtrGet() function:

err = FtrGet(creator, constant, &value)

where creator is the constant listed in the Creator columns of the tables that follow, constant is the value listed in the Constant column, and value is the set by the FtrGet function if the feature is defined. If the feature is not defined, value is not set, and sysErrNoSuchFeature is returned. Unless otherwise specified, you should consider these features to be read-only.

The feature constants are grouped into the following categories:

Networking Features ^TOP^

Table 34.1 lists the features that provide information about the communications and networking libraries installed on the device.

Table 34.1  Communications feature constants

Constant

Creator

Value

btexgFtrNumVersion

btexgFtrCreator

The version number of the Bluetooth Exchange Library. See "Detecting the Bluetooth Exchange Library" in the Palm OS Programmer's Companion, vol. II, Communications for more information.

btLibFeatureVersion

btLibFeature
Creator

The version number of the Bluetooth Library. Used to determine if the Bluetooth Library Feature Set is present.

inetFtrNumVersion

inetLibFtrCreator

The version number of the Internet Library, if present. See "System Requirements" in Palm OS Programmer's Companion, vol. II, Communications for more information.

irFtrNumVersion

irFtrCreator

The version number of the IR library, if present.

kCncFtrCncMgr
Version

kCncFtrCncMgr
Creator

The version of the Connection Manager API. More than one version of this API has been released. If the value for this feature is greater than 0x00040001, the Connection Manager Feature Set is present.

kSmsFtrNumVersion

sysFileCSmsLib

The version number of the SMS Exchange Library.

sysFtrNumDefault
Compression

sysFtrCreator

The default compression algorithm used for wireless networking. The Palm Web Clipping Application checks this feature. Note that the Palm Web Clipping Application is obsolete.

netFtrCommandBlocks

netFtrCreator

System use only.

netFtrNumVersion

netFtrCreator

The version number of the Net Library. See "Version Checking" in the Palm OS Programmer's Companion, vol. II, Communications for more information.

sysFtrBtSupports
ScheduledWakeup

The presence of this feature indicates that the Bluetooth hardware supports wakeup scheduling.

sysFtrNewSerial
Present

sysFileCSerialMgr

A nonzero value indicates that the New Serial Manager Feature Set is present.

sysFtrNewSerial
Version

sysFileCSerialMgr

The version of the New Serial Manager API. There is currently more than one version. See "Checking the Serial Manager Version" in the Palm OS Programmer's Companion, vol. II, Communications for more information.

sysFtrNumEncryption

sysFtrCreator

One or more flags indicating which encryption schemes are present. The only currently supported encryption is DES, which can be tested for using sysFtrNumEncryptionMaskDES.

Expansion and VFS Manager Features ^TOP^

Table 34.2 lists the feature constants that provide information about the Expansion and VFS Managers.

Table 34.2  Expansion and VFS feature constants

Constant

Creator

Value

expFtrIDVersion

sysFileCExpansionMgr

The version number of the Expansion Manager if present on the device. Used to determine if the Expansion Manager Feature Set is present.

vfsFtrIDDefaultFS

sysFileCVFSMgr

The creator ID of the default file system that VFSVolumeFormat() uses when formatting new volumes. Application developers are allowed to set this value.

vfsFtrIDVersion

sysFileCVFSMgr

The version number of the VFS Manager. Use to determine if the VFS Manager Feature Set is present.

Hardware Capability Features ^TOP^

Table 34.3 lists the features constants that provide information about the capabilities of the hardware on which Palm OS is running.

Table 34.3  Hardware capability feature constants

Constant

Creator

Value

kAttnFtr
Capabilities

kAttnFtrCreator

One or more of the Attention Manager Feature Constants, indicating the hardware's abilities for catching the user's attention (LED, sound, vibration, and so on). For more information, see "Detecting Device Capabilities" in the Palm OS Programmer's Companion, vol. I.

sysFtrNumBacklight

sysFtrCreator

A nonzero value indicates that the device has a backlight.

sysFtrNumDisplay
Depth

sysFtrCreator

The device's default display depth. Supported depths are 1, 2, 4, 8, and 16 bits per pixel.

sysFtrNumDmAutoBackup

sysFtrCreator

Indicates that the device has the Automatic Database Backup and Restore feature, which preserves device data even without a backup battery.

sysFtrNumInputArea
Flags

sysFtrCreator

One or more of the flags listed in Table 34.4 that provide information about the input area.

sysFtrNumUIHardwareFlags

One or more flags specifying the set of UI navigation capabilities. See Table 34.5.

This feature is not currently used but may be used by future devices.

Table 34.4 describes the possible flags that could be set in the value for the sysFtrNumInputAreaFlags feature constant. You can AND these flags with the value returned by FtrGet to see if that attribute exists. For example:


err = FtrGet(sysFtrCreator, sysFtrNumInputAreaFlags,  
&flags); 
if (!err) { 
if (flags & grfFtrInputAreaFlagDynamic) ... 
} 

Table 34.4  Input area attributes

Constant

Description

grfFtrInputAreaFlagDynamic

The input area is implemented in software. If 0, the input area is implemented as hardware.

grfFtrInputAreaFlagCollapsible

The user is allowed to collapse the input area, giving more room to the application area.

grfFtrInputAreaFlagLiveInk

The input area has the live ink feature, which echoes the pen stroke so that the user can see what has been written.

Table 34.5 describes the flags that may be set in the value for the sysFtrNumUIHardwareFlags feature constant.

Table 34.5  Navigation attributes

Constant

Description

sysFtrNumUIHardwareHas5Way

The device has a 5-way navigation rocker.

sysFtrNumUIHardwareHasJog

The device has a thumb wheel on the side.

sysFtrNumUIHardwareHasJogBack

The device has a thumb wheel with a back button.

sysFtrNumUIHardwareHasKbd

The device has a built-in keyboard.

sysFtrNumFiveWayNavVersion

The version of the 5-way navigation support (if any)

Hardware Features ^TOP^

Table 34.6 lists the feature constants that identify the hardware itself, rather than the capabilities of the hardware.


NOTE: You are strongly encouraged to check the hardware capabilities and other features before resorting to checking for specific hardware devices, manufacturers, or ROM versions. The other features, when present, provide a more reliable method of discovering the capabilities of a particular device.

Table 34.6  Hardware feature constants

Constant

Creator

Value

sysFtrNumHwrMisc
Flags

sysFtrCreator

One or more flags indicating hardware capabilities. See Table 34.7.

This feature is not applicable on devices with ARM processors. On releases before Palm OS 3.5, this feature's value contains both the product ID and the hardware's capabilities.

sysFtrNumHwrMisc
FlagsExt

sysFtrCreator

One or more flags indicating additional hardware capabilities. See Table 34.8.

This feature is not applicable on devices with ARM processors.

sysFtrNumOEM
CompanyID

sysFtrCreator

The 4-character company ID of the HAL manufacturer. The company ID is unique for each Palm OS licensee.

This feature is only defined on Palm OS 3.5 and later releases. On earlier releases, the sysFtrNumHwrMiscFlags value contains both the product ID and the hardware's capabilities.

sysFtrNumOEM
DeviceID

sysFtrCreator

The 4-character ID of the device on which Palm OS is running. There is roughly one device ID per model of device.

This feature is only defined on Palm OS 3.5 and later releases. On earlier releases, the sysFtrNumHwrMiscFlags value contains both the product ID and the hardware's capabilities.

sysFtrNumOEMHALID

sysFtrCreator

The 4-character ID of the HAL on which Palm OS is running. Each HAL is specific to a device model and Palm OS version.

This feature is only defined on Palm OS 3.5 and later releases. On earlier releases, the sysFtrNumHwrMiscFlags value contains both the product ID and the hardware's capabilities.

sysFtrNumOEMROM
Version

sysFtrCreator

A ROM system version provided by the Palm OS licensee. Used to identify patches provided by licensees.

sysFtrNum
ProcessorID

sysFtrCreator

The processor type and the processor revision. See Table 34.9.

sysFtrNumProductID

sysFtrCreator

The processor type and the processor revision. See Table 34.9. (Note that sysFtrNumOEMDeviceID gives the product ID.)

sysFtrNumROMVersion

sysFtrCreator

The ROM version. You can use the sysMakeROMVersion macro to create a value to test against. See Appendix B and

"The System Version Feature" in the Palm OS Programmer's Companion, vol. I.

sysFtrNumVendor

Not used.

Table 34.7 defines the possible flags that could be set in the value for the sysFtrNumHwrMiscFlags feature constant. You can AND these flags with the value returned by FtrGet to see if that attribute exists. For example:


err = FtrGet(sysFtrCreator, sysFtrNumHwrMiscFlags, &flags); 
if (!err) { 
if (flags & hwrMiscFlagHasBacklight) ... 
} 

Table 34.7  Hardware flags

Constant

Description

hwrMiscFlagHasBacklight

The display has a backlight.

hwrMiscFlagHasMbdIrDA

IrDA is present on the main board.

hwrMiscFlagHasCardIrDA

IrDA is present on the memory card.

hwrMiscFlagHasBurrBrown

Not used.

hwrMiscFlagHasJerryHW

The device is a Palm VII series device.

hwrMiscFlagNoRTCBug

Not used.

hwrMiscFlagHas3vRef

Not used.

hwrMiscFlagHasAntennaSw

Not used.

hwrMiscFlagHasCradleDetect

There is an A/D converter on the HotSync port used for identifying the attached device.

hwrMiscFlagHasSWContrast

Software contrast is supported.

hwrMiscFlagInvertLCDForBL

The LCD is inverted when backlight is on.

hwrMiscFlagHasMiscFlagExt

Further attributes are defined in the sysFtrNumHwrMiscFlagsExt feature value.

Table 34.8 describes the possible flags that could be set in the value for the sysFtrNumHwrMiscFlagsExt feature constant. You can AND these flags with the value returned by FtrGet to see if that attribute exists. For example:


err = FtrGet(sysFtrCreator, sysFtrNumHwrMiscFlagsExt,  
&flags); 
if (!err) { 
if (flags & hwrMiscFlagExtHasLiIon) ... 
} 

Table 34.8  Hardware extended flags

Constant

Description

hwrMiscFlagExtSubIDMask

Subtype ID Mask.

hwrMiscFlagExtHasLiIon

The device has a Lithium Ion battery that is rechargable in the cradle.

hwrMiscFlagExtHasRailIO

Not used.

hwrMiscFlagExtHasFlash

The device has Flash ROM.

hwrMiscFlagExtHasFParms

The device has a Flash parameters area.

hwrMiscFlagExt115KIrOK

The device supports 115K IR transfers.

hwrMiscFlagExtHasExtLCD

Not used.

hwrMiscFlagExtHasSWBright

The device has software controlled brightness.

hwrMiscFlagExtNeedsLpr

Not used.

Table 34.9 contains the possible values returned for sysFtrNumProcessorID and sysFtrNumProductID. Use the bit mask sysFtrNumProcessorMask to extract the processor type from the values returned for these feature. For example:


UInt32 id, chip, 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 
else ... 
} 

Table 34.9  Processor values

Constant

Description

sysFtrNumProcessor328

Motorola 68328 (Dragonball).

sysFtrNumProcessorARM710A

ARM710A

sysFtrNumProcessorARM720T

ARM 720T

sysFtrNumProcessorARM7TDMI

ARM7TDMI

sysFtrNumProcessorARM920T

ARM920T

sysFtrNumProcessorARM922T

ARM922T

sysFtrNumProcessorARM925

ARM925

sysFtrNumProcessorARM925T

ARM925T

sysFtrNumProcessorARM926EJS

ARM926EJ-S

sysFtrNumProcessorEZ

Motorola 68EZ328 (Dragonball EZ).

sysFtrNumProcessorStrongARM

Strong ARM

sysFtrNumProcessorSuperVZ

Motorola 68SZ328 (Dragonball SuperVZ)

sysFtrNumProcessorVZ

Motorola 68VZ328 (Dragonball VZ)

sysFtrNumProcessorx86

The Palm OS ARM Simulator, which runs on Windows. See "Calling ARM-Native Subroutines" in Palm OS Programmer's Companion, vol. I.

sysFtrNumProcessorXscale

X-scale

Emulator and Debugging Features ^TOP^

Table 34.10 lists the feature constants that provide debugging information.

Table 34.10  Debugging feature constants

Constant

Creator

Value

kPalmOSEmulator
FeatureNumber

kPalmOSEmulator
FeatureCreator

The value is 0 if the application is running on the Palm OS Emulator rather than a real handheld.

omFtrShowErrorsFlag

omFtrCreator

A Boolean value that controls the number of error messages displayed by the Overlay Manager. Application developers may set this feature to debug an overlay database. It is automatically set in debug ROMs. See "Overlay Manager Constants" for more information.

sysFtrNumErrorCheckLevel

sysFtrCreator

The error checking level (such as ERROR_CHECK_FULL or ERROR_CHECK_NONE) with which the system was built.

sysFtrNumGremlins
SupportGlobals

sysFtrCreator

A memory location that is used to intelligently support Gremlins. This feature was set only by the Progress Manager and only in Palm OS 3.2 and 3.3. It is obsolete in Palm OS 3.5 and later.

Localization Features ^TOP^

Table 34.11 lists the feature constants that provide information about the device's locale.

Table 34.11  Localization feature constants

Constant

Creator

Value

omFtrDefaultLocale

omFtrCreator

An LmLocaleType constant identifying the country and language of the ROM's default locale.

sysFtrDefaultBold
Font

sysFtrCreator

The FontID of the default font used for bold text as specified in the ROM's locale module.

sysFtrDefaultFont

sysFtrCreator

The FontID of the default font for standard text, as defined in the ROM's locale module.

sysFtrIDKeyboard
Active

sysFtrTKeyboard

A nonzero value indicates that the keyboard dialog is being displayed. Only used on systems with multi-byte character encodings.

sysFtrNumChar
EncodingFlags

sysFtrCreator

One or more of the Character Encoding Feature Attributes, which specify the attributes of the character encoding used on the device. For example, these constants specify if the device uses only single-byte characters or has double-byte characters as well.

sysFtrNumCountry

sysFtrCreator

One of the Country Constants, identifying the default country as specified in the ROM's locale module.

sysFtrNumEncoding

sysFtrCreator

One of the Character Encoding Constants identifying the character encoding used on the device. See also "Retrieving the Character Encoding" in the Palm OS Programmer's Companion, vol. I.

sysFtrNumIntlMgr

sysFtrCreator

One or more flags specifying International Manager attributes. See Table 34.12.

sysFtrNumLanguage

sysFtrCreator

One of the Language Constants specifying the default language in the ROM's locale module.

tsmFtrNumFlags

tsmFtrCreator

One or more flags indicating the attributes of the front-end processor (FEP). The only supported attribute currently is tsmFtrFlagsHasFep, which is set when any FEP is present. FEPs are common on systems with multi-byte character encodings.

Table 34.12 lists the possible flags that could be set in the value for the sysFtrNumIntlMgr feature constant.

Table 34.12  International Manager flags

Constant

Description

intlMgrExists

The International Manager is installed on the device.

intlMgrStrict

The International Manager does strict checking and produces more error messages. This flag is set for debugging purposes.

intlMgrBestFit

The TxtConvertEncoding() function can use the charEncodingDestBestFitFlag. See the description of that function for more information.

Miscellaneous Features ^TOP^

Table 34.13 lists the feature constants that provide information about the other features that may be part of Palm OS.

Table 34.13  Miscellaneous feature constants

Constant

Creator

Value

sndFtrIDVersion

sysFileCSoundMgr

The version number of the Sound Streaming API. Used to determine if the Sound Stream Feature Set is present.

sysFtrIDOEMSysHide
BatteryGauge

sysFtrTOEMSys

If defined, the Launcher does not display the battery gauge in its title bar. This feature is only defined on devices such as phones that have some other place to display the information.

sysFtrNumAccessor
TrapPresent

sysFtrCreator

A nonzero value indicates that the Palm OS Glue Library running on a Palm OS Garnet release should call certain functions through PACE rather than access structures directly.

sysFtrNumNotifyMgr
Version

sysFtrCreator

The version number of the Notification Manager API. Used to determine if the Notification Feature Set is present.

sysFtrNumWinVersion

sysFtrCreator

The version of the Window Manager. If 4 or greater, the High-Density Display Feature Set is present. Version 5 adds QVGA support.

Feature Manager Functions and Macros ^TOP^

FtrGet Function ^TOP^

Purpose

Get a feature.

Declared In

FeatureMgr.h

Prototype

Err FtrGet (
   UInt32creator,
   UInt16featureNum,
   UInt32*valueP
)

Parameters

creator
Creator ID, which must be registered with PalmSource, Inc. This is usually the same as the creator ID for the application that owns this feature.
featureNum
Feature number of the feature.
valueP
Value of the feature is returned here.

Returns

Returns 0 if no error, or ftrErrNoSuchFeature if the specified feature number doesn't exist for the specified creator.

Comments

The value of the feature is application-dependent.

See Also

FtrSet()

FtrGetByIndex Function ^TOP^

Purpose

Get a feature by index.

Declared In

FeatureMgr.h

Prototype

Err FtrGetByIndex (
   UInt16index,
   BooleanromTable,
   UInt32*creatorP,
   UInt16*numP,
   UInt32*valueP
)

Parameters

index
Index of feature.
romTable
If true, index into ROM table; otherwise, index into RAM table.
creatorP
Feature creator is returned here.
numP
Feature number is returned here.
valueP
Feature value is returned here.

Returns

Returns 0 if no error, or ftrErrNoSuchFeature if the index is out of range.

Comments

This function is intended for system use only. It is used by shell commands. Most applications don't need it.

Until the caller gets back ftrErrNoSuchFeature, it should pass indices for each table (ROM, RAM) starting at 0 and incrementing. Note that in Palm OS 3.1 and higher, the RAM feature table serves the entire system. At system startup, the values in the ROM feature table are copied into the RAM feature table.

FtrPtrFree Function ^TOP^

Purpose

Release memory previous allocated with FtrPtrNew().

Declared In

FeatureMgr.h

Prototype

Err FtrPtrFree (
   UInt32creator,
   UInt16featureNum
)

Parameters

creator
The creator ID for the feature.
featureNum
Feature number of the feature.

Returns

Returns 0 if no error, or ftrErrNoSuchFeature if an error occurs.

Comments

This function unregisters the feature before freeing the memory associated with it.

Compatibility

Implemented only if 3.1 New Feature Set is present.

FtrPtrNew Function ^TOP^

Purpose

Allocate feature memory.

Declared In

FeatureMgr.h

Prototype

Err FtrPtrNew (
   UInt32creator,
   UInt16featureNum,
   UInt32size,
   void**newPtrP
)

Parameters

creator
Creator ID, which must be registered with PalmSource, Inc. This is usually the same as the creator ID for the application that owns this feature.
featureNum
Feature number of the feature.
size
Size in bytes of the temporary memory to allocate. The maximum chunk size is 64K.
newPtrP
Pointer to the memory chunk is returned here.

Returns

Returns 0 if no error, memErrInvalidParam if the value of size is 0, or memErrNotEnoughSpace if there is not enough space to allocate a chunk of the specified size.

Comments

This function allocates a chunk of memory and stores a pointer to that chunk in the feature table. The same pointer is returned in newPtrP. The memory chunk remains allocated and locked until the next system reset or until you free the chunk with FtrPtrFree().

FtrPtrNew is useful if you want quick, efficient access to data that persists from one invocation of the application to the next. FtrPtrNew stores values on the storage heap rather than the dynamic heap, where free space is often extremely limited. The disadvantage to using feature memory is that writing to storage memory is slower than writing to dynamic memory.


NOTE: Starting with Palm OS 3.5, FtrPtrNew allows allocating chunks larger than 64k. Do keep in mind standard issues with allocating large chunks of memory: there might not be enough contiguous space, and it can impact system performance.

You can obtain the pointer to the chunk using FtrGet(). To write to the chunk, you must use DmWrite() because the chunk is in the storage heap, not the dynamic heap.

For example, if you allocate a memory chunk in this way:


FtrPtrNew(appCreator, 
myFtrMemFtr, 32, &ftrMem); 

You can later access that memory and write to it using the following:


void *data;  
if (!FtrGet(appCreator, 
myFtrMemFtr, (UInt32*)&data)) 
DmWrite(data, 0, &someVal, sizeof(someVal)); 

Compatibility

Implemented only if 3.1 New Feature Set is present.

See Also

FtrPtrResize()

FtrPtrResize Function ^TOP^

Purpose

Resize feature memory.

Declared In

FeatureMgr.h

Prototype

Err FtrPtrResize (
   UInt32creator,
   UInt16featureNum,
   UInt32newSize,
   void**newPtrP
)

Parameters

creator
The creator ID for the feature.
featureNum
Feature number of the feature.
newSize
New size in bytes for the chunk.
newPtrP
Pointer to the memory chunk is returned here.

Returns

Returns 0 if no error, or ftrErrNoSuchFeature if the specified feature number doesn't exist for the specified creator, memErrInvalidParam if newSize is 0, or memErrNotEnoughSpace if there's not enough free space available to allocate a chunk of that size.

Comments

Use this function to resize a chunk of memory previously allocated by FtrPtrNew().

This function may move the chunk to a new location in order to resize it, so it is important to use the pointer returned by this function when accessing the memory chunk. The pointer in the feature table is automatically updated to be the same as the pointer returned by this function.

If this function fails, the old memory pointer still exists and its data is unchanged.

Compatibility

Implemented only if 3.1 New Feature Set is present.

See Also

MemHandleResize()

FtrSet Function ^TOP^

Purpose

Set a feature.

Declared In

FeatureMgr.h

Prototype

Err FtrSet (
   UInt32creator,
   UInt16featureNum,
   UInt32newValue
)

Parameters

creator
Creator ID, which must be registered with PalmSource, Inc. This is usually the same as the creator ID for the application that owns this feature.
featureNum
Feature number for this feature.
newValue
New value.

Returns

Returns 0 if no error, or memErrNotEnoughSpace if the feature table must be resized to add a new feature and no space is available.

Comments

The value of the feature is application-dependent.

A feature that you define in this manner remains defined until the next system reset or until you explicitly undefine the feature with FtrUnregister().

See Also

FtrGet(), FtrPtrNew()

FtrUnregister Function ^TOP^

Purpose

Unregister a feature.

Declared In

FeatureMgr.h

Prototype

Err FtrUnregister (
   UInt32creator,
   UInt16featureNum
)

Parameters

creator
Creator ID for the feature.
featureNum
Feature number of the feature.

Returns

Returns 0 if no error, or ftrErrNoSuchFeature if the specified feature number doesn't exist for the specified creator.