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

37    System Utilities

System Management

Exploring Palm OS®

The utility APIs declared here are of general use by applications. These functions are wide-ranging, and include functions that return the handheld's battery type, to functions that sort arrays using either quicksort or insertion sort algoritihms, to functions that retrieve specific resource types.

This chapter is organized as follows:

System Utilities Structures and Types
System Utilities Constants
System Utilities Functions and Macros

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

System Utilities Structures and Types ^TOP^

CmpFuncPtr Typedef ^TOP^

Purpose

Pointer to a comparison function that is used when sorting arrays with either SysInsertionSort() or SysQSort().

Declared In

SysUtils.h

Prototype

typedef _comparF *CmpFuncPtr

SearchFuncPtr Typedef ^TOP^

Purpose

Pointer to a search function, used with SysBinarySearch().

Declared In

SysUtils.h

Prototype

typedef _searchF *SearchFuncPtr

SysBatteryKind Typedef ^TOP^

Purpose

Contains a value indicating the type of battery used by the handheld.

Declared In

SysUtils.h

Prototype

typedef Enum8 SysBatteryKind

Comments

See SysBatteryKindTag (in Chapter 17, "Common Battery Types,") for the set of values that this type can assume.

SysDBListItemType Struct ^TOP^

Purpose

Describes a single database or panel. The SysCreateDataBaseList() and SysCreatePanelList() functions each create and return an array of SysDBListItemType structures.

Declared In

SysUtils.h

Prototype

typedef struct {
   char name[dmDBNameLength];
   uint32_t creator;
   uint32_t type;
   uint16_t version;
   uint16_t padding;
   LocalID dbID;
   BitmapPtr iconP;
} SysDBListItemType

Fields

name
The name of the database or panel.
creator
The database or panel's creator ID.
type
The database or panel's type.
version
The version of the database or panel.
padding
Padding bytes.
dbID
The database or panel's local ID.
iconP
The database or panel's icon.

System Utilities Constants ^TOP^

Miscellaneous System Utilities Constants ^TOP^

Purpose

The System Utilities header file defines the following constants.

Declared In

SysUtils.h

Constants

#define sysRandomMax 0x7FFF
The upper limit of random number generation. The SysRandom() function generates pseudo-random integers where 0 <= randomInteger <= sysRandomMax.

System Utilities Functions and Macros ^TOP^

Abs Macro ^TOP^

Purpose

Calculate the absolute value of a numeric argument.

Declared In

SysUtils.h

Prototype

#define Abs (
   a
)

Parameters

a
A numeric value.

Returns

Returns the argument if it is greater than or equal to zero, or the argument multiplied by -1 if it is less than zero.

SysAreWeRunningUI Function ^TOP^

Purpose

Determine whether or not the calling thread is running a UI context.

Declared In

SysUtils.h

Prototype

Boolean SysAreWeRunningUI (
   void
)

Parameters

None.

Returns

Returns true if this thread is running a UI context. This is true for the main UI thread and any thread that is currently inside a UI context from WinStartThreadUI().

See Also

SysAreWeUIThread()

SysAreWeUIThread Function ^TOP^

Purpose

Determine whether or not the calling thread is the UI thread.

Declared In

SysUtils.h

Prototype

Boolean SysAreWeUIThread (
   void
)

Parameters

None.

Returns

Returns true if the calling thread is the UI thread, false if not.

SysBatteryInfoV40 Function ^TOP^

Purpose

Retrieve settings for the batteries. Set set to false to retrieve battery settings.


WARNING! Use this function only to retrieve settings! Applications should not change any of the battery settings.

Declared In

SysUtils.h

Prototype

uint16_t SysBatteryInfoV40 (
   Boolean set,
   uint16_t *warnThresholdP,
   uint16_t *criticalThresholdP,
   uint32_t *maxTimeP,
   SysBatteryKind *kindP,
   Boolean *pluggedIn,
   uint8_t *percentP
)

Parameters

set
If false, parameters with non-NULL pointers are retrieved. Never set this parameter to true.
warnThresholdP
Pointer to battery voltage warning threshold in volts*100, or NULL.
criticalThresholdP
Pointer to the battery voltage critical threshold in volts*100, or NULL.
maxTimeP
Pointer to the battery timeout, or NULL.
kindP
Pointer to the battery type, or NULL. For the complete set of battery types, see "SysBatteryKindTag."
pluggedIn
Pointer to pluggedIn return value, or NULL.
percentP
Percentage of power remaining in the battery.

