The Media Kit: BTimedEventQueue

The Media Kit Table of Contents | The Media Kit Index

# BTimedEventQueue

Derived from: (none)

Declared in: be/media/TimedEventQueue.h

Library: libmedia.so

Allocation: Constructor only

###### Summary

The BTimedEventQueue class provides an easy way to queue a sequence of events within your node. You can use it to queue up start, stop, and seek requests, and to queue up incoming data buffers in preparation for handling them. Each queue element is tagged with the time at which the event should be processed, and functions are provided for locating the next event that should be handled.

Although you shouldn't need to subclass BTimedEventQueue, there's no reason you can't do it.

## Cleaning Up After Nodes

Each event has a cleanup flag associated with it that indicates what sort of special action needs to be performed when the event is removed from the queue. If this value is `B_NO_CLEANUP`, nothing is done. If it's `B_RECYCLE`, and the event is a `B_HANDLE_BUFFER` event, BTimedEventQueue will automatically recycle the buffer associated with the event.

If the cleanup flag is `B_DELETE` or is `B_USER_CLEANUP` or greater, the cleanup hook function will be called. You can implement and establish a cleanup hook function to handle deleting event data yourself. The hook function is of type `cleanup_hook`:

       typedef void (*cleanup_hook)(void *context, bigtime_t time, int32 what,
                void *pointer, uint32 pointerCleanup, int64 data);

You specify the cleanup hook function by calling `SetCleanupHook()`, like this:

       SetCleanupHook(MyCleanupFunction, contextPtr);

The contextPtr

is a pointer that your cleanup hook function uses, and can contain whatever data you require.

## Constructor and Destructor

### BTimedEventQueue()

`BTimedEventQueue() `

Initializes a new, empty, timed event queue.

### ~BTimedEventQueue()

`virtual ~BTimedEventQueue() `

Flushes the queue and deallocates memory allocated by the object.

## Member Functions

### AddEvent()

status_t `AddEvent(`const media_timed_event &event`) `

Adds the specified event to the queue.

RETURN CODES

`B_OK`. The event was added.

