BMediaEventLooper

Derived from: BMediaNode

Declared in: be/media/MediaEventLooper.h

Library: libmedia.so

Allocation: Constructor only

Summary

　BMediaEventLooperクラスは、受け取ったメディアイベントをキューに入れる制御スレッドを提供し、それらを処理するために実装されたHandleEvent()を必要に応じて呼び出します。これは、nodeを書く際の単純作業をなくします。

• やってきたメッセージを受け取って処理するためのサービススレッドを書く必要がありません。BMediaEventLooperがこれを行います（BLooperと全く同様に。だから名前が似ているのですが）。

• BMediaEventLooperがBTimedEventQueueを維持してくれるため、イベントを扱う時まで、それらをキューに入れるコードを書く必要がありません。

• もしあなたのnodeが、Start()、Stop()及びSeek()要求が来る時間を正確に知る必要があるだけなら、あなたのnodeはこれらの関数をオーバーライドする必要さえありません—BMediaEventLooperは自動的にこれらをインターセプトし、キューにプッシュします。

• BMediaEventLooperに使用されるBTimedEventQueueは、自動的に複数のstart、stop及びseekイベントをキューに入れる処理をサポートします。

Implementing a Node (the Easy Way)

　BMediaEventLooperは、nodeの複雑なコンストラクト処理の多くを取り去りますが、まだしなければならない作業が残っています。あなた自身が実装しなければならないフック関数が、まだたくさんあるのです（厳密には、nodeの種類がproducerかcosumerかによります）。

　"A BMediaEventLooper Example"を読むことで、BMediaEventLooperを使用するnodeをどうやって実装するかについての具体的な例を学ぶことができます。

Hook Functions

• CleanUpEvent()

• ControlLoop()

• HandleEvent()

• OfflineTime()

Constructor and Destructor

BMediaEventLooper()

protected:

	explicit BMediaEventLooper(uint32 apiVersion = B_BEOS_VERSION)

　あなたのnodeの初期化を扱うために、この関数をオーバーライドする必要があります。引数apiVersionは、そのオブジェクトが対応するBeOS APIのバージョンを示します。これにはデフォルトの値を使用して下さい—これにより、あなたのnodeは、自分がコンパイルされるBeOSのAPIバージョンを継承します。

~BMediaEventLooper()

protected:

	virtual ~BMediaEventLooper(void)

　制御スレッドを停止させ、領域確保されたメモリを解放するために、Quit()を呼び出します。

Member Functions

BufferDuration() see SetBufferDuration()

CleanUpEvent()

protected:

	virtual void CleanUpEvent(const media_timed_event *event)

　あなたが生成し、キューに追加したカスタムイベントの後始末をするために、この関数を実装して下さい。この関数は、イベントが必要とするかも知れない特別な後処理をあなたが扱えるように、カスタムイベントがキューから削除される時に呼び出されます。

ControlLoop()

protected:

	virtual void ControlLoop(void)

　この関数は、メッセージを待ち、イベントをキューからポップし、そしてDispatchEvent()を呼び出します。この関数は、BMediaEventLooperがRun()される際に自動的に呼び出されます。

もしこの関数を再実装することを選ぶなら、非常に注意して下さい。それは非常に簡単に「悪いこと」を起こす原因となります。

ControlThread()

	thread_id ControlThread(void)

　制御スレッドのthread_idを返します。

DispatchEvent()

protected:

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

　指定されたeventをあなたのnodeが扱えるように、HandleEvent()を呼び出します。もしあなたのcodeがそれを扱わないなら、この関数はそれを処理するためのデフォルトハンドラを持つでしょう。一般的に、あなたがこの関数を呼び出すことはありません。

　キューからイベントを削除するのは、制御ループの作業です。この関数は、それを行いません。

EventLatency() see SetEventLatency()

EventQueue() , RealTimeQueue()

protected:

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