Returns

Returns the current battery voltage in volts*100.

Comments

Call this function to make sure an upcoming activity won't be interrupted by a low battery warning.

warnThresholdP and maxTimeP are the battery-warning voltage threshold and time out. If the battery voltage falls below the threshold, or the timeout expires, a lowBatteryChr key event is put on the queue. Normally, applications call SysHandleEvent() which calls SysBatteryDialog() in response to this event.

criticalThresholdP is the battery voltage threshold. If battery voltage falls below this level, the system turns itself off without warning and doesn't turn on until battery voltage is above it again.

SysBinarySearch Function ^TOP^

Purpose

Search elements in a sorted array for the specified data according to the specified comparison function.

Declared In

SysUtils.h

Prototype

Boolean SysBinarySearch (
   void const *baseP,
   const uint16_t numOfElements,
   const int16_t width,
   SearchFuncPtr searchF,
   void const *searchData,
   const int32_t other,
   int32_t *position,
   const Boolean findFirst
)

Parameters

baseP
Base pointer to an array of elements.
numOfElements
Number of elements to search. Must be greater than 0.
width
Width of each array element.
searchF
Search function.
searchData
Data to search for. This data is passed to the searchF function.
other
Data to be passed as the third parameter (the other parameter) to the comparison function.
position
Pointer to the position result.
findFirst
If set to true, the first matching element is returned. Use this parameter if the array contains duplicate entries to ensure that the first such entry will be the one returned.

Returns

Returns true if an exact match was found. In this case, position points to the element number where the data was found.

Returns false if an exact match was not found. If false is returned, position points to the element number where the data should be inserted if it was to be added to the array in sorted order.

Comments

The array must be sorted in ascending order prior to the search. Use SysInsertionSort() or SysQSort() to sort the array.

The search starts at element 0 and ends at element (numOfElements - 1).

The search function's (searchF) prototype is:


int16_t _searchF (void const *searchData, 
void const *arrayData, int32_t other); 

The first parameter is the data for which to search, the second parameter is a pointer to an element in the array, and the third parameter is any other necessary data.

The function should return:

  • > 0 if the search data is greater than the pointed-to element.
  • < 0 if the search data is less than the pointed-to element.
  • 0 if the search data is the same as the pointed-to element.

SysCopyStringResource Function ^TOP^

Purpose

Obtain a copy of a resource string.

Declared In

SysUtils.h

Prototype

void SysCopyStringResource (
   char *string,
   DmOpenRef dbRef,
   DmResourceID resID
)

Parameters

string
Location to which the resource string is to be copied.
dbRef
Reference to an open resource database that contains the resource string.
resID
ID of the resource string to be copied.

Returns

Returns nothing.

SysCopyStringResourceV50 Function ^TOP^

Purpose

Obtain a copy of a resource string.

Declared In

SysUtils.h

Prototype

void SysCopyStringResourceV50 (
   char *string,
   DmResourceID resID
)

Parameters

string
Location to which the resource string is to be copied.
resID
ID of the resource string to be copied.

Returns

Returns nothing.

Compatibility

This function is provided for compatibility purposes. It searches the resource chain for a resource with the specified ID. New and updated applications should use SysCopyStringResource() instead.

SysCreateDataBaseList Function ^TOP^

Purpose

Generate a list of databases matching a specified type and creator criterion, and return the result.

Declared In

SysUtils.h

Prototype

Boolean SysCreateDataBaseList (
   uint32_t type,
   uint32_t creator,
   uint16_t *dbCount,
   MemHandle *dbIDs,
   Boolean lookupName,
   dmFindType findType
)

Parameters

type
The type of database to find. Supply 0 to find databases of any type.
creator
The creator ID of the database to find. Supply 0 to find databases with any creator ID.
dbCount
A pointer to an integer value that is updated by this function to the number of matching databases.
dbIDs
A pointer to a handle that gets allocated to contain the database list. Upon return, this references an array of SysDBListItemType structures. See the Comments section below for more information.
lookupName
If true, this function uses a name in a tAIN resource instead of the database's name, and it sorts the list.
findType
Flags indicating the type of database to be searched for: schema, extended, classic, or a combination of the three. See DmFindType (in Exploring Palm OS: Memory, Databases, and Files) for more information.