- `B_BAD_VALUE`. Unknown or invalid event type (you can't use `B_NO_EVENT` or `B_ANY_EVENT`).

- `B_NO_INIT`. The queue hasn't been initialized.

### DoForEach()

status_t `DoForEach(`for_each_hook hook, void *context,
bigtime_t time,
time_direction direction,
bool inclusive = true,
int32 event = B_ANY_EVENT`)

`

For each event in the queue matching the specified parameters, the hook function is called. The context pointer is passed through to the hook function, and may point to anything your hook function requires.

- Setting direction to `B_ALWAYS` indicates that all events of the type indicated by event should be processed. The time and includive arguments are ignored.

- Setting direction to `B_BEFORE_TIME` indicates that all matching events occurring before the specified time should be processed. If inclusive is `true`, events occurring at time are also processed.

- Setting direction to `B_AT_TIME` processes all matching events scheduled at the specified time. The inclusive argument is ignored.

- If direction is `B_AFTER_TIME`, all matching events scheduled to occur after the specified time are processed. If inclusive is `true`, events scheduled to occur at time are also processed.

This provides a means for you to scan through the queue and perform a particular act on every node (or all nodes of a certain type, or that occur at certain times). If you want to process all events, you can specify a time of `B_INFINITE_TIMEOUT` and a direction of `B_BEFORE_TIME`.

The hook function should return a queue_action value.

       queue_action MyHook(media_timed_event *event, void *context) {
          if (event->data == 0) {
             /* countdown finished, do something */
             return BTimedEventQueue::B_REMOVE_EVENT;
          }
          event->data--;
          return BTimedEventQueue::B_NO_ACTION;
       }

In this example, the hook function processes the event (and indicates on return that it should be removed from the queue) if the `data` field of the event structure is zero; otherwise `data` is decremented and the event is left alone.

RETURN CODES

`B_OK`. The events were processed.

- `B_ERROR`. An undefined error occurred.

### EventCount()

int32 `EventCount(`void`)` const` `

Returns the number of events in the queue.

### FindFirstMatch()

const media_timed_event *`FindFirstMatch(`bigtime_t eventTime, time_direction direction, bool inclusive = true, int32 eventType = B_ANY_EVENT`) `

Searches the event queue for the first event matching the given specifications. The search begins at the time specified by eventTime, and progresses in the specified direction.

- Setting direction to `B_ALWAYS` indicates that all events of the type indicated by event should be scanned. The eventTime and includive arguments are ignored.

- Setting direction to `B_BEFORE_TIME` indicates that all matching events occurring before the specified eventTime should be scanned. If inclusive is `true`, events occurring at eventTime are also scanned.

- Setting direction to `B_AT_TIME` scans all matching events scheduled at the specified eventTime. The inclusive argument is ignored.

- If direction is `B_AFTER_TIME`, all matching events scheduled to occur after the specified eventTime are scanned. If inclusive is `true`, events scheduled to occur at eventTime are also scanned.

If you want to scan all events, you can specify a time of `B_INFINITE_TIMEOUT` and a direction of `B_BEFORE_TIME`.

If no matching event is found, `NULL` is returned.

### FirstEvent() , FirstEventTime()

const media_timed_event *`FirstEvent(`void`)` const
bigtime_t `FirstEventTime(`void`)` const

`FirstEvent()` returns the first event in the queue, without removing it from the queue.

`FirstEventTime()` returns the first event's time, in microseconds.

RETURN CODES

`B_OK`. No error occurred.

- `B_NO_INIT`. The queue hasn't been initialized.

- `B_INFINITE_TIMEOUT`. The queue is empty (`FirstEventTime()` only).

### FlushEvents()

status_t `FlushEvents(`bigtime_t time, time_direction direction, bool inclusive = true, int32 event = B_ANY_EVENT`) `

Flushes the specified events from the queue. You specify which events to flush by indicating a time from which events should be flushed, a direction in which to search for events to flush, and the type of events to flush:

- Setting direction to `B_ALWAYS` indicates that all events of the type indicated by event should be flushed. The time and includive arguments are ignored.

- Setting direction to `B_BEFORE_TIME` indicates that all matching events occurring before the specified time should be flushed. If inclusive is `true`, events occurring at time are also flushed.

- Setting direction to `B_AT_TIME` flushes all matching events scheduled at the specified time. The inclusive argument is ignored.

- If direction is `B_AFTER_TIME`, all matching events scheduled to occur after the specified time are flushed. If inclusive is `true`, events scheduled to occur at time are also flushed.

If you want to flush all events, you can specify a time of `B_INFINITE_TIMEOUT` and a direction of `B_BEFORE_TIME`.

RETURN CODES

`B_OK`. The events were flushed.

- `B_ERROR`. An undefined error occurred.

### HasEvents()

bool `HasEvents(`void`) `

Returns `true` if there are events in the queue, otherwise returns `false`.

### LastEvent() , LastEventTime()

const media_timed_event *`LastEvent(`void`)` const
bigtime_t `LastEventTime(`void`)` const

`LastEvent()` returns the last event in the queue, without removing it from the queue.

`LastEventTime()` returns the last event's time, in microseconds.

RETURN CODES

`B_OK`. No error occurred.

- `B_NO_INIT`. The queue hasn't been initialized.

- `B_INFINITE_TIMEOUT`. The queue is empty (`LastEventTime()` only).

### RemoveEvent() , RemoveFirstEvent()

status_t `RemoveEvent(`const media_timed_event *event`) `
status_t `RemoveFirstEvent(`const media_timed_event *outEvent = NULL`) `

`RemoveEvent()` removes the specified event from the queue.

`RemoveFirstEvent()` removes the first event from the queue. If outEvent isn't `NULL`, the specified buffer is filled with a copy of the event that's been removed.

RETURN CODES

`B_OK`. The event was removed.

- `B_NO_INIT`. The queue hasn't been initialized.

### SetCleanupHook()

void `SetCleanupHook(`cleanup_hook hook, void *context`) `

Sets up the cleanup hook function specified by hook to be called for events as they're removed from the queue. The hook will be called only for events with `cleanup_flag` values of `B_DELETE` or `B_USER_CLEANUP` or greater.

## Constants

### cleanup_flag

Declared in: <be/media/TimedEventQueue.h>

Constant | Description
--- | ---
`B_NO_CLEANUP` | Don't clean up when the event is removed from the queue.
`B_RECYCLE_BUFFER` | BTimedEventQueue should recycle the buffer when the buffer event is removed from the queue.
`B_EXPIRE_TIMER` | Call `TimerExpired()` on the event's `data` field.
`B_USER_CLEANUP` | Base value for user-defined cleanup types.

These values define how BTimedEventQueue should handle removing events from the queue. If the flag is `B_USER_CLEANUP` or greater, the cleanup hook function is called when the event is removed.

### event_type

Declared in: <be/media/TimedEventQueue.h>

Constant | Description
--- | ---
`B_NO_EVENT` | Don't push buffers of this type. It's a return value only.
`B_ANY_EVENT` | Don't push buffers of this type; it's used in searches only.
`B_START` | A start event.
`B_STOP` | A stop event.
`B_SEEK` | A seek event.
`B_WARP` | A warp event.
`B_TIMER` | A timer event.
`B_HANDLE_BUFFER` | Represents a buffer queued to be handled. The event's `pointer` is a pointer to a BBuffer object.
`B_DATA_STATUS` | Represents a data status event.
`B_HARDWARE` | A hardware event.
`B_PARAMETER` | The buffer contains changes to parameter values; pass it to `BControllable::ApplyParameterData()`.
`B_USER_EVENT` | Base value for user-defined events.

These values describe type types of events that a BTimedEventQueue can handle.

### queue_action

Declared in: <be/media/TimedEventQueue.h>

Constant | Description
--- | ---
`B_DONE` | End the `DoForEach()` pass.
`B_NO_ACTION` | Do nothing for this event.
`B_REMOVE_EVENT` | Remove the event.
`B_RESORT_QUEUE` | Sort the queue again to ensure that events are still in the right order.

These queue action values are returned by the hook function used by `DoForEach()`; these values indicate what `DoForEach()` should do to the event after the hook has processed it.

### time_direction

Declared in: <be/media/TimedEventQueue.h>

Constant | Description
--- | ---
`B_ALWAYS` | Matches events occurring at any time.
`B_BEFORE_TIME` | Matches events occurring before a specified time.
`B_AT_TIME` | Matches events occurring at a specified time.
`B_AFTER_TIME` | Matches events occurring after a specified time.

These values are used to indicate a search direction through the time continuum.

## Defined Types

### cleanup_hook

Declared in: <be/media/TimedEventQueue.h>

       typedef queue_action (*cleanup_hook)(media_timed_event *event, void *context);

The cleanup_hook type is used to define a hook function called while removing an event from the queue; it's set by calling `SetCleanupHook()`.

### for_each_hook

Declared in: <be/media/TimedEventQueue.h>

       typedef queue_action (*for_each_hook)(media_timed_event *event, void *context);

The for_each_hook type is used to define a hook function called by `DoForEach()`.

### media_timed_event

Declared in: <be/media/TimedEventQueue.h>

       struct media_timed_event {
          media_timed_event();
          media_timed_event(bigtime_t inTime, int32 inType);
          media_timed_event(bigtime_t inTime, int32 inType, void *inPointer,
                   uint32 inCleanup);
          media_timed_event(bigtime_t inTime, int32 inType,
                   void *inPointer, uint32 inCleanup,
                   int32 inData, int64 inBigdata,
                   char *inUserData, size_t dataSize = 0);

          media_timed_event(const media_timed_event &clone);
          void operator=(const media_timed_event &clone);

          ~media_timed_event();

          bigtime_t event_time;
          int32 type;
          void *pointer;
          uint32 cleanup;
          int32 data;
          int64 bigdata;
          char user_data[64];
          uint32 _reserved_media_timed_event_[8];
       };

Describes a media event:

- `event_time` indicates the time at which the event is scheduled to occur.

- `type` indicates the type of event, as an event_type.

- `pointer` is a pointer to event-specific data owned by the event.

- `cleanup` is the cleanup_flag value for the event.

- `data` is an event-specific 32-bit value.

- `bigdata` is an event-specific 64-bit value.

- `user_data` is user-defined data.

The Media Kit Table of Contents | The Media Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..