path: root/packages/extra/palmunits/notifymgr.pp

{$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.