Returns

Returns false if no databases were found, and true if any databases were found. The value of dbCount is updated to reflect the number of databases that were found. If at least one database is found, dbIDs is updated to reference a array of SysDBListItemType structures; this array contains dbCount items.

Comments

This function creates a list of unique databases, where unique is defined as having a different type and creator ID. Two or more databases with the same type and creator ID are counted as one. Thus, you cannot use SysCreateDataBaseList() to build a list of databases that share a common type and creator. There are two exceptions to this rule, however. If type is 0 or if creator is not 0, the code that removes "non-unique" databases isn't run. It also isn't run if the type is sysFileTpqa, since web-clipping databases all have the same type and creator ID.

Only the last version of a database is returned. Databases with multiple versions are listed only once.

If this function returns true and the value of dbCount is greater then 0, than you can iterate through the list of database items, as shown in Listing 37.1

Listing 37.1  Using the SysCreateDatabaseList function


SysDBListItemType *dbListIDsP; 
MemHandle dbListIDsH; 
UInt16 dbCount = 0; 
Boolean status; 
UInt16 counter; 
SysDBListItemType theItem; 
 
status = SysCreateDatabaseList(sysFileTpqa, 0, &dbCount,
   &dbListIDsH, false); 
 
if (status == true && dbCount > 0) { 
   dbListIDsP = MemHandleLock (dbListIDsH); 
   for (counter = 0; counter < dbCount; counter++) 
      if (StrCompare(dbListIDsP[counter].name, "MINE") == 0) 
         // we found my database 
   MemPtrFree (dbListIDsP); 
} 


NOTE: It is your responsibility to free the memory allocated by this function for the list of databases.

See Also

SysCreatePanelList()

SysCreateDataBaseListV50 Function ^TOP^

Purpose

Generate a list of Classic databases matching a specified type and creator criterion, and return the result.

Declared In

SysUtils.h

Prototype

Boolean SysCreateDataBaseListV50(
   uint32_t type,
   uint32_t creator,
   uint16_t *count,
   MemHandle *dbIDs,
   Boolean lookupName
)

Parameters

type
The type of database to find. Supply 0 to find databases of any type.
creator
The creator ID of the database to find. Supply 0 to find databases with any creator ID.
count
A pointer to an integer value that is updated by this function to the number of matching databases.
dbIDs
A pointer to a handle that gets allocated to contain the database list. Upon return, this references an array of SysDBListItemType structures. See the Comments section below for more information.
lookupName
If true, this function uses a name in a tAIN resource instead of the database's name, and it sorts the list.

Returns

Returns false if no databases were found, and true if any databases were found. The value of dbCount is updated to reflect the number of databases that were found. If at least one database is found, dbIDs is updated to reference a array of SysDBListItemType structures; this array contains dbCount items.

Comments

This function is provided for compatibility purposes only. Palm OS Cobalt applications should use SysCreateDataBaseList() instead.

For additional comments, see the Comments section under SysCreateDataBaseList().

SysCreatePanelList Function ^TOP^

Purpose

Generate a list of panels and return the result. Multiple versions of a panel are listed once.

Declared In

SysUtils.h

Prototype

Boolean SysCreatePanelList (
   uint16_t *panelCount,
   MemHandle *panelIDs
)

Parameters

panelCount
The number of panels in the list.
panelIDs
A pointer to a handle that gets allocated to contain the panel list. Upon return, this references an array of SysDBListItemType structures.

Returns

Returns false if no panels were found, and true if any panels were found. The value of panelCount is updated to reflect the number of panels that were found. If at least one panel is found, panelIDs is updated to reference a array of SysDBListItemType structures; this array contains panelCount items.

Comments

If this function returns true and the value of panelCount is greater than 0, than you can iterate through the list of panel items, as shown in Listing 37.1. It is your responsibility to free the memory allocated for the panel list.

See Also

SysCreateDataBaseList()

SysErrString Function ^TOP^

Purpose

Given a system error number, this function looks up the textual description of the error in the appropriate List resource and creates a string that can be used to display that error.

Declared In

SysUtils.h

Prototype

