Documentation  |   Table of Contents   |  < Previous   |  Next >  

114    SystemMgr.h

Porting Applications to Palm OS® Cobalt

Exploring Palm OS®

Deleted APIs ^TOP^

Table 114.1  Deleted functions 

Deleted API

Use instead

SysBatteryInfoV20()

SysBatteryInfo()

SysGetTrapAddress()

SysGetEntryAddresses()

SysLibFind()

SysLibLoad()

SysLoadModule() or SysLoadModuleByDatabaseID()

SysLibRemove()

SysUnloadModule()

SysSetTrapAddress()

In Palm OS Cobalt functions aren't accessed via traps, so this 68K function has no direct counterpart. This function was most often used to patch a given function, however, and there is a mechanism for doing that in Palm OS Cobalt. The operating system is presented to an application as a set of shared libraries; see Chapter 6, "Shared Libraries," of Exploring Palm OS: System Management for more information.

SysTicksPerSecond()

The SysTicksPerSecond() macro is the most straightforward substitution. However, note that Palm OS Cobalt introduces a number of SysTimeIn... and SysTimeTo... macros that convert between a system time value (a system tick count) and a more natural set of units such as seconds or milliseconds. Applications should be rewritten to employ these macros and deal with time using more natural units.

The functions listed in Table 114.2 were documented as "system use only" and should not have been used by applications. Thse functions are not publicly declared in Palm OS Cobalt.

Table 114.2  Deleted "system use only" functions 

SysAppExit()

SysAppStartup()

SysBatteryDialog()

SysColdBoot()

SysDisableInts()

SysDoze()

SysEvGroupCreate()

SysEvGroupRead()

SysEvGroupSignal()

SysEvGroupWait()

SysInit()

SysKernelInfo()

SysLaunchConsole()

SysLibClose()

SysLibInstall()

SysLibOpen()

SysLibSleep()

SysLibTblEntry()

SysLibWake()

SysMailboxCreate()

SysMailboxDelete()

SysMailboxFlush()

SysMailboxSend()

SysMailboxWait()

SysNewOwnerID()

SysPowerOn()

SysResSemaphoreCreate()

SysResSemaphoreDelete()

SysResSemaphoreRelease()

SysResSemaphoreReserve()

SysRestoreStatus()

SysSemaphoreDelete()

SysSemaphoreSet()

SysSetA5()

SysSetPerformance()

SysTaskCreate()

SysTaskDelete()

SysTaskID()

SysTaskResume()

SysTaskSetTermProc()

SysTaskSuspend()

SysTaskSwitching()

SysTaskTrigger()

SysTaskWait()

SysTaskWaitClr()

SysTaskWake()

SysTimerCreate()

SysTimerDelete()

SysTimerRead()

SysTimerWrite()

SysTranslateKernelErr()

SysUILaunch()

SysUnimplemented()

Table 114.3  Deleted structures

Deleted API

Use instead

SysAppInfoType

Nothing. This data structure was only used by functions documented as "system use only," so it should never have been used by applications.

SysAppPrefsType

ARMAppLaunchPrefsType

SysExtPrefsType

Nothing. This data structure was not used by any exported APIs, so it should never have been used by applications.

SysHSIResponseType

Nothing. This data structure was not used by any exported APIs, so it should never have been used by applications.

SysLibTblEntryType

The Palm OS Protein headers don't declare a comparable structure, but comparable information to what this structure contained can be obtained by calling either or both SysGetEntryAddresses() or SysGetModuleGlobals().

SysMailboxMsgType

Nothing. This data structure was only used by functions documented as "system use only," so it should never have been used by applications.

Table 114.4  Deleted types

Deleted API

Use instead

SysAppInfoPtr

Nothing. This was a pointer to a data structure that was only used by functions documented as "system use only," so it should never have been used by applications.

SysAppPrefsPtr

ARMAppLaunchPrefsType *

SysLibTblEntryPtr

See SysLibTblEntryType in Table 114.3, above.

Table 114.5  Deleted #defines 

Deleted API

Use instead

sysDbgCommLibraryRefNum

sysDbgCommPortID

sysErrDelayWakened

sysErrInvalidID

sysErrMb..., sysErrNotAsleep, sysErrNotAsleepN

Nothing - these errors were only used by the pre Palm OS Cobalt kernel.

sysErrSemInUse

sysEvGroup...

Nothing. These constants were only used by functions previously documented as "system use only" and therefore should never have been used by applications.

sysExtPrefsNoOverlayFlag

sysExtPrefsVers

