BTimedEventQueue

Derived from: (none)

Library: libmedia.so

Allocation: Constructor only

Summary

　BTimedEventQueueクラスは、node内での一連のイベントをキューに入れる簡単な方法を提供します。あなたは、開始、停止及びseek要求を並べるために、また入ってきたデータのバッファを扱うために用意している間、それらを並べるためにこのクラスを使用することができます。それぞれのキューの要素はイベントが処理されるべき時間によってタグ付けされており、関数は扱われるべき次のイベントを探すために提供されます。

BTimedEventQueueのサブクラスを使用する必要はありませんが、それができない理由はありません。

Cleaning Up After Nodes

　それぞれのイベントは、イベントがキューから削除される際に、どんな特別な動作が行われる必要があるかを示す（自分自身に関連する）クリーンアップフラグを持ちます。もしこの値がB_NO_CLEANUPであれば、なにも行われません。もし値がB_RECYCLEであり、イベントがB_HANDLE_BUFFERイベントであれば、BTimedEventQueueはそのイベントに関連するバッファを自動的にリサイクルするでしょう。

　もしクリーンアップフラグがB_DELETE、B_USER_CLEANUPまたはそれ以上の値であれば、クリーンアップフック関数が呼び出されます。あなたはイベントデータの削除を自分自身で扱うために、クリーンアップフック関数を実装し、確立することができます。そのフック関数は、cleanup_hookタイプです。

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

　SetCleanupHook()を呼び出すことによって、下記のようにクリーンアップフック関数を指定できます。

   SetCleanupHook(MyCleanupFunction, contextPtr);

　contextPtrは、あなたがクリーンアップフック関数を使用するポインタであり、それは種類を問わずあなたが要求するデータを内包することができます。

Constructor and Destructor

BTimedEventQueue()

BTimedEventQueue()

　新しくて中身が空の、時刻設定のあるイベントキュー（timed event queue）を初期化します。

~BTimedEventQueue()

virtual ~BTimedEventQueue()

　キューを消去し、そのオブジェクトによって領域確保されていたメモリを解放します。

Member Functions

AddEvent()

status_t AddEvent(const media_timed_event &event)

　キューに、指定されたeventを追加します。

RETURN CODES

B_OK. イベントが追加された。

B_BAD_VALUE. 未知の、或いは無効なイベントタイプ（B_NO_EVENTまたはB_ANY_EVENTは使用できない）。
B_NO_INIT. キューは初期化されていない。

DoForEach()

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

　キューにある指定したparameterに一致する各々のイベントに対して、hook関数が呼び出されます。contextポインタはフック関数に渡され、あなたのフック関数が要求するなにかを指し示すことになるでしょう。

directionにB_ALWAYSをセットすることにより、eventによって指定されるタイプの全てのイベントが処理されるべきだということを示します。
directionにB_BEFORE_TIMEをセットすることにより、指定されたtimeより以前に生じた全てのイベントが処理されるべきだということを示します。もしinclusiveがtrueであれば、timeに生じたイベントも処理されます。
directionにB_AT_TIMEをセットすることにより、指定されたtimeに生じる予定の全てのイベントを処理します。引数inclusiveは無視されます。
もしdirectionがB_AFTER_TIMEであれば、指定されたtimeより後に生じるよう予定されている全てのイベントが処理されます。もしinclusiveがtrueであれば、timeに生じる予定のイベントも処理されます。

　これによって、それぞれのnode（または、あるタイプの或いはある時間に起こった全てのnode）に於てキューをスキャンし、特定の動作を行うことの意味が提供されます。もし全てのイベントを処理したいなら、時間をB_INFINITE_TIMEOUTに指定し、directionを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;
   }

　この例では、もしイベント構造体のdataがゼロであれば、フック関数はイベントを処理します（そして戻る際にキューから削除されるできであることを示します）。

RETURN CODES

B_OK. イベントは処理された。

B_ERROR. 定義されていないエラーが生じた。

EventCount()

int32 EventCount(void) const

　キューにあるイベント数を返します。

FindFirstMatch()

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

　与えられた特徴に一致する最初のイベントを、それぞれのキューから探します。この探索は、eventTimeで指定された時間から始まり、指定されたdirectionに進行します。

