"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
Feature Manager Error Codes
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
FtrGet Function
Purpose
Declared In
FeatureMgr.h
Prototype
status_t FtrGet ( uint32_tcreator
, uint32_tfeatureNum
, 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
FtrGetByIndex Function
Purpose
Declared In
FeatureMgr.h
Prototype
status_t FtrGetByIndex ( uint16_tindex
, BooleanromTable
, 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
Purpose
Release memory previous allocated with FtrPtrNew()
.
Declared In
FeatureMgr.h
Prototype
status_t FtrPtrFree ( uint32_tcreator
, uint32_tfeatureNum
)
Parameters
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
Purpose
Retrieve a previously created feature pointer.
Declared In
FeatureMgr.h
Prototype
status_t FtrPtrGet ( uint32_tcreator
, uint32_tfeatureNum
, 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 Function
Purpose
Declared In
FeatureMgr.h
Prototype
status_t FtrPtrNew ( uint32_tcreator
, uint32_tfeatureNum
, size_tsize
, 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
FtrPtrResize Function
Purpose
Declared In
FeatureMgr.h
Prototype
status_t FtrPtrResize ( uint32_tcreator
, uint32_tfeatureNum
, size_tnewSize
, 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
FtrSet Function
Purpose
Declared In
FeatureMgr.h
Prototype
status_t FtrSet ( uint32_tcreator
, uint32_tfeatureNum
, uint32_tnewValue
)
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
FtrUnregister Function
Purpose
Declared In
FeatureMgr.h
Prototype
status_t FtrUnregister ( uint32_tcreator
, uint32_tfeatureNum
)
Parameters
Returns
Returns errNone
if no error, or ftrErrNoSuchFeature
if the specified feature number doesn't exist for the specified creator.