sysFtrNumCharEncodingFlags

sysFtrNumCharEncodingFlags68K, or TxtGetEncodingFlags(LmGetSystemLocale(NULL));

sysFtrNumCountry

sysFtrNumCountry68K, or LmGetLocaleSetting(..., lmChoiceLocale, ...)

sysFtrNumEncoding

sysFtrNumEncoding68K, or query the locale with one of the LmGet...Locale() functions defined in LocaleMgr.h.

sysFtrNumErrorCheckLevel

sysFtrNumGremlinsSupportGlobals

Nothing; Gremlins isn't supported in Palm OS Cobalt version 6.0.

sysFtrNumIntlMgr

Nothing; the Text Manager, which is always present on all Palm OS Cobalt devices, should be used instead of the International Manager.

sysFtrNumLanguage

sysFtrNumLanguage68K, or LmGetLocaleSetting(..., lmChoiceLocale, ...)

sysFtrNumProcessorARM925T

One of the other sysFtrNumProcessor... constants, or, better, macros such as sysFtrNumProcessorIsARM().

sysHSISerialInquiryBaud

sysHSISerialInquiryString

sysHSISerialInquiryStringLen

sysHSISerialInquiryTimeout

sysHSISerialInterChrTimeout

sysInvalidRefNum

sysMaxHSIResponseSize

sysNotifyHSIDebugEvent

sysNotifyHSINoConnectionEvent

sysNotifyHSIPeripheralNotRespondingEvent

sysNotifyHSIPeripheralRespondedEvent

sysNotifyHSIRS232CradleEvent

sysNotifyHSIRS232PeripheralEvent

sysNotifyHSISerialPortInUseEvent

sysNotifyHSIUSBCradleEvent

sysNotifyHSIUSBPeripheralEvent

sysTicksPerSecond

The SysTicksPerSecond() macro is the most straightforward substitution. However, note that Palm OS Cobalt introduces a number of SysTimeIn... and SysTimeTo... macros that convert between a system time value (a system tick count) and a more natural set of units such as seconds or milliseconds. Applications should be rewritten to employ these macros and deal with time using more natural units.

Table 114.6  Deleted application-defined functions 

Deleted API

Use instead

SysLibEntryProcPtr()

PilotMain()

SysTermProcPtr()

Nothing; this was used in conjunction with a function previously documented as "system use only" and so shouldn't have been used by any applications.

SysTimerProcPtr()

Nothing; this was used in conjunction with a function previously documented as "system use only" and so shouldn't have been used by any applications.

Modified APIs ^TOP^

Table 114.7  Modified functions 

Modified API

Description of change

status_t SysAppLaunch (DatabaseID, uint16_t, MemPtr, uint32_t *)

The database containing the application to be launched is now identified solely by a DatabaseID, rather than a separate cardNo and dbID. The launchFlags parameter has been removed. Note that applications should avoid this function; they should use SysAppLaunchLocal() or SysAppLaunchRemote() instead.

uint16_t SysBatteryInfo (Boolean, uint16_t *, uint16_t *, uint16_t *, uint32_t *, SysBatteryKind *, Boolean *, uint8_t *)

A new parameter, maxMilliSecsP, has been added; this function now can also return the estimated amount of time, in milliseconds, before the device will shut down due to lack of power.

status_t SysBroadcastActionCode (uint16_t, void *)

The command block pointer, formerly a MemPtr, is now simply declared as a void *.

Boolean SysCreateDataBaseList (uint32_t, uint32_t, uint16_t *, MemHandle *, Boolean, DmFindType)

The final parameter has been added: with it you specify the type of database to be searched for: schema, extended, classic, or a combination of the three.

status_t SysCurAppDatabase (DatabaseID *)

Because the concept of logical memory cards isn't supported in Palm OS Cobalt, this function simply returns a DatabaseID rather than returning a card number and local ID.

status_t SysGetROMToken (uint32_t, uint8_t **, uint16_t *)

The cardNo parameter has been dropped.

status_t SysSemaphoreCreate (uint32_t, uint32_t, uint32_t, SysHandle *)

This function, formerly system use only, is now available to developers. See the description of SysSemaphoreCreate() in Chapter 36, "SysThread," of Exploring Palm OS: System Management.

status_t SysSemaphoreSignal (SysHandle)

This function, formerly system use only, is now available to developers. See the description of SysSemaphoreSignal() in Chapter 36, "SysThread," of Exploring Palm OS: System Management.

status_t SysSemaphoreWait (SysHandle, timeoutFlags_t, nsecs_t)

