< Home < Developers < Development Support < Documentation

## 31 Feature Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 31 Feature Manager Feature Manager Functions FtrGet FtrGetByIndex FtrPtrFree FtrPtrNew FtrPtrResize FtrSet FtrUnregister |  |  |  | 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.
#####
-> newValue | New value.
#### 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. |