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
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
- Expansion and VFS Manager Features
- Hardware Capability Features
- Hardware Features
- Emulator and Debugging Features
- Localization Features
- Miscellaneous Features
Networking Features
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
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. |
||
The version number of the Bluetooth Library. Used to determine if the Bluetooth Library Feature Set is present. |
||
The version number of the Internet Library, if present. See "System Requirements" in Palm OS Programmer's Companion, vol. II, Communications for more information. |
||
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 |
||
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. |
||
The version number of the Net Library. See "Version Checking" in the Palm OS Programmer's Companion, vol. II, Communications for more information. |
||
The presence of this feature indicates that the Bluetooth hardware supports wakeup scheduling. |
||
A nonzero value indicates that the New Serial Manager Feature Set is present. |
||
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. |
||
One or more flags indicating which encryption schemes are present. The only currently supported encryption is DES, which can be tested for using |
Expansion and VFS Manager Features
Table 34.2 lists the feature constants that provide information about the Expansion and VFS Managers.
Table 34.2 Expansion and VFS feature constants
The version number of the Expansion Manager if present on the device. Used to determine if the Expansion Manager Feature Set is present. |
||
The creator ID of the default file system that |
||
The version number of the VFS Manager. Use to determine if the VFS Manager Feature Set is present. |
Hardware Capability Features
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
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. |
||
The device's default display depth. Supported depths are 1, 2, 4, 8, and 16 bits per pixel. |
||
Indicates that the device has the Automatic Database Backup and Restore feature, which preserves device data even without a backup battery. |
||
One or more of the flags listed in Table 34.4 that provide information about the input area. |
||
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
Table 34.5 describes the flags that may be set in the value for the sysFtrNumUIHardwareFlags
feature constant.
Table 34.5 Navigation attributes
Hardware Features
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
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. |
||
One or more flags indicating additional hardware capabilities. See Table 34.8. |
||
This feature is not applicable on devices with ARM processors. |
||
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 |
||
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 |
||
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 |
||
A ROM system version provided by the Palm OS licensee. Used to identify patches provided by licensees. |
||
The processor type and the processor revision. See Table 34.9. |
||
The processor type and the processor revision. See Table 34.9. (Note that |
||
The ROM version. You can use the "The System Version Feature" in the Palm OS Programmer's Companion, vol. I. |
||
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) ... }
There is an A/D converter on the HotSync port used for identifying the attached device. |
|
Further attributes are defined in the |
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
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 ... }
The Palm OS ARM Simulator, which runs on Windows. See "Calling ARM-Native Subroutines" in Palm OS Programmer's Companion, vol. I. |
|
Emulator and Debugging Features
Table 34.10 lists the feature constants that provide debugging information.
Table 34.10 Debugging feature constants
The value is 0 if the application is running on the Palm OS Emulator rather than a real handheld. |
||
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. |
||
The error checking level (such as |
||
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
Table 34.11 lists the feature constants that provide information about the device's locale.
Table 34.11 Localization feature constants
An |
||
The |
||
The |
||
A nonzero value indicates that the keyboard dialog is being displayed. Only used on systems with multi-byte character encodings. |
||
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. |
||
One of the Country Constants, identifying the default country as specified in the ROM's locale module. |
||
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. |
||
One or more flags specifying International Manager attributes. See Table 34.12. |
||
One of the Language Constants specifying the default language in the ROM's locale module. |
||
One or more flags indicating the attributes of the front-end processor (FEP). The only supported attribute currently is |
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
The International Manager does strict checking and produces more error messages. This flag is set for debugging purposes. |
|
The |
Miscellaneous Features
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
The version number of the Sound Streaming API. Used to determine if the Sound Stream Feature Set is present. |
||
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. |
||
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. |
||
The version number of the Notification Manager API. Used to determine if the Notification Feature Set is present. |
||
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
FtrGet Function
Purpose
Declared In
FeatureMgr.h
Prototype
Err FtrGet ( UInt32 creator, UInt16 featureNum, 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
FtrGetByIndex Function
Purpose
Declared In
FeatureMgr.h
Prototype
Err FtrGetByIndex ( UInt16 index, Boolean romTable, 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
Purpose
Release memory previous allocated with FtrPtrNew()
.
Declared In
FeatureMgr.h
Prototype
Err FtrPtrFree ( UInt32 creator, UInt16 featureNum )
Parameters
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
Purpose
Declared In
FeatureMgr.h
Prototype
Err FtrPtrNew ( UInt32 creator, UInt16 featureNum, UInt32 size, 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 Function
Purpose
Declared In
FeatureMgr.h
Prototype
Err FtrPtrResize ( UInt32 creator, UInt16 featureNum, UInt32 newSize, 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
FtrSet Function
Purpose
Declared In
FeatureMgr.h
Prototype
Err FtrSet ( UInt32 creator, UInt16 featureNum, UInt32 newValue )
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
FtrUnregister Function
Purpose
Declared In
FeatureMgr.h
Prototype
Err FtrUnregister ( UInt32 creator, UInt16 featureNum )
Parameters
Returns
Returns 0 if no error, or ftrErrNoSuchFeature
if the specified feature number doesn't exist for the specified creator.