char *SysErrString (
   status_t err,
   char *strP,
   uint16_t maxLen
)

Parameters

err
Error number.
strP
Pointer to a buffer into which the error text will be written.
maxLen
Length of the strP buffer, in bytes.

Returns

Returns a pointer to the error text.

Comments

The actual string will be of the form: "<error message> (XXXX)" where XXXX is the error number in hex.

This function looks for a resource of type 'tstl' and resource ID of (err>>8). It then copies the string at index (err & 0x00FF) out of that resource.


NOTE: The first string in the resource is index #1 in Constructor, NOT #0. For example, an error code of 0x0101 will fetch the first string in the resource.

See Also

SysErrStringTextOnly()

SysErrStringTextOnly Function ^TOP^

Purpose

Given a system error number, this function looks up the textual description of the error in the appropriate List resource and creates a string that can be used to display that error.

Declared In

SysUtils.h

Prototype

char *SysErrStringTextOnly (
   status_t err,
   char *strP,
   uint16_t maxLen
)

Parameters

err
Error number.
strP
Pointer to a buffer into which the error text will be written.
maxLen
Length of the strP buffer, in bytes.

Returns

Returns a pointer to the error text.

Comments

Unlike SysErrString(), this function only returns the error message obtained from the list resource. The error number isn't included in the resulting string.

This function looks for a resource of type 'tstl' and resource ID of (err>>8). It then copies the string at index (err & 0x00FF) out of that resource.


NOTE: The first string in the resource is index #1 in Constructor, NOT #0. For example, an error code of 0x0101 will fetch the first string in the resource.

SysFormPointerArrayToStrings Function ^TOP^

Purpose

Form an array of pointers to strings packed in a block. Useful for setting the items of a list.

Declared In

SysUtils.h

Prototype

MemHandle SysFormPointerArrayToStrings (
   char *c,
   int16_t stringCount
)

Parameters

c
Pointer to packed block of strings, each terminated by a null character.
stringCount
The number of strings in the block.

Returns

Unlocked handle to an allocated array of pointers to the strings in the passed block. The returned array points to the strings in the original block. Note that you'll need to free the returned handle when you no longer need it.

See Also

LstSetListChoices()

SysGetOSVersionString Function ^TOP^

Purpose

Return the operating system version number.

Declared In

SysUtils.h

Prototype

char *SysGetOSVersionString (
   void
)

Parameters

None.

Returns

Returns a string such as "v. 6.0."

Comments

You must free the returned string after you no longer need it.

SysGetROMTokenV40 Function ^TOP^

Purpose

Get a ROM token value.

Declared In

SysUtils.h

Prototype

status_t SysGetROMTokenV40 (
   uint16_t cardNo,
   uint32_t token,
   uint8_t **dataP,
   uint16_t *sizeP
)

Parameters

cardNo
The card on which the ROM to be queried resides. This value must be 0.
token
The value to retrieve, as specified by one of the tokens listed under "ROM Tokens."
dataP
Pointer to a buffer that holds the requested value when the function returns.
sizeP
The number of bytes in the dataP buffer.

Returns

Returns errNone if the requested token was successfully retrieved, or an error code if an error occurred. If this function returns an error, or if the returned pointer to the buffer is NULL, or if the first byte of the text buffer is 0xFF, then no serial number is available.

SysInsertionSort Function ^TOP^

Purpose

Using an insertion sort algorithm, ort elements in an array according to the passed comparison function.

Declared In

SysUtils.h

Prototype

void SysInsertionSort (
   void *baseP,
   uint16_t numOfElements,
   int16_t width,
   const CmpFuncPtr comparF,
   const int32_t other
)

Parameters

baseP
Base pointer to an array of elements.
numOfElements
Number of elements to sort (must be at least 2).
width
Width of each element.
comparF
Comparison function. See Comments, below.
other
Other data passed to the comparison function.

Returns

Returns nothing.

Comments

Only elements which are out of order move. Moved elements are moved to the end of the range of equal elements. If a large amount of elements are being sorted, SysQSort() may be faster.

This is the insertion sort algorithm: Starting with the second element, each element is compared to the preceding element. Each element not greater than the last is inserted into sorted position within those already sorted. A binary search for the insertion point is performed. A moved element is inserted after any other equal elements.

In order to use SysInsertionSort() you must write a comparison function with the following prototype:


