MetaClass: 2.7 Utility Messages: Notification Messages

| Up: GEOS SDK TechDocs | Up | Prev: 2.6 Variable Data Messages | Next: 2.8 Options Messages

These messages are used by the various notification mechanisms throughout the system.

MSG_META_NOTIFY

void	MSG_META_NOTIFY(
        ManufacturerID manufID,
        word	notificationType,
        word 	data);

This message notifies the recipient that some change or action has taken place. The object must have registered for the notification. The type of change that has occurred depends on the notificationType argument.

One word of notification data is allowed, but this should not reference a handle which must at some point be destroyed. See MSG_META_NOTIFY_WITH_DATA_BLOCK for such requirements.

Source: Unrestricted.

Destination: Any object, or any of the GCNListSend() routines.

Interception: No general requirements, though particular notification types may place restrictions or requirements on such handling.

Parameters: manufID Manufacturer ID associated with notification type.

notificationType
What sort of notification is being announced. This value depends on the Manufacturer ID for that notification list. A list of valid types for the Geoworks Manufacturer ID is indicated by the GeoWorksNotificationType enumerated type.
data
One word of data, which will be placed in a vardata field. If more than one word is necessary, use MSG_META_NOTIFY_WITH_DATA_BLOCK , below.

Return: Nothing.

MSG_META_NOTIFY_WITH_DATA_BLOCK

void	MSG_META_NOTIFY_WITH_DATA_BLOCK(
        ManufacturerID manufID,
        word	notificationType,
        MemHandle data);

This message acts like MSG_META_NOTIFY , but it also carries a handle of a block of data. It is absolutely imperative that if this message is subclassed, the object call its superclass in the handler.

The data block must be set up to use the Block "reference count" mechanism, i.e. be sharable and initialized with MemInitRefCount() . Details on the count are noted below.

Source: Unrestricted.

Destination: Any object, or any of the GCNListSend... routines

Interception: Message must eventually arrive at the MetaClass handler, with the handle to the data block with the reference count intact, in order for the block to be freed when no longer referenced. Failure to do so will result in garbage being left on the heap, which will kill the system with repetitive occurrences.

Parameters: manufID Manufacturer ID associated with notification type.

notificationType
What sort of notification is being announced.
data
SHARABLE data block having a "reference count" initialized via MemInitRefCount() .

NOTE on data block reference counts:
The reference count should hold the total number of references of this data block. This count should be incremented before sending a message holding a reference to this block (using MemIncRefCount() ). Any messages passing such reference either must have a MetaClass handler which decrements this count and frees the block if it reaches zero or must call MemDecRefCount() (which does exactly that). GCNListSend() and similar functions add in the number of optrs in any list to which a message referring to this block is sent. Thus, when creating a block which will only be sent using GCNListSend() , this count should be initialized to zero. If the block is to be sent to one or more objects or GCNListSend() calls, the calling routine should call MemIncRefCount() before making the calls, being sure to call MemIncRefCount() additionally for any objects that the message is sent to, and then call MemDecRefCount () after the calls, to balance the increment call at the start.

Return: Nothing.

Warnings: This message must eventually reach the default MetaClass handler, so that the block can be freed when no longer referenced.

MSG_META_GCN_LIST_ADD

Boolean	MSG_META_GCN_LIST_ADD(@stack
        optr			dest,
        word 		listType,
        ManufacturerID 		listManuf);

This message adds the passed object to a particular notification list. It returns true if the object was successfully added, false otherwise. This message is the equivalent of GCNListAdd() for individual object GCN list.

Source: Unrestricted.

Destination: Object providing GCN services.

Interception: Unnecessary, as MetaClass does the right thing.

Parameters: dest Object to be added to list.

listType
GCNListType to add object to.
listManuf
Manufacturer ID associated with GCN list.

Return: Returns true if optr added, false otherwise.

MSG_META_GCN_LIST_REMOVE

Boolean	MSG_META_GCN_LIST_REMOVE(@stack
        optr	dest,
        word	listType,
        ManufacturerID listManuf);

This message removes the passed object from a particular notification list. It returns true if the object was successfully removed, false otherwise. This message is the equivalent of GCNListRemove() for an individual object's GCN list.

Source: Unrestricted.

Destination: Object providing GCN services.

Interception: Unnecessary, as MetaClass does the right thing.

Parameters: dest Object to be removed from list.

listType
Which list to remove object from.
listManuf
Manufacturer ID associated with GCN list.

Return: Returns true if optr found and removed, otherwise returns false .

MSG_META_GCN_LIST_SEND

void	MSG_META_GCN_LIST_SEND(@stack
        GCNListSendFlags 		flags,
        EventHandle		event,
        MemHandle 		block,
        word		listType,
        ManufacturerID 		listManuf);

This message sends the given event to all objects in a particular notification list. The event will be freed after being sent. This message is the equivalent of GCNListSend() for an individual object GCN list.

