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 Manager Functions

FtrGet

Purpose
Get a feature.
Prototype
Err FtrGet (UInt32 creator, UInt16 featureNum, UInt32 *valueP)
Parameters
-> creator | Creator ID, which must be registered with Palm, 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. |
Result
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

Purpose
Get a feature by index.
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. |
Result
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

Purpose
Release memory previous allocated with FtrPtrNew.
Prototype
Err FtrPtrFree (UInt32 creator, UInt16 featureNum)
Parameters
-> creator | The creator ID for the feature. |
-> featureNum | Feature number of the feature. |
Result
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

Purpose
Allocate feature memory.
Prototype
Err FtrPtrNew (UInt32 creator, UInt16 featureNum, UInt32 size, void **newPtrP)
Parameters
-> creator | Creator ID, which must be registered with Palm, 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. |
Result
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

Purpose
Resize feature memory.
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. |
Result
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

Purpose
Set a feature.
Prototype
Err FtrSet (UInt32 creator, UInt16 featureNum, UInt32 newValue)
Parameters
-> creator | Creator ID, which must be registered with Palm, Inc. This is usually the same as the creator ID for the application that owns this feature. |
-> featureNum | Feature number for this feature. |
Result
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

Purpose
Unregister a feature.
Prototype
Err FtrUnregister (UInt32 creator, UInt16 featureNum)
Parameters
-> creator | Creator ID for the feature. |
-> featureNum | Feature number of the feature. |
Result
Returns 0 if no error, or ftrErrNoSuchFeature if the specified feature number doesn't exist for the specified creator.
|