General Change Notification: 3.1 System Notification: Registering for System Notification

Whenever an object or process needs to be notified of some system change, it must call the routine GCNListAdd() to add itself to the list for that particular change. GCNListAdd () finds the appropriate general change notification list--creating a new one if none currently exists--and adds the optr of the new object to the end of that list. You may add the optr to the GCN list at any time during the process' or object's life, but it is usually convenient for a process to be added in its MSG_GEN_PROCESS_OPEN_APPLICATION or for an object that is on the active list to be added in its MSG_META_ATTACH handler.

Each optr in a GCN list should have a notification ID attached to it. (The combination of a manufacturer ID and a notification type comprises an element's specific notification ID.) GCNListAdd() must be passed the optr of the object to add, along with a notification ID. For each separate notification ID, a separate GCN list is needed and will be created automatically.

The GCN routines use a word of data, GCNStandardListType , to represent the notification type. The currently recognized GCNStandardListType types for MANUFACTURER_ID_GEOWORKS are

GCNSLT_FILE_SYSTEM
This GCNStandardListType is used for notification of a file system change. Parties on this list will receive the system messages MSG_NOTIFY_FILE_CHANGE and MSG_NOTIFY_DRIVE_CHANGE .
GCNSLT_APPLICATION
This GCNStandardListType is used for notification of a starting or exiting application. Parties on this list will receive the system messages MSG_NOTIFY_APP_STARTED and MSG_NOTIFY_APP_EXITED .
GCNSLT_DATE_TIME
This GCNStandardListType is used for notification of a date/time change in the system's internal clock. Note that this will not tell you about timer ticks--the only time changes that will come up are those resulting from system restarts and time changes by the user. Parties on this list will receive the system message MSG_NOTIFY_DATE_TIME_CHANGE. This message does not pass any further information, so your message handler should be able to take care of any changes by itself (such as calling the internal clock for an updated value).
GCNSLT_DICTIONARY
This GCNStandardListType is used for notification of a user dictionary change. Parties on this list will receive the system message MSG_NOTIFY_USER_DICT_CHANGE.
GCNSLT_KEYBOARD_OBJECTS
This list is used for notification when the user has chosen a different keyboard layout. Parties on this list will receive the system message MSG_NOTIFY_KEYBOARD_LAYOUT_CHANGE.
GCNSLT_EXPRESS_MENU_CHANGE
This GCNStandardListType notifies various system utilities that an express menu has been created or destroyed. The recipient receives the optr of the Express Menu Control. This list should be used in conjunction with the GCNSLT_EXPRESS_MENU_OBJECTS list. Objects on this list receive MSG_NOTIFY_EXPRESS_MENU_CHANGE, which itself passes a GCNExpressMenuNotificationType (either GCNEMNT_CREATED or GCNEMNT_DESTROYED) and the optr of the Express Menu Control affected.
GCNSLT_INSTALLED_PRINTERS
This list notifies objects when a printer is either installed or removed. The recipient of MSG_PRINTER_INSTALLED_REMOVED might want to call SpoolGetNumPrinters() to learn if any printer or fax drivers are currently installed.
GCNSLT_SHUTDOWN_CONTROL
This GCNStandardListType is used for system shutdown control. Parties on a list of this type will receive the system message MSG_META_CONFIRM_SHUTDOWN which itself passes a GCNShutdownControlType (either GCNSCT_SUSPEND, GCNSCT_SHUTDOWN, or GCNSCT_UNSUSPEND). Shutdown Control is documented in the Applications and Geodes chapter.
GCNSLT_TRANSFER_NOTIFICATION
This list notifies objects that a transfer item within the clipboard has changed (or been freed). Parties on this list will receive the system message MSG_META_CLIPBOARD_
NOTIFY_NORMAL_TRANSFER_ITEM_CHANGED and MSG_META_CLIPBOARD_NOTIFY_TRANSFER_ITEM_FREED.
GCNSLT_EXPRESS_MENU_OBJECTS
This list contains all Express Menu Control objects in the system. Typically this list is used to add a control panel item or a DOS task list item to all express menu Control objects. This can be done by sending MSG_EXPRESS_MENU_CONTROL_CREATE_ITEM to the GCN list with GCNListSend() .
GCNSLT_TRANSPARENT_DETACH
This list contains all application objects that may be transparently detached if the system runs short of heap space, in least recently used (LRU) order. This list should only be used if transparent launch mode is in use.
GCNSLT_TRANSPARENT_DETACH_DA
This list contains a list of transparently detachable desk accessories if the system runs short of heap space. This list should only be used if transparent launch mode is in use. Objects should not be detached unless all detachable, full-screen applications have been detached.
GCNSLT_REMOVABLE_DISK
This list is used to store all application and document control objects that originate from a removable drive. If the disk they originate on is removed, they will be notified to shut themselves down with MSG_META_DISK_REMOVED.

These pre-defined notification types are intended only for use with MANUFACTURER_ID_GEOWORKS. Other manufacturers wishing to intercept their own system changes must define their own change types under their respective manufacturer IDs if they are unable to use MANUFACTURER_ID_GEOWORKS.

Code Display 9-1 Adding a Process Object to a GCN List

@method MyProcessClass, MSG_GEN_PROCESS_OPEN_APPLICATION {
    optr			myThread;

    @callsuper;			/* Do default MSG_GEN_PROCESS_OPEN_APPLICATION */

/* Casts the return value for the process handle into an optr */

    myThread = ConstructOptr(GeodeGetProcessHandle(), NullChunk);

/* myThread (the process) is added to notification of file changes */

    GCNListAdd(myThread, MANUFACTURER_ID_GEOWORKS, GCNSLT_FILE_SYSTEM);
}

GEOS SDK TechDocs |

3 System Notification | Next:

3.2 Handling System Notification