int16_t _comparF (void *p1, void *p2, int32_t other); 

Your comparison function must return zero if p1 equals p2, a positive integer value if p1 is greater than p2, and a negative integer value if p1 is less than p2. Note that the value of the parameter named other is passed through from the SysInsertionSort() call and can be used to control the behavior of the comparF function if appropriate for your application.

See Also

SysBinarySearch(), SysQSort()

SysQSort Function ^TOP^

Purpose

Using a quicksort algorithm, sort elements in an array according to the supplied comparison function.

Declared In

SysUtils.h

Prototype

void SysQSort (
   void *baseP,
   uint16_t numOfElements,
   int16_t width,
   const CmpFuncPtr comparF,
   const int32_t other
)

Parameters

baseP
Base pointer to an array of elements.
numOfElements
Number of elements to sort (must be at least 2).
width
Width of each element.
comparF
Comparison function. See Comments, below.
other
Other data passed to the comparison function.

Returns

Returns nothing.

Comments

Equal records can be in any position relative to each other because a quick sort tends to scramble the ordering of records. As a result, calling SysQSort() multiple times can result in a different order if the records are not completely unique. If you don't want this behavior, use SysInsertionSort() instead.

To pick the pivot point, the quick sort algorithm picks the middle of three records picked from around the middle of all records. That way, the algorithm can take advantage of partially sorted data.

These optimizations are built in:

  • The function contains its own stack to limit uncontrolled recursion. When the stack is full, an insertion sort is used because it doesn't require more stack space.
  • An insertion sort is also used when the number of records is low. This avoids the overhead of a quick sort which is noticeable for small numbers of records.
  • If the records seem mostly sorted, an insertion sort is performed to move only those few records that need to be moved.

In order to use SysQSort() you must write a comparison function with the following prototype:

Int16 comparF (void *p1, void *p2, Int32 other)

Your comparison function must return zero if p1 equals p2, a positive integer value if p1 is greater than p2, and a negative integer value if p1 is less than p2. Note that the value of the parameter named other is passed through from the SysQSort() call and can be used to control the behavior of the comparF function if appropriate for your application.

See Also

SysBinarySearch(), SysInsertionSort()

SysRandom Function ^TOP^

Purpose

Return a random number anywhere from 0 to sysRandomMax.

Declared In

SysUtils.h

Prototype

int16_t SysRandom (
   int32_t newSeed
)

Parameters

newSeed
New seed value, or 0 to use existing seed.

Returns

Returns a random number.

SysStringByIndex Function ^TOP^

Purpose

Copy a string out of a string list resource.

Declared In

SysUtils.h

Prototype

char *SysStringByIndex (
   DmOpenRef dbRef,
   DmResourceID resID,
   uint16_t index,
   char *strP,
   uint16_t maxLen
)

Parameters

dbRef
Reference to an open resource database that contains the string list resource.
resID
Resource ID of the string list.
index
String to get out of the list.
strP
Pointer to a buffer into which the string is copied.
maxLen
Size of strP buffer.

Returns

Returns a pointer to the copied string. The string returned from this call will be the prefix string appended with the designated index string. Indices are 0-based; index 0 is the first string in the resource.

Comments

String list resources are of type 'tSTL' and contain a list of strings and a prefix string.

ResEdit always displays the items in the list as starting at 1, not 0. Consider this when creating your string list.

SysStringByIndexV50 Function ^TOP^

Purpose

Copy a string out of a string list resource.

Declared In

SysUtils.h

Prototype

char *SysStringByIndexV50 (
   DmResourceID resID,
   uint16_t index,
   char *strP,
   uint16_t maxLen
)

Parameters

resID
Resource ID of the string list.
index
String to get out of the list.
strP
Pointer to a buffer into which the string is copied.
maxLen
Size of strP buffer.

Returns

Returns a pointer to the copied string. The string returned from this call will be the prefix string appended with the designated index string. Indices are 0-based; index 0 is the first string in the resource.

Comments

String list resources are of type 'tSTL' and contain a list of strings and a prefix string.

ResEdit always displays the items in the list as starting at 1, not 0. Consider this when creating your string list.

Compatibility

This function is provided for compatibility purposes. It searches the resource chain for a string list resource with the specified ID. New and updated applications should use SysStringByIndex() instead.