29 Feature Manager

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.

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 Computing®. 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 ftrErrNoSuchFtr 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 ftrErrNoSuchFtr 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 Computing. 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 ftrErrNoSuchFtr 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 Computing. 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.