Class Documentation

Name:Broadcast
Version:1.0
ID:ID_BROADCAST
Status:Beta
Category:System
Include:system/event.h
Date:July 2001
Author:Rocklyte Systems
Copyright:  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:

Broadcast  Broadcasts an event.
SubscribeEvent  Subscribes objects to broadcast events.
UnsubscribeEvent  Unsubscribes objects from broadcast events.

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.
Method:Broadcast()
Short:Broadcasts an event.
Arguments:
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.

Result
ERR_Okay  The event was broadcast successfully.
ERR_AccessMemory  Access to the internal subscription array was denied.

Method:SubscribeEvent()
Short:Subscribes objects to broadcast events.
Arguments:
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.

Result
ERR_Okay  Subscription successful.
ERR_Args  Invalid arguments were specified.
ERR_AllocMemory  Failed to allocate a new subscription array.

Method:UnsubscribeEvent()
Short:Unsubscribes objects from broadcast events.
Arguments:
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.

Result
ERR_Okay  The termination of service was successful.
ERR_Args  Invalid arguments were specified.
ERR_AccessMemory  Internal access to a memory block was denied.

Event:FileCreated
Short:Indicates that a new file has been created.
Arguments:
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.


Event:FileDeleted
Short:Indicates that an existing file has been destroyed.
Arguments:
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.


Event:NewTask
Short:Indicates that a new Task has been activated.
Arguments:
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.


Event:TaskCrashed
Short:Indicates that a Task has crashed or self-destructed.
Arguments:
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.