mirror of
https://gitlab.com/freepascal.org/fpc/source.git
synced 2025-10-21 07:01:51 +02:00
398 lines
21 KiB
ObjectPascal
398 lines
21 KiB
ObjectPascal
{$MACRO ON}
|
|
|
|
{$define Rsc := }
|
|
(******************************************************************************
|
|
*
|
|
* Copyright (c) 1998-2000 Palm, Inc. or its subsidiaries.
|
|
* All rights reserved.
|
|
*
|
|
* File: NotifyMgr.h
|
|
*
|
|
* Release: Palm OS SDK 4.0 (63220)
|
|
*
|
|
* Description:
|
|
* Include file for Notification Manager
|
|
*
|
|
* History:
|
|
* 6/15/98 JED - Created by Jesse Donaldson
|
|
* 12/23/99 jmp - Fix <> vs. "" problem.
|
|
* 10/19/00 PPL - Change cncNotifyCurrentConfigurationChange 'conf'
|
|
* to cncNotifyProfileEvent 'cncp'
|
|
*
|
|
*****************************************************************************)
|
|
|
|
unit notifymgr;
|
|
|
|
interface
|
|
|
|
uses palmos, coretraps, datamgr, localemgr, systemresources;
|
|
|
|
type
|
|
SysNotifyParamType = record
|
|
notifyType: UInt32; // What type of event occurred?
|
|
broadcaster: UInt32; // normally creator code of broadcasting app
|
|
notifyDetailsP: Pointer; // ptr to notification-specific data, if any
|
|
userDataP: Pointer; // user specified ptr passed back with notification
|
|
handled: Boolean; // true if event is handled yet
|
|
reserved2: UInt8;
|
|
end;
|
|
|
|
type
|
|
SysNotifyProc = function (var notifyParamsP: SysNotifyParamType): Err;
|
|
SysNotifyProcPtr = SysNotifyProc;
|
|
|
|
const
|
|
sysNotifyNormalPriority = 0; // clients should use this priority
|
|
|
|
sysNotifyBroadcasterCode = sysFileCSystem; // broadcaster code for events broadcast by the system
|
|
|
|
sysNotifyNoDatabaseID = $FFFFFFFF; // for system use only!!!
|
|
|
|
sysNotifyVersionNum = 1; // version of the NotifyMgr, obtained from the feature
|
|
|
|
// The queue is much smaller in debug builds so that we aren't tempted to overflow it
|
|
// (and larger for release builds so that when we do, it will work).
|
|
|
|
sysNotifyDefaultQueueSize = 30;
|
|
|
|
(*
|
|
Notify Manager Events:
|
|
|
|
Note that in general, for notifications regarding the creation of information
|
|
(e.g. sysNotifyDBAddedEvent) the broadcast goes out AFTER the fact (e.g.,
|
|
after the database has been created) and that notifications regarding
|
|
the deletion of information are broadcast BEFORE the fact. A notable and
|
|
unfortunate exception to this rule is the database deleted notification, which
|
|
is sent out after the fact.
|
|
|
|
The sleep & wake notifications require a little special attention. These
|
|
notifications are _not_ guaranteed to always be broadcast, and hence are unsuitable
|
|
for applications where syscall hardware must be shut off to conserve power when
|
|
we go to sleep. For example, the sleep notification will not be broadcast when
|
|
we do an emergency shutdown due to low battery conditions. Also note that any
|
|
sort of prolonged activity (especially displaying UI sich as a dialog) in response
|
|
to these noticfications can complicate things immensely. UI is very tricky because
|
|
these notifications are broadcast from SysHandleEvent. The result is that you may
|
|
receive more than one sleep notification if one of the notification clients puts up
|
|
a dialog or something, and it remains there long enough for another AutoOff event
|
|
to come through. There are also possible problems with reentrancy and stack space
|
|
usage since the notification is broadcast from SysHandleEvent inside an application's
|
|
event loop.
|
|
*)
|
|
|
|
sysNotifySyncStartEvent = Rsc('hots');
|
|
// Sent at the start of a hotsync.
|
|
// Always sent from UI thread.
|
|
// param: none
|
|
|
|
sysNotifySyncFinishEvent = Rsc('sync');
|
|
// Sent at the end of a hotsync.
|
|
// Always sent from UI thread.
|
|
// param: none
|
|
|
|
sysNotifyAntennaRaisedEvent = Rsc('tena');
|
|
// Sent when the antenna is raised on a
|
|
// Palm VII series device.
|
|
// Always sent from UI thread.
|
|
// param: none
|
|
|
|
sysNotifyResetFinishedEvent = Rsc('rstf');
|
|
// Broadcast after all app launchcodes
|
|
// are sent after a reset.
|
|
// Always sent from UI thread.
|
|
// param: none
|
|
|
|
sysNotifyForgotPasswordEvent = Rsc('bozo');
|
|
// Broadcast when the user presses the
|
|
// 'Forgotten Password' button in the
|
|
// security app, just before every database's
|
|
// private records are deleted.
|
|
|
|
sysNotifyTimeChangeEvent = Rsc('time');
|
|
// Broadcast when the time is changed by the user.
|
|
// param: Int32*, ptr to time change delta in
|
|
// seconds (e.g., a value of 100 means that the
|
|
// user set the clock ahead 100 seconds).
|
|
|
|
sysNotifySleepRequestEvent = Rsc('slpq');
|
|
// A "Sleep Request Event" is broadcast when the device
|
|
// is about to go to sleep, and is a chance for clients
|
|
// to do perform an action or even delay going to sleep
|
|
// for a little while. This may be broadcast multiple
|
|
// times if one or more clients defer the sleep. Parameter
|
|
// is a pointer to a SleepEventParamType. See below
|
|
// details on this structure. Note that this event is
|
|
// NOT guaranteed to be broadcast. See the big comment
|
|
// at the top of this list for important detials & warnings.
|
|
// Always sent from UI thread.
|
|
|
|
sysNotifySleepNotifyEvent = Rsc('slp!');
|
|
// A "Sleep Notify Event" is broadcast when the device is
|
|
// definitely going to sleep as soon as the broadcast
|
|
// is finished. Parameter is unused.
|
|
// Note that this event is NOT guaranteed to be broadcast.
|
|
// See the big comment at the top of this list for
|
|
// important detials & warnings.
|
|
// Always sent from UI thread.
|
|
|
|
sysNotifyEarlyWakeupEvent = Rsc('worm');
|
|
// ...the early bird gets the worm...
|
|
// Broadcast just after the device wakes up
|
|
// at the early stage where the screen may
|
|
// still be turned off and we may quickly go
|
|
// back to sleep after handling an alarm or
|
|
// charger event.
|
|
// Always sent from UI thread.
|
|
|
|
sysNotifyLateWakeupEvent = Rsc('lazy');
|
|
// Broadcast after the device wakes up
|
|
// at the later stage of the wakeup
|
|
// process after we turn the screen on,
|
|
// broadcast from EvtResetAutoOffEvent
|
|
// the first time it is called implying
|
|
// that the device will remain awake
|
|
// for at least a little while.
|
|
// Always sent from UI thread.
|
|
|
|
sysNotifyDisplayChangeEvent = Rsc('scrd');
|
|
// Sent when the display depth is
|
|
// changed, notifyDetailsP has old/new depth
|
|
// see SysNotifyDisplayChangeDetailsType
|
|
|
|
sysNotifyMenuCmdBarOpenEvent = Rsc('cbar');
|
|
// Sent by FormHandleEvent when a menuCmdBarOpenEvent
|
|
// passes through. The system will not open the toolbar
|
|
// if the 'handled' field is set in the parameter block,
|
|
// so most clients should not set it. The notification
|
|
// is provided so that Hack-like entities can catch
|
|
// it and add their own buttons to the bar. These
|
|
// buttons will show up to the left of cut/copy/paste/undo and
|
|
// to the right of everything else. Without this
|
|
// notification, people would hack SysHandleEvent... ick.
|
|
|
|
cncNotifyProfileEvent = Rsc('cncp');
|
|
// sent by the Connection Panel to inform its clients
|
|
// that the current configuration has change
|
|
// void * notifyDetailsP : has to be casted as UInt32
|
|
// to get the Broadcasted Profile ID user specified ptr
|
|
// passed back with notification
|
|
// void * userDataP : has to be casted as UInt16
|
|
// to get the device kind of the Broadcasted Profile ID
|
|
|
|
syssyscallConnectorAttachEvent = Rsc('ecna');
|
|
// Broadcast when anything is attached to
|
|
// the syscall connector.
|
|
|
|
syssyscallConnectorDetachEvent = Rsc('ecnd');
|
|
// Broadcast when anything is detached from
|
|
// the syscall connector.
|
|
|
|
sysNotifyCardInsertedEvent = Rsc('crdi');
|
|
// Broadcast when an ExpansionMgr card is
|
|
// inserted into a slot, and the slot driver
|
|
// calls ExpCardInserted. Always broadcast
|
|
// from UI task.
|
|
// ExpansionMgr will play a sound & attempt to
|
|
// mount a volume unless the corresponding
|
|
// bits in the 'handled' field are set by a
|
|
// notification handler (see ExpansionMgr.h).
|
|
// PARAMETER: slot number cast as void*
|
|
|
|
sysNotifyCardRemovedEvent = Rsc('crdo');
|
|
// Broadcast when an ExpansionMgr card is
|
|
// removed from a slot, and the slot driver
|
|
// calls ExpCardRemoved. Always broadcast
|
|
// from UI task.
|
|
// ExpansionMgr will play a sound & attempt to
|
|
// unmount a volume unless the corresponding
|
|
// bits in the 'handled' field are set by a
|
|
// notification handler (see ExpansionMgr.h).
|
|
// PARAMETER: slot number cast as void*
|
|
|
|
sysNotifyVolumeMountedEvent = Rsc('volm');
|
|
// Broadcast when a VFSMgr volume is
|
|
// mounted, Always broadcast from UI task.
|
|
// VFSMgr will run start.prc (if present),
|
|
// and SysUIAppSwitch to it or the Launcher
|
|
// unless the appropriate bits in the 'handled'
|
|
// field are set by a notification handler.
|
|
// PARAMETER: VFSAnyMountParamPtr cast as void*
|
|
|
|
sysNotifyVolumeUnmountedEvent = Rsc('volu');
|
|
// Broadcast AFTER a VFSMgr volume is
|
|
// unmounted, Always broadcast from UI task.
|
|
// VFSMgr will delete start.prc (if it was loaded).
|
|
// The volume ref number for the unmounted volume is
|
|
// NO LONGER VALID, so don't bother trying to use it.
|
|
// PARAMETER: volume refNum cast as void*
|
|
|
|
sysNotifyHelperEvent = Rsc('hlpr');
|
|
// Sent by Address Book (or any
|
|
// 3rd party application) to
|
|
// communicate with Phone Apps
|
|
|
|
sysNotifyPOSEMountEvent = Rsc('pose');
|
|
// Sent by HostFS to communicate with itself,
|
|
// saving on stack depth.
|
|
|
|
sysNotifyLocaleChangedEvent = Rsc('locc');
|
|
// Notify apps/panel that the system locale
|
|
// has changed.
|
|
// This is broadcast by the language picker after it
|
|
// has changed the locale.
|
|
// Always sent from UI thread.
|
|
// param: ptr to SysNotifyLocaleChangedType
|
|
|
|
sysNotifyRetryEnqueueKey = Rsc('retk');
|
|
// An EvtEnqueueKey failed, so retry.
|
|
|
|
sysNotifyGotUsersAttention = Rsc('attn');
|
|
// Got users attention.
|
|
|
|
sysNotifyDBDeletedEvent = Rsc('dbs-');
|
|
// broadcast AFTER a database is removed from the device.
|
|
// Note that the database ID in the parameter block is
|
|
// NO LONGER VALID, and you WILL CRASH the device if you
|
|
// try to pass it to any DataMgr routines.
|
|
// notifyDetailsP: ptr to SysNotifyDBDeletedType.
|
|
|
|
sysNotifyDeviceUnlocked = Rsc('unlk');
|
|
// Broadcasted by the Security app After the device is
|
|
//unlocked.
|
|
//notifyDetailsP: none
|
|
|
|
sysNotifyPhoneEvent = Rsc('fone');
|
|
// Sent by third-party applications to communicate
|
|
// with built-in or syscall phones.
|
|
// NOTE THAT THIS EVENT IS FOR FUTURE USE
|
|
|
|
sysNotifyNetLibIFMediaEvent = Rsc('neti');
|
|
// Broadcasted by NetLib to communicate its interfaces media Up and Down requests
|
|
// to registered Apps.
|
|
// notifyDetailsP: ptr to SysNotifyNetLibIFMediaType.
|
|
|
|
sysNotifyDeleteProtectedEvent = Rsc('-pdb');
|
|
// Broadcast BEFORE a database is removed from the device when a user
|
|
// or installer application wants to remove a protected database. This
|
|
// will ONLY be issued from the UI task and should be issued before each
|
|
// user driven deletion that targets a protected database that the app
|
|
// running does not own (i.e. needs to request be unprotected).
|
|
// This gives the unlucky client a chance to do any required
|
|
// cleanup work. Note that if an application has multiple protected
|
|
// databases, this notification may be sent out more than once.
|
|
// notifyDetailsP: ptr to SysNotifyDBInfoType.
|
|
|
|
sysNotifyIrDASniffEvent = Rsc('irda');
|
|
// Sent by IrDA sniffing code when an incomming IrDA frame is detected
|
|
|
|
// for sysNotifyDisplayChangeEvent
|
|
type
|
|
SysNotifyDisplayChangeDetailsTag = record
|
|
oldDepth: UInt32;
|
|
newDepth: UInt32;
|
|
end;
|
|
SysNotifyDisplayChangeDetailsType = SysNotifyDisplayChangeDetailsTag;
|
|
|
|
// For sysNotifyLocaleChangedEvent
|
|
type
|
|
SysNotifyLocaleChangedTag = record
|
|
oldLocale: LmLocaleType;
|
|
newLocale: LmLocaleType;
|
|
end;
|
|
SysNotifyLocaleChangedType = SysNotifyLocaleChangedTag;
|
|
|
|
// Possible values for the sleep-reason for the sysNotifySleepEvent
|
|
const
|
|
sysSleepPowerButton = 0;
|
|
sysSleepAutoOff = 1;
|
|
sysSleepResumed = 2;
|
|
sysSleepUnknown = 3;
|
|
|
|
// for sysNotifySleepRequestEvent
|
|
type
|
|
SleepEventParamTag = record
|
|
reason: UInt16; // contains the reason we are going to sleep. See above list for possible values.
|
|
deferSleep: UInt16; // Only used for the sysNotifySleepRequestEvent, this should be incremented by
|
|
// clients that want to defer the sleep. They are then responsible for enqueing
|
|
// a resumeSleepChr in the event queue.
|
|
end;
|
|
SleepEventParamType = SleepEventParamTag;
|
|
|
|
// for sysNotifyDeleteProtectedEvent, and possibly others...
|
|
type
|
|
SysNotifyDBInfoTag = record
|
|
dbID: LocalID; // database ID of dabatase
|
|
cardNo: UInt16; // card number that dabatase resides on
|
|
attributes: UInt16; // database attributes
|
|
dbName: array [0..dmDBNameLength-1] of Char; // name of database
|
|
creator: UInt32; // creator code of dabatase
|
|
type_: UInt32; // type of dabatase
|
|
end;
|
|
SysNotifyDBInfoType = SysNotifyDBInfoTag;
|
|
|
|
// for sysNotifyDBDeletedEvent
|
|
type
|
|
SysNotifyDBDeletedTag = record
|
|
oldDBID: LocalID; // old database ID of dabatase, no longer valid
|
|
cardNo: UInt16; // card number that dabatase resides on
|
|
attributes: UInt16; // database attributes
|
|
dbName: array [0..dmDBNameLength-1] of Char; // name of database
|
|
creator: UInt32; // creator code of dabatase
|
|
type_: UInt32; // type code of dabatase
|
|
end;
|
|
SysNotifyDBDeletedType = SysNotifyDBDeletedTag;
|
|
|
|
(*
|
|
Possible event types to be added in the future:
|
|
NOTE that these are NOT implemented yet!!!!
|
|
|
|
sysNotifyDBAddedEvent = Rsc('dbs+');
|
|
// Broadcast after a database is added to the device
|
|
// param: ptr to SysNotifyDBInfoType.
|
|
|
|
sysNotifyInitializeEvent = Ord('helo');
|
|
// broadcast to an app after its installed
|
|
// so it can do any necessary initalization
|
|
// This event is always broadcast.
|
|
// param: ptr to SysNotifyDBInfoType.
|
|
|
|
sysNotifyCleanupEvent = Ord('gbye');
|
|
// broadcast to an app just before its deleted
|
|
// so it can do any necessary cleanup work.
|
|
// This event is always broadcast.
|
|
// The database's type will have been set to
|
|
// sysFileTTemp so that if case the handler
|
|
// crashes, the DB will be deleted on reset.
|
|
// param: ptr to SysNotifyDBInfoType.
|
|
|
|
sysNotifyCardChangedEvent = Ord('card');
|
|
// broadcast when the owner's business card
|
|
// has changed, allowing apps to adjust for that.
|
|
// param: ptr to new owner data.
|
|
*)
|
|
|
|
function SysNotifyRegister(cardNo: UInt16; dbID: LocalID; notifyType: UInt32;
|
|
callbackP: SysNotifyProcPtr; priority: Int8; userDataP: Pointer): Err; syscall sysTrapSysNotifyRegister;
|
|
|
|
function SysNotifyUnregister(cardNo: UInt16; dbID: LocalID; notifyType: UInt32; priority: Int8): Err; syscall sysTrapSysNotifyUnregister;
|
|
|
|
(*
|
|
* WARNING: Never call SysNotifyBroadcast from a background task
|
|
* (or from any code that might be called from a BG task)
|
|
* with the memory semaphore reserved. Deadlock will
|
|
* result when the broadcast is deferred and the UI task
|
|
* tries to acquire the mem semaphore in order to send it out.
|
|
*)
|
|
function SysNotifyBroadcast(var notify: SysNotifyParamType): Err; syscall sysTrapSysNotifyBroadcast;
|
|
|
|
function SysNotifyBroadcastDeferred(var notify: SysNotifyParamType; paramSize: Int16): Err; syscall sysTrapSysNotifyBroadcastDeferred;
|
|
|
|
// Kick off a notification from an interrupt handler.
|
|
// Note: non-interrupt code should use SysNotifyBroadcast
|
|
function SysNotifyBroadcastFromInterrupt(notifyType: UInt32; broadcaster: UInt32;
|
|
notifyDetailsP: Pointer): Err; syscall sysTrapSysNotifyBroadcastFromInterrupt;
|
|
|
|
implementation
|
|
|
|
end.
|