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
CmpFuncPtr Typedef
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
Purpose
Pointer to a search function, used with SysBinarySearch()
.
Declared In
SysUtils.h
Prototype
typedef _searchF *SearchFuncPtr
SysBatteryKind Typedef
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
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
Miscellaneous System Utilities Constants
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
Abs Macro
Purpose
Calculate the absolute value of a numeric argument.
Declared In
SysUtils.h
Prototype
#define Abs (
a
)
Parameters
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
Purpose
Determine whether or not the calling thread is running a UI context.
Declared In
SysUtils.h
Prototype
Boolean SysAreWeRunningUI ( void )
Parameters
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 Function
Purpose
Determine whether or not the calling thread is the UI thread.
Declared In
SysUtils.h
Prototype
Boolean SysAreWeUIThread ( void )
Parameters
Returns
Returns true
if the calling thread is the UI thread, false
if not.
SysBatteryInfoV40 Function
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 ( Booleanset
, 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 totrue
. -
↔ 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, orNULL
. -
↔ 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
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_tnumOfElements
, const int16_twidth
, SearchFuncPtrsearchF
, void const*searchData
, const int32_tother
, int32_t*position
, const BooleanfindFirst
)
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_tother
);
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.
- > 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
Purpose
Obtain a copy of a resource string.
Declared In
SysUtils.h
Prototype
void SysCopyStringResource ( char*string
, DmOpenRefdbRef
, DmResourceIDresID
)
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
SysCopyStringResourceV50 Function
Purpose
Obtain a copy of a resource string.
Declared In
SysUtils.h
Prototype
void SysCopyStringResourceV50 ( char*string
, DmResourceIDresID
)
Parameters
-
→ string
- Location to which the resource string is to be copied.
-
→ resID
- ID of the resource string to be copied.
Returns
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
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_ttype
, uint32_tcreator
, uint16_t*dbCount
, MemHandle*dbIDs
, BooleanlookupName
, 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 atAIN
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
SysCreateDataBaseListV50 Function
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_ttype
, uint32_tcreator
, uint16_t *count
, MemHandle *dbIDs
, BooleanlookupName
)
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 atAIN
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
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
SysErrString Function
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_terr
, char*strP
, uint16_tmaxLen
)
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 Function
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_terr
, char*strP
, uint16_tmaxLen
)
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
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_tstringCount
)
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
SysGetOSVersionString Function
Purpose
Return the operating system version number.
Declared In
SysUtils.h
Prototype
char *SysGetOSVersionString ( void )
Parameters
Returns
Returns a string such as "v. 6.0."
Comments
You must free the returned string after you no longer need it.
SysGetROMTokenV40 Function
Purpose
Declared In
SysUtils.h
Prototype
status_t SysGetROMTokenV40 ( uint16_tcardNo
, uint32_ttoken
, 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
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_tnumOfElements
, int16_twidth
, const CmpFuncPtrcomparF
, const int32_tother
)
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
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_tother
);
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
SysQSort Function
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_tnumOfElements
, int16_twidth
, const CmpFuncPtrcomparF
, const int32_tother
)
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
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
, Int32other
)
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
Purpose
Return a random number anywhere from 0 to sysRandomMax
.
Declared In
SysUtils.h
Prototype
int16_t SysRandom (
int32_t newSeed
)
Parameters
Returns
SysStringByIndex Function
Purpose
Copy a string out of a string list resource.
Declared In
SysUtils.h
Prototype
char *SysStringByIndex ( DmOpenRefdbRef
, DmResourceIDresID
, uint16_tindex
, char*strP
, uint16_tmaxLen
)
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
Purpose
Copy a string out of a string list resource.
Declared In
SysUtils.h
Prototype
char *SysStringByIndexV50 ( DmResourceIDresID
, uint16_tindex
, char*strP
, uint16_tmaxLen
)
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.