Parameters: flags Flags to pass on to GCNListSend().

event
Classed event to send to the list.
block
Handle of extra data block, if used, else NULL. This block must have a reference count, which may be initialized with MemInitRefCount() and incremented for any new usage with MemIncRefCount() . Methods in which they are passed are considered such a new usage, and must have MetaClass handlers which call MemDecRefCount() .
listType
Which GCN list to send event to.
listManuf
Manufacturer ID associated with GCN list.

Return: Nothing.

Structures: 

  typedef WordFlags GCNListSendFlags;
/* These flags may be combined using | and &:
	GCNLSF_SET_STATUS,
	GCNLSF_IGNORE_IF_STATUS_TRANSITIONING */
GCNLSF_SET_STATUS
Additionally saves the message as the list's current "status." The "status" message is automatically sent to any object adding itself to the list at a later point in time.
GCNLSF_IGNORE_IF_STATUS_TRANSITIONING
Optimization bit used to avoid lull in status when transitioning between two different sources--such as when the source is the current target object, and one has just lost, and another may soon gain, the exclusive. (The bit should be set only when sending the "null," "lost," or "not selected" status, as this is the event that should be discarded if another non-null status comes along shortly). Implementation is not provided by the kernel primitive routines, which ignore this bit, but may be provided by objects managing their own GCN lists. GenApplication responds to this bit by delaying the request until after the UI and application queues have been cleared, and then only sets the status as indicated if no other status has been set since the first request. Other objects may use their own logic to implement this optimization as is appropriate. Mechanisms which can not tolerate the delayed status setting nature of this optimization, or require that all changes are registered, should not pass this bit set.

MSG_META_GCN_LIST_FIND_ITEM

Boolean	MSG_META_GCN_LIST_FIND_ITEM(@stack
        optr		dest,
        word		listType,
        ManufacturerID		listManuf);

This message checks whether an object is on a particular GCN list.

Source: Unrestricted.

Destination: Any object providing GCN services.

Parameters: dest Optr of object that we are checking.

listType
GCNListType .
listManuf
ManufacturerID .

Return: true if object is on the GCN list.

Interception: Unnecessary.

MSG_META_GCN_LIST_DESTROY

void	MSG_META_GCN_LIST_DESTROY();

This message completely destroys the GCN setup for the caller. It frees all GCN lists, cached events, and overhead data storage. This should only be used when the object is being freed. You will likely never handle or call this message.

Source: Object providing GCN services, often in handler for MSG_META_FINAL_OBJ_FREE .

Destination: Self.

Interception: Unnecessary, as MetaClass does the right thing.

Parameters: Nothing.

Return: Nothing.

MSG_META_NOTIFY_OBJ_BLOCK_INTERACTIBLE

void	MSG_META_NOTIFY_OBJ_BLOCK_INTERICTABLE(
        MemHandle objBlock);

This message is sent to an object block's output object when the block changes from being not in-use to being in-use. An object may handle this message to monitor changes of in-use status.

Source: Kernel.

Destination: Object which is set as the output of an object block resource either by ObjBlockSetOutput() , or by being pre-defined in an application resource.

Interception: May be intercepted to learn about change in object block interactable status. No default handling is provided, though you may wish to pass the message onto the superclass in case it is interested in this data as well.

Parameters: objBlock Handle of object block.

Return: Nothing.

MSG_META_NOTIFY_OBJ_BLOCK_NOT_INTERACTIBLE

void	MSG_META_NOTIFY_OBJ_BLOCK_NOT_INTERACTIBLE(
        MemHandle objBlock);

This message is sent to an object block's output object when the block changes from being not in-use to being in-use. An object may handle this message to monitor changes of in-use status.

Source: Kernel.

Destination: Object which is set as the output of an Object Block resource either by ObjBlockSetOutput() , or by being pre-defined in an application resource.

Interception: May be intercepted to learn about change in object block interactable status. No default handling is provided, though you may wish to pass the message onto the superclass in case it is interested in this data as well.

Parameters: objBlock Handle of object block.

Return: Nothing.

MSG_META_VM_FILE_DIRTY

void	MSG_META_VM_FILE_DIRTY(
        FileHandle file);

This message is sent to all processes that have a VM file open when a block in the file becomes marked dirty for the first time. This is useful if many processes may be sharing a VM file. The VM file must be marked VMA_NOTIFY_DIRTY in its attributes.

Source: Kernel VM code.

Destination: ProcessClass object.

Interception: May be intercepted at process to do whatever is desired on this occurrence of this event. Default behavior in GenProcessClass sends notification to the current model GenDocumentGroupClass object.

Parameters: file Handle open to the VM file, from the receiving process's perspective.

Return: Nothing.

| Up: GEOS SDK TechDocs | Up | Prev: 2.6 Variable Data Messages | Next: 2.8 Options Messages