This function, formerly system use only, is now available to developers. See the description of SysSemaphoreWait() in Chapter 36, "SysThread," of Exploring Palm OS: System Management.

void SysSleep (void)

This system use only function no longer takes any parameters.

status_t SysUIAppSwitch (DatabaseID, uint16_t, MemPtr, uint32_t)

The card number and local ID parameters have been dropped in favor of a single DatabaseID parameter. As well, the final parameter, cmdPBSize, has been added so you can specify the size of the parameter block.

Table 114.8  Modified structures 

Modified API

Description of change

SysAppLaunchCmdCardType

The err field is now of type status_t, and various padding and reserved fields have been added.

SysAppLaunchCmdHandleSyncCallAppType

The replyErr field is now of type status_t, and a second reserved field has been added immediately before replyErr.

SysAppLaunchCmdInitDatabaseType

Padding bytes have been added.

SysAppLaunchCmdOpenDBType

The card number and local ID fields have been dropped in favor of a single MemHandle parameter, dbH.

SysAppLaunchCmdPnpsType

The error field is now of type status_t, and a reserved field has been added to the end of the structure.

SysDBListItemType

The cardNo field has been dropped, and a 16-bit padding field has been added.

Table 114.9  Modified #defines

Modified API

Description of change

sysAppLaunchFlagPrivateSet

Now includes sysAppLaunchFlagGlobalsAvailable in addition to sysAppLaunchFlagSubCall and sysAppLaunchFlagDataRelocated.

Table 114.10  Modified enumerated types

Modified API

Description of change

SysBatteryKind

Formerly an enum, this is now a typedef that takes one of the values defined by the SysBatteryKindTag enum.

SysBatteryState

Formerly an enum, this is now a typedef that takes one of the values defined by the SysBatteryStateTag enum.

Unchanged APIs ^TOP^

Table 114.11  Unchanged functions 

PilotMain()

SysCreatePanelList()

SysGetOrientation()

SysGetOrientationTriggerState()

SysGetOSVersionString()

SysGetStackInfo()

SysHandleEvent()

SysLCDBrightness()

SysLCDContrast()

SysReset()

SysSetAutoOffTime()

SysSetOrientation()

SysSetOrientationTriggerState()

SysTaskDelay()

SysUIBusy()

Table 114.12  Unchanged macros

sysFtrNumProcessorIs68K()

sysFtrNumProcessorIsARM()

sysGetROMVerBuild()

sysGetROMVerFix()

sysGetROMVerMajor()

sysGetROMVerMinor()

sysGetROMVerStage()

sysMakeROMVersion()

Table 114.13  Unchanged structures

SysAppLaunchCmdFailedAppNotifyType

SysAppLaunchCmdSaveDataType

SysAppLaunchCmdSyncCallApplicationTypeV10

SysAppLaunchCmdSystemResetType

Table 114.14  Unchanged #defines 

pwrErrBacklight

pwrErrBeam

pwrErrGeneric

pwrErrNone

pwrErrRadio

sysAppLaunchCmdAddRecord

sysAppLaunchCmdAlarmTriggered

sysAppLaunchCmdAntennaUp

sysAppLaunchCmdAttention

sysAppLaunchCmdCardLaunch

sysAppLaunchCmdCountryChange

sysAppLaunchCmdCustomBase

sysAppLaunchCmdDisplayAlarm

sysAppLaunchCmdEventHook

sysAppLaunchCmdExgAskUser

sysAppLaunchCmdExgGetData

sysAppLaunchCmdExgPreview

sysAppLaunchCmdExgReceiveData

sysAppLaunchCmdFailedAppNotify

sysAppLaunchCmdFepPanelAddWord

sysAppLaunchCmdFind1

sysAppLaunchCmdGoTo

sysAppLaunchCmdGoToURL

sysAppLaunchCmdHandleSyncCallApp

sysAppLaunchCmdInitDatabase

sysAppLaunchCmdLookup

sysAppLaunchCmdLookupWord

sysAppLaunchCmdMultimediaEvent

sysAppLaunchCmdNormalLaunch

sysAppLaunchCmdNotify

sysAppLaunchCmdOpenDB

sysAppLaunchCmdPanelCalledFromApp

sysAppLaunchCmdReturnFromPanel

sysAppLaunchCmdSaveData

sysAppLaunchCmdSyncCallApplicationV10

sysAppLaunchCmdSyncNotify

sysAppLaunchCmdSyncRequest