directionにB_ALWAYSをセットすると、eventで指定されるタイプの全てのイベントがスキャンされます。eventTime及びinclusive引数は無視されます。
directionにB_BEFORE_TIMEをセットすると、指定されたeventTimeより前に生じる全てのイベントがスキャンされます。もしinclusive がtrueなら、eventTimeに生じるイベントもスキャンされます。
directionにB_AT_TIMEをセットすると、eventTimeに生じる全てのイベントがスキャンされます。inclusive引数は無視されます。
もしdirectionがB_AFTER_TIMEなら、指定されたeventTimeより後に生じるよう予定された全てのイベントがスキャンされます。もしinclusiveがtrueであれば、eventTimeに生じるよう予定されたイベントもスキャンされます。

　もし全てのイベントをスキャンしたいなら、時間にB_INFINITE_TIMEOUTを、directionにB_BEFORE_TIMEを指定することができます。

　もし一致するイベントが見つからなければ、NULLが返されます。

FirstEvent() , FirstEventTime()

const media_timed_event *FirstEvent(void) const

bigtime_t FirstEventTime(void) const

　FirstEvent()は、キューからイベントを削除せずに、キューの最初のイベントを返します。

　FirstEventTime()は、最初のイベントの生じる時間をマイクロ秒で返します。

RETURN CODES

B_OK. エラーは生じなかった。

B_NO_INIT. キューは初期化されていない。
B_INFINITE_TIMEOUT. キューが空である（FirstEventTime()のみ）。

FlushEvents()

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

　キューから指定されたイベントを消去します。イベントが消去されるtime、消去するイベント探すdirection、及び消去されるイベントのタイプを指定することで、どのイベントが消去されるかを指定します。

directionにB_ALWAYSをセットすることで、eventeventによって示されるタイプの全てのイベントが消去されます。time引数は無視されます。
directionにB_BEFORE_TIMEをセットすることで、指定されたtimeより前に生じる全てのイベントが消去されます。もしinclusiveがtrueであれば、timeに生じるイベントも消去されます。
directionにB_AT_TIMEをセットすることで、指定されたtimeに生じる予定の全てのイベントが消去されます。inclusive引数は無視されます。
もしdirectionがB_AFTER_TIMEであれば、指定されたtimeより後に生じる予定の全てのイベントが消去されます。もしinclusiveがtrueであれば、timeに生じる予定のイベントも消去されます。

　もし全てのイベントを消去したいなら、時間にB_INFINITE_TIMEOUTを、そしてdirectionにB_BEFORE_TIMEを指定することができます。

RETURN CODES

B_OK. イベントは消去された。

B_ERROR. 定義されていないエラーが生じた。

HasEvents()

bool HasEvents(void)

　もしキューにイベントがあれば、trueを返します。そうでなければfalseを返します。

LastEvent() , LastEventTime()

const media_timed_event *LastEvent(void) const

bigtime_t LastEventTime(void) const

　LastEvent()は、キューからイベントを削除せずに、キューの最後のイベントを返します。

　LastEventTime()は、最後のイベントの生じる時間をマイクロ秒で返します。

RETURN CODES

B_OK. エラーは生じなかった。

B_NO_INIT. キューは初期化されていない。
B_INFINITE_TIMEOUT. キューは空である（LastEventTime()のみ）。

RemoveEvent() , RemoveFirstEvent()

status_t RemoveEvent(const media_timed_event *event)

status_t RemoveFirstEvent(const media_timed_event *outEvent = NULL)

　RemoveEvent()は、キューから指定されたeventを削除します。

　RemoveFirstEvent()は、キューから最初のイベントを削除します。もしoutEventがNULLでなければ、指定されたバッファには削除されるイベントのコピーが格納されます。

RETURN CODES

B_OK. イベントは削除された。

B_NO_INIT. キューは初期化されていない。

SetCleanupHook()

void SetCleanupHook(cleanup_hook hook, void *context)

　イベントがキューから削除される際に、イベントに対して呼び出されるフックによって指定されるクリーンアップフック関数を設定します。このフックは、B_DELETE、B_USER_CLEANUPまたはそれ以上のcleanup_flagの値の場合のみイベントに対して呼び出されます。