The Media Kit: BMediaEventLooper

The Media Kit Table of Contents | The Media Kit Index

# BMediaEventLooper

Derived from: BMediaNode

Declared in: be/media/MediaEventLooper.h

Library: libmedia.so

Allocation: Constructor only

###### Summary

The BMediaEventLooper class provides a control thread that automatically queues received media events and calls the `HandleEvent()` function you implement to process them as necessary. This takes a lot of the drudgery out of writing nodes:

- You don't have to write a service thread to receive and process incoming messages; BMediaEventLooper does this for you (much like a BLooper, hence the similarity in names).

- You don't have to write code to queue up events until it's time to handle them, since BMediaEventLooper maintains a BTimedEventQueue for you. Just push events onto the queue as you receive them and the BMediaEventLooper pops them off for you at the appropriate times and asks you to handle them.

- If all your node needs to do is know when `Start()`, `Stop()`, and `Seek()` requests come due, your node doesn't even have to override these functions—BMediaEventLooper automatically intercepts them and pushes them onto the queue for you.

- The BTimedEventQueue employed by BMediaEventLooper automatically provides support for queueing multiple start, stop, and seek events.

  ## Implementing a Node (the Easy Way)

  Although BMediaEventLooper does take away a lot of the complicated node construction work, there's still work to be done. There are still plenty of hooks you have to implement yourself (which ones, exactly, depend on whether you're a producer or a consumer).

  You can study a specific example of how to implement a node using BMediaEventLooper by reading "A BMediaEventLooper Example".

  ## Hook Functions

  - `CleanUpEvent()

    `
  - `ControlLoop()

    `
  - `HandleEvent()

    `
  - `OfflineTime()

    `

  ## Constructor and Destructor

  ### BMediaEventLooper()

  protected:

  explicit `BMediaEventLooper(`uint32 apiVersion = `B_BEOS_VERSION``)`

  You need to override this function to handle your node's initialization needs. The apiVersion argument indicates the version of the BeOS API the object was written for; you should let the default value be used—this will cause your node to inherit the API version of the BeOS version you're compiling under.

  ### ~BMediaEventLooper()

  protected:

  virtual `~BMediaEventLooper(`void`)`

  Calls `Quit()` to stop the control thread and free allocated memory.

  ## Member Functions

  ### BufferDuration() see SetBufferDuration()

  ### CleanUpEvent()

  protected:

  virtual void `CleanUpEvent(`const media_timed_event *event`) `

  Implement this function to clean up after custom events you've created and added to your queue. It's called when a custom event is removed from the queue, to let you handle any special tidying-up that the event might require.

  ### ControlLoop()

  protected:

  virtual void `ControlLoop(`void`) `

  This function waits for messages, pops events off the queue, and calls `DispatchEvent()`. It's called automatically when the BMediaEventLooper is `Run()`.

  | If you choose to reimplement this function, be very careful; it's very easy to cause Bad Things to happen.

  ### ControlThread()

  thread_id `ControlThread(`void`) `

  Returns the control thread's thread_id.

  ### DispatchEvent()

  protected:

  void `DispatchEvent(`const media_timed_event *event, bigtime_t lateness, bool realTimeEvent = false`) `

  Calls `HandleEvent()` to let your code handle the specified event. If your code doesn't handle it, this function may have a default handler to process it. In general, you won't call this function.

  It's the control loop's job to remove the event from the queue; this function doesn't do that.

  ### EventLatency() see SetEventLatency()

  ### EventQueue() , RealTimeQueue()

  protected:

  BTimedEventQueue *`EventQueue(`void`) `
  BTimedEventQueue *`RealTimeQueue(`void`) `

  `EventQueue()` returns a pointer to the BTimedEventQueue used by the message handler. `RealTimeQueue()` returns a pointer to the BTimedEventQueue used to queue real-time events.

  ### HandleEvent()

  protected:

  virtual void `HandleEvent(`const media_timed_event *event, bigtime_t lateness, bool realTimeEvent = false`) `

  Implement this function to handle incoming media events. The event argument references a media_timed_event structure that describes the event. lateness indicates how late the event is, and realTimeEvent is true if the event needs to be handled in real time.

  The BMediaEventLooper will call this function from the `DispatchEvent()` function. It's the control loop's job to remove the event from the queue.

  ### OfflineTime() see SetOfflineTime()

  ### NodeRegistered()

  protected:

  virtual void `NodeRegistered(`void`) `

  The Media Server calls this hook function after the node has been registered. This is derived from BMediaNode; BMediaEventLooper implements it to call `Run()` automatically when the node is registered; if you implement `NodeRegistered()` you should call through to `BMediaEventLooper::NodeRegistered()` after you've done your custom operations.

  ### Priority() see SetPriority()

  ### Quit()

  void `Quit(`void`) `

  Closes the node's control port and closes the control thread. Blocks until the control thread is gone.

  ### Run()

  void `Run(`void`) `

  Spawns and runs the control thread; this is called automatically by the default `NodeRegistered()` implementation. If you override `NodeRegistered()`, be sure you call through to the default implementation, or call `Run()`.

  ### RunState() see SetRunState()

  ### SchedulingLatency()

  protected:

  bigtime_t `SchedulingLatency(`void`)` const

  Returns the scheduling latnecy, in microseconds, of the node.

  ### SetBufferDuration() , BufferDuration()

  protected:

  void `SetBufferDuration(`bigtime_t duration`) `
  bigtime_t `BufferDuration(`void`)` const

  `SetBufferDuration()` sets the duration of the node's buffers. The duration is clamped to 0 if it's less than 0.

  `BufferDuration()` returns the duration of the nodes' buffers.

  ### SetEventLatency() , EventLatency()

  protected:

  void `SetEventLatency(`bigtime_t latency`) `
  bigtime_t `EventLatency(`void`)` const

  `SetEventLatency()` sets the event latency. The event latency is the total latency of your node, including both your internal latency and the downstream latency. This latency is taken into account by the BMediaEventLooper when deciding when to pop events off the queue for you to process.

  `EventLatency()` returns the event latency.

  ### SetOfflineTime() , OfflineTime()

  protected:

  void `SetOfflineTime(`bigtime_t offlineTime`) `
  virtual bigtime_t `OfflineTime(`void`) `

  `SetOfflineTime()` sets the time that `OfflineTime()` will return.

  Augment `OfflineTime()` to compute the node's current time; it's called by the Media Kit when it's in offline mode. Update any appropriate internal information as well, then call through to the BMediaEventLooper implementation.

  ### SetPriority() , Priority()

  protected:

  void `SetPriority(`int32 priority`) `
  int32 `Priority(`void`)` const

  `SetPriority()` sets the control thread's priority. Values less than 0 are clamped to 0, and values greater than 120 are clamped to 120.

  `Priority()` returns the control thread's current priority.

  ### SetRunState() , RunState()

  protected:

  void `SetRunState(`run_state state`) `
  run_state `RunState(`void`)` const

  `SetRunState()` sets the node's current run state.

  `RunState()` returns the current run state.

  See also: `run_state`

  ## Constants

  ### run_state

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

  Constant | Description
  --- | ---
  `B_IN_DISTRESS` | The node is experiencing problems.
  `B_UNREGISTERED` | The node hasn't been registered with the Media roster yet.
  `B_STOPPED` | The node isn't running.
  `B_STARTED` | The node is running.
  `B_QUITTING` | The node's in the process of shutting down.
  `B_TERMINATED` | The node has been terminated.
  `B_USER_RUN_STATES` | Base for user-defined run states.

  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..