sysAppLaunchCmdSyncRequestLocal

sysAppLaunchCmdSyncRequestRemote

sysAppLaunchCmdSystemLock

sysAppLaunchCmdSystemReset2

sysAppLaunchCmdTimeChange3

sysAppLaunchCmdURLParams

sysAppLaunchFlagDataRelocated

sysAppLaunchFlagNewGlobals

sysAppLaunchFlagNewStack

sysAppLaunchFlagNewThread

sysAppLaunchFlagSubCall

sysAppLaunchFlagUIApp

sysAppLaunchNppiNoUI

sysAppLaunchNppiUI

sysAppLaunchPnpsPreLaunch

sysAppLaunchStartFlagAutoStart

sysAppLaunchStartFlagNoAutoDelete

sysAppLaunchStartFlagNoUISwitch

sysDialLaunchCmdDial

sysDialLaunchCmdHangUp

sysDialLaunchCmdLast

sysErrBufTooSmall

sysErrLibNotFound

sysErrNoFreeLibSlots)

sysErrNoFreeRAM

sysErrNoFreeResource

sysErrNotAllowed

sysErrNotInitialized

sysErrOutOfOwnerIDs

sysErrParamErr

sysErrPrefNotFound

sysErrRomIncompatible

sysErrTimeout

sysFileDescStdIn

sysFtrCreator

sysFtrDefaultBoldFont

sysFtrDefaultFont

sysFtrNumAccessorTrapPresent

sysFtrNumBacklight

sysFtrNumDefaultCompression

sysFtrNumDisplayDepth

sysFtrNumEncryption

sysFtrNumEncryptionMaskDES

sysFtrNumHwrMiscFlags

sysFtrNumHwrMiscFlagsExt

sysFtrNumInputAreaFlags

sysFtrNumNotifyMgrVersion

sysFtrNumOEMCompanyID

sysFtrNumOEMDeviceID

sysFtrNumOEMHALID

sysFtrNumOEMROMVersion

sysFtrNumProcessor328

sysFtrNumProcessor68KIfZero

sysFtrNumProcessorARM710A

sysFtrNumProcessorARM720T

sysFtrNumProcessorARM7TDMI

sysFtrNumProcessorARM920T

sysFtrNumProcessorARM922T

sysFtrNumProcessorARM925

sysFtrNumProcessorARMIfNotZero

sysFtrNumProcessorEZ

sysFtrNumProcessorID

sysFtrNumProcessorMask

sysFtrNumProcessorStrongARM

sysFtrNumProcessorSuperVZ

sysFtrNumProcessorVZ

sysFtrNumProcessorx86

sysFtrNumProcessorXscale

sysFtrNumProductID

sysFtrNumROMVersion

sysFtrNumVendor

sysFtrNumWinVersion

sysNotifyErrBroadcastBusy

sysNotifyErrBroadcastCancelled

sysNotifyErrDuplicateEntry

sysNotifyErrEntryNotFound

sysNotifyErrNoStackSpace

sysNotifyErrQueueEmpty

sysNotifyErrQueueFull

sysOrientationLandscape

sysOrientationPortrait

sysOrientationReverseLandscape

sysOrientationReversePortrait

sysOrientationTriggerDisabled

sysOrientationTriggerEnabled

sysOrientationUser

sysROMStageAlpha

sysROMStageBeta

sysROMStageDevelopment

sysROMStageRelease

sysROMTokenSnum

sysSvcLaunchCmdGetQuickEditLabel

sysSvcLaunchCmdGetServiceID

sysSvcLaunchCmdGetServiceInfo

sysSvcLaunchCmdGetServiceList

sysSvcLaunchCmdLast

sysSvcLaunchCmdSetServiceID

1. Unlike other versions of Palm OS, in Palm OS Cobalt the sysAppLaunchCmdFind launch code is only sent to the active application, to 68K applications, and to those applications that have the ALPF_FLAG_NOTIFY_FIND attribute set to true in their Application Launch Preferences Resource.
2. Unlike other versions of Palm OS, in Palm OS Cobalt the sysAppLaunchCmdSystemReset launch code is only sent to 68K applications and to those applications that have the ALPF_FLAG_NOTIFY_RESET attribute set to true in their Application Launch Preferences Resource.
3. Unlike other versions of Palm OS, in Palm OS Cobalt the sysAppLaunchCmdTimeChange launch code is only sent to to 68K applications and to those applications that have the ALPF_FLAG_NOTIFY_TIME_CHANGE attribute set to true in their Application Launch Preferences Resource.