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

27    Feature Manager

System Management

Exploring Palm OS®

"Features" provide applications or other components with a means to get and set 32-bit values that persist between invocations of those components. Features are identified by a 32-bit unique creator ID and a 32-bit feature number. The operating system uses the Feature Manager to publish information about the current state of the operating system and the device. Applications are free to use the Feature Manager for similar purposes, or for holding small pieces of data that must persist across application launches. On reset, all features and feature pointers are cleared out and must be re-initialized by the appropriate component.

Feature pointers have traditionally provided a way to allocate chunks of memory larger than the (then very small) dynamic heap, and allow that memory to persist until the device was reset. In Palm OS Cobalt the dynamic heaps are typically much larger and are much more efficient, so reliance on feature pointers is reduced.

This chapter describes the constants and functions that constitute the Feature Manager. It is organized as follows:

Feature Manager Constants
Feature Manager Functions and Macros

The header file FeatureMgr.h declares the API that this chapter describes.

For information on using the APIs documented in this chapter, see Chapter 2, "Features."

Feature Manager Constants ^TOP^

Feature Manager Error Codes ^TOP^

Purpose

Error codes returned by the various Feature Manager functions.

Declared In

FeatureMgr.h

Constants

#define ftrErrInternalErr (ftrErrorClass | 5)
An internal error occurred.
#define ftrErrInvalidParam (ftrErrorClass | 1)
One of the function parameters is invalid.
#define ftrErrNoSuchFeature (ftrErrorClass | 2)
The specified feature number doesn't exist for the specified creator.

Feature Manager Functions and Macros ^TOP^

FtrGet Function ^TOP^

Purpose

Get a feature.

Declared In

FeatureMgr.h

Prototype

status_t FtrGet (
   uint32_t creator,
   uint32_t featureNum,
   uint32_t *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

status_t FtrGetByIndex (
   uint16_t index,
   Boolean romTable,
   uint32_t *creatorP,
   uint16_t *numP,
   uint32_t *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 errNone 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 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

status_t FtrPtrFree (
   uint32_t creator,
   uint32_t featureNum
)

Parameters

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

Returns

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

Comments

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

FtrPtrGet Function ^TOP^

Purpose

Retrieve a previously created feature pointer.

Declared In

FeatureMgr.h

Prototype

status_t FtrPtrGet (
   uint32_t creator,
   uint32_t featureNum,
   size_t *sizeP,
   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.
sizeP
Size, in bytes, of the memory chunk allocated to the feature pointer.
newPtrP
Pointer to the memory chunk is returned here.

Returns

Returns errNone if the operation completed successfully.

See Also

FtrPtrNew()

FtrPtrNew Function ^TOP^

Purpose

Allocate feature memory.

Declared In

FeatureMgr.h

Prototype

status_t FtrPtrNew (
   uint32_t creator,
   uint32_t featureNum,
   size_t 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 errNone 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.

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)); 

See Also

FtrPtrGet(), FtrPtrResize()

FtrPtrResize Function ^TOP^

Purpose

Resize feature memory.

Declared In

FeatureMgr.h

Prototype

status_t FtrPtrResize (
   uint32_t creator,
   uint32_t featureNum,
   size_t 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 errNone 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.

See Also

MemHandleResize()

FtrSet Function ^TOP^

Purpose

Set a feature.

Declared In

FeatureMgr.h

Prototype

status_t FtrSet (
   uint32_t creator,
   uint32_t featureNum,
   uint32_t 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 errNone 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

status_t FtrUnregister (
   uint32_t creator,
   uint32_t featureNum
)

Parameters

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

Returns

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