Class Documentation
Broadcast |
1.0 |
ID_BROADCAST |
Beta |
System |
system/event.h |
July 2001 |
Rocklyte Systems |
Rocklyte Systems, 1998-2001. All rights reserved. |
Description
The Broadcast class provides a central area for event broadcasting. This
class is designed so that there is only ever one Broadcast object in the entire
system (known as the "SystemBroadcaster", which is set up by the kernel). By
subscribing to the SystemBroadcaster, you can listen to system-wide events that
will provide you with information on the system's activity.
System events can cover a wide variety of types of activity, such as a new
disk being inserted, file activity, various types of hardware I/O, user
activity, system alerts and so on. Each event is handled by a particular area
of the system. For example, sending file related events is handled by the
FileSystem module. When an event is signalled by one of these handlers, the
system will call all of the subscribers that are hooked into that event.
To subscribe to a system event, call the
SubscribeEvent() method. A
subscription can be terminated by calling the
UnsubscribeEvent() method.
Methods
The Broadcast class implements the following methods:
Events
The Broadcast class supports the following events:
FileCreated | Indicates that a new file has been created. |
FileDeleted | Indicates that an existing file has been destroyed. |
NewTask | Indicates that a new Task has been activated. |
TaskCrashed | Indicates that a Task has crashed or self-destructed. |
Broadcast() |
Broadcasts an event. |
LONG EventID | The ID of the event that you are broadcasting. |
OBJECTID ObjectID | Reference to an object that is relevant to the event - NULL if not applicable. |
LARGE Integer | A 64-bit value that is relevant to the event - NULL if not applicable. |
APTR Buffer | Reference to a data buffer with more information on the event - NULL if not applicable. |
LONG Size | The size of the Buffer - NULL if not applicable. |
|
The Broadcast method is used to broadcast events. When a Broadcast object
receives this method, it will check the specified EventID to see if any
subscribers are listening to that particular event type. If this is the case,
it will send action messages to each subscriber with the information provided
in the ObjectID, Integer and Buffer fields.
Messages are passed to subscribers using the EventMessage action. See
the Action Support Guide
for more information on this action type.
ERR_Okay | The event was broadcast successfully. |
ERR_AccessMemory | Access to the internal subscription array was denied. |
|
|
SubscribeEvent() |
Subscribes objects to broadcast events. |
OBJECTID SubscriberID | The unique ID of the object that will be subscribed to the event. |
LONG EventID | The event ID that you are subscribing to. |
|
The SubscribeEvent() method is used to subscribe objects to Broadcast
events. To subscribe to an event, you simply need to provide the unique ID
of the object that will be subscribed, and the event ID that you wish to
subscribe it to.
When someone calls a matching event on the Broadcast object that you are
listening to, all relevant event subscribers will be notified. This is done
by sending each subscriber an event message (AC_EventMessage) with information
on the event ID and data specifically related to the event type.
When you need to terminate an event subscription, use the
UnsubscribeEvent() method.
ERR_Okay | Subscription successful. |
ERR_Args | Invalid arguments were specified. |
ERR_AllocMemory | Failed to allocate a new subscription array. |
|
|
UnsubscribeEvent() |
Unsubscribes objects from broadcast events. |
OBJECTID SubscriberID | The unique ID of the object that will be unsubscribed from the event. |
LONG EventID | The event ID that the object is being unsubscribed from. |
|
If you have subscribed to an event using the
SubscribeEvent() method, you can terminate
the subscription by calling the UnsubscribeEvent() method. Simply provide the
ID of the event that you want to unsubscribe from as well as the unique ID of
the subscriber that you used in the original subscription call.
ERR_Okay | The termination of service was successful. |
ERR_Args | Invalid arguments were specified. |
ERR_AccessMemory | Internal access to a memory block was denied. |
|
|
FileCreated |
Indicates that a new file has been created. |
APTR Buffer | This string will reflect the location of the File that was created. |
LONG Size | This argument reflects the byte size of the string. |
|
This event is managed by the FileSystem module. It is called whenever
a new file, directory or assignment has been created with the File class.
If the Pandora Engine is running on a hosted system, this event will not
detect files that are created by foreign programs.
If the created file is a directory, this will be indicated with a trailing
slash at the end of the location string. If the file is an assignment, this
will be indicated with a colon at the end of the location string. In all
other cases, the location will indicate a normal file.
|
|
FileDeleted |
Indicates that an existing file has been destroyed. |
APTR Buffer | This string will reflect the location of the File that was deleted. |
LONG Size | This argument reflects the byte size of the string. |
|
This event is managed by the FileSystem module. It is called whenever a
new file, directory or assignment has been deleted. If the Pandora Engine is
running on a hosted system, this event will not detect files that are deleted
by foreign programs.
If the deleted file is a directory, this will be indicated with a trailing
slash at the end of the location string. If the file is an assignment, this
will be indicated with a colon at the end of the location string. In all
other cases, the location will indicate a normal file.
|
|
NewTask |
Indicates that a new Task has been activated. |
OBJECTID ObjectID | Refers to the ID of the Task that has been created. |
|
The NewTask event is signalled when a new Task is activated in the
system.
|
|
TaskCrashed |
Indicates that a Task has crashed or self-destructed. |
OBJECTID ObjectID | Refers to the ID of the Task that has crashed. |
|
If a Task has crashed, this event will be called to indicate that a Task
has been removed from the system by force. This event is useful for modules
and classes that need to clean-up after Tasks that have been removed in a way
that does not follow normal protocols.
|
|