　EventQueue()は、メッセージハンドラに使用されるBTimedEventQueueへのポインタを返します。RealTimeQueue()は、リアルタイムイベントに使用されるBTimedEventQueueへのポインタを返します。

HandleEvent()

protected:

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

　入ってきたメディアイベントを扱うために、この関数を実装して下さい。引数eventは、イベントを記述するmedia_timed_event構造体を参照します。latenessは、そのイベントがどれくらい遅れるかを示し、もしイベントがreal timeで扱われる必要があれば、realTimeEventはtrueです。

　BMediaEventLooperは、DispatchEvent()関数からこの関数を呼び出します。キューからイベントを削除するのは、制御ループの作業です。

OfflineTime() see SetOfflineTime()

NodeRegistered()

protected:

	virtual void NodeRegistered(void)

　nodeが登録された後、Media Serverはこのフック関数を呼び出します。この関数はBMediaNodeから派生しています。BMediaNodeLooperは、nodeが登録された際に自動的にRun()を呼び出すよう、この関数を実装します。もしあなたがNodeRegistered()を実装するなら、あなたがカスタムの処理を行った後に、BMediaEventLooper::NodeRegistered()を呼び出して下さい。

Priority() see SetPriority()

Quit()

	void Quit(void)

　nodeの制御ポート及び制御スレッドを閉じます。制御スレッドが破棄されるまでブロックします。

Run()

	void Run(void)

　制御スレッドを生成し、動作させます。これはデフォルトのNodeRegistered()実装によって自動的に呼び出されます。もしNodeRegistered()をオーバーライドするなら、その中で必ずデフォルトの実装を呼び出すか、またはRun()を呼び出して下さい。

RunState() see SetRunState()

SchedulingLatency()

protected:

	bigtime_t SchedulingLatency(void) const

　nodeのscheduling latencyを、マイクロ秒単位で返します。

SetBufferDuration() , BufferDuration()

protected:

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

　SetBufferDuration()は、nodeのバッファの時間的な長さ（duration）を設定します。durationは、もしその値が0未満なら強制的に0になります。

　BufferDuration()は、nodeのバッファの時間的な長さ（duration）を返します。

SetEventLatency() , EventLatency()

protected:

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

　SetEventLatency()は、イベントのlatencyを設定します。イベントのlatencyは、内部的なlatencyと下流のlatencyの両方を含む、あなたのnodeのlatencyを合計したものです。このlatencyは、あなたが処理するためキューからイベントをポップする時間を決定する際に、BMediaEventLooperによって計算に取り込まれます。

　EventLatency()は、イベントのlatencyを返します。

SetOfflineTime() , OfflineTime()

protected:

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

　SetOfflineTime()は、OfflineTime()が返される時間を設定します。

　nodeの現在の時間を計算するために、OfflineTime()を増やします。この関数はオフラインモードの時にMedia Kitによって呼び出されます。全ての適切な内部情報を更新した上で、BMediaEventLooperの実装を呼び出して下さい。

SetPriority() , Priority()

protected:

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

　SetPriority()は、制御スレッドの優先度（priority）を返します。0未満の値は強制的に0にされ、120を越える値は強制的に120にされます。

　Priority()は、制御スレッドの現在の優先度（priority）を返します。

SetRunState() , RunState()

protected:

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

　SetRunState()は、nodeの現在の実行モードを設定します。

　RunState()は、現在の実行状況（run state）を返します。

　こちらもご覧下さい: run_state

Constants

run_state

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

Constant	Description
B_IN_DISTRESS	nodeは、問題を経験している。
B_UNREGISTERED	nodeは、まだMedia roterに登録されていない。
B_STOPPED	nodeは、動作していない。
B_STARTED	nodeは動作している。
B_QUITTING	nodeは、終了処理中である。
B_TERMINATED	nodeは、終了させられた。
B_USER_RUN_STATES	ユーザ定義の実行状況（run status）に基づく。