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

2    Features

System Management

Exploring Palm OS®

A feature is a 32-bit value that has special meaning to both the feature publisher and to users of that feature. Features can be published by the system or by applications.

Each feature is identified by a feature creator and a feature number:

  • The feature creator is a unique creator registered with PalmSource, Inc. You usually use the creator type of the application that publishes the feature.
  • The feature number is any 32-bit value used to distinguish between different features of a particular creator.

Once a feature is published, it remains present until it is explicitly unregistered or the handheld is reset. A feature published by an application sticks around even after the application quits.

This section introduces the Feature Manager by discussing these topics:

The Operating System Version Feature ^TOP^

As an example of what features are used for, the version of the operating system is stored in a feature. This feature is published by the system and contains a 32-bit representation of the operating system version. The operating system version has a feature creator of sysFtrCreator and a feature number of sysFtrNumROMVersion. To obtain the operating system version you call FtrGet(), like this:


err = FtrGet(sysFtrCreator, sysFtrNumROMVersion,
   &romVersion); 

On Palm OS Cobalt, the value written to romVersion by this call is 0x06003000. This indicates that the operating system version is 6.0, and that it is a release ROM.

If your code is dependant on a particular Palm OS version, you'll want to obtain the value of the sysFtrNumROMVersion feature and compare it to a known base value. Rather than hard wiring an obscure constant like one of the above into your code, however, you can use the sysMakeROMVersion macro (defined in SystemMgr.h) to construct a version number for comparison purposes. It takes five parameters:

  • Major version number
  • Minor version number
  • Fix level
  • Build stage (either sysROMStageDevelopment,
    sysROMStageAlpha, sysROMStageBeta, or
    sysROMStageRelease)
  • Build number

The fix level and build number parameters are normally set to zero, while build stage is usually set to sysROMStageRelease. Simply check to see whether sysFtrNumROMVersion is greater than or equal to the version number constructed with sysMakeROMVersion, as shown here:


// See if we're on ROM version 6.0 or later. 
FtrGet(sysFtrCreator, sysFtrNumROMVersion, &romVersion); 
if (romVersion >= sysMakeROMVersion(6, 0, 0, 
    sysROMStageRelease, 0)) { 
   .... 
} 

Other system features are defined in SystemMgr.h; see "System Features" for a complete list. Checking for the presence of system features allows an application to be compatible with multiple versions of the system by refining its behavior depending on which capabilities are actually present in the device. For instance, the blitter's capabilities can be determined by checking the version number of the Window Manager. If the Window Manager version is 4 or greater, "high-density" displays (greater than 160 by 160 pixels) are supported. If the Window Manager version is 5 or greater, quarter-VGA displays (320 by 240 pixels) are supported. (Note, however, that just because the blitter is capable of working with a quarter-VGA display, for example, that doesn't mean that the handheld actually has a quarter-VGA display. For that, you need to check the attributes of the screen with WinScreenGetAttribute().)

In some cases the presence or absence of a feature is also important. For instance, the VFS Manager may or may not be present on a given device. If it is not present, the FtrGet() call returns an error. See "Checking for the Presence of the VFS Manager" for more on checking for the VFS Manager feature.


IMPORTANT: Not all features are guaranteed to be present on any given device. Always check for specific features rather than relying on the system version number to determine if a specific API set is available.

Application-Defined Features ^TOP^

Applications may find the Feature Manager useful for their own private use. For example, an application may want to publish a feature that contains a pointer to some private data it needs for processing launch codes. Or, an application might use features to hold small pieces of data that must persist across application launches.

The feature manager maintains one feature table in RAM, and one feature table in ROM. Application-defined features are stored in the RAM feature table. System features are stored in the ROM feature table. Note, however, that the contents of the ROM feature table are copied into the RAM feature table at system startup.

Using the Feature Manager ^TOP^

To check whether a particular feature is present, call FtrGet() and pass it the feature creator ID and feature number. If the feature exists, FtrGet() returns the 32-bit value of the feature. If the feature doesn't exist, an error code is returned.

To publish a new feature or change the value of an existing one, call FtrSet() and pass the feature creator ID, feature number, and the 32-bit value of the feature. A published feature remains available until it is explicitly removed by a call to FtrUnregister() or until the system resets; simply quitting an application doesn't remove a feature published by that application. Upon reset, all features and feature pointers are cleared out and must be re-initialized by the appropriate component.

You can get a complete list of all published features by calling FtrGetByIndex() repeatedly. The first time you call FtrGetByIndex(), pass an index value of 0. Increment the index value by 1 on subsequent calls until FtrGetByIndex() returns an error. Note that although FtrGetByIndex() accepts a parameter that specifies whether to search the ROM feature table or the RAM feature table, the contents of the ROM table are copied into the RAM table at system startup. Thus, the RAM feature table contains all feature values.

Feature Memory ^TOP^

Feature memory provides quick, efficient access to data that persists between invocations of an application. The values stored in feature memory persist until the handheld is reset or until you explicitly free the memory. Feature memory is memory allocated from the storage heap. Thus, you write to feature memory using DmWrite(), which means that writing to feature memory is no faster than writing to a database. However, feature memory can provide more efficient access to that data in certain circumstances.

To allocate a chunk of feature memory, call FtrPtrNew(), specifying a feature creator, a feature number, the number of bytes to allocate, and a location where the Feature Manager can write a pointer to the newly allocated memory chunk. For example:


FtrPtrNew(appCreator, myFtrMemFtr, 32, &ftrMem); 

Elsewhere in your application, you can obtain the pointer to the feature memory chunk using FtrPtrGet().

Feature memory is considered a performance optimization. The conditions under which you'd use it are not common, and you probably won't find them in a typical application.

One potential use of feature memory is to "publish" data from your application or library to other applications when that data doesn't fit in a normal 32-bit feature value. For example, suppose you are writing a communications library and you want to publish an icon that client applications can use to draw the current connection state. The library can use FtrPtrNew() to allocate a feature memory chunk and store an icon representing the current state in that location. Applications can then use FtrPtrGet() to access the icon and display the connection state on the screen.

Feature Memory Limitations ^TOP^

Feature pointer memory is allocated from the storage heap as part of a "features" temporary database, so applications must use DmWrite() to write to feature pointers. (While a feature pointer's contents are modified via DmWrite(), you modify the pointer itself using FtrPtrResize() or FtrPtrFree().)

If one thread or process modifies the feature pointer while another one is using it, the result is undefined. This is generally not a problem because feature pointers are usually private and used by only one application at a time, so synchronization is never required. However, it is important to note that feature pointers are not a good foundation for sharing memory across threads or processes in Palm OS Cobalt, and you should not use them for that purpose.