BControllable

Constructor

BControllable()

protected:

	BControllable()

　BControllableのコンストラクタです。あなたの派生クラスがBParameterWebオブジェクトを生成し、利用可能なparameterをそのオブジェクトが記述するように設定し、そして返る前にそのオブジェクトをもってBControllable::SetParameterWeb()を呼び出すように、これをオーバーライドして下さい。

Member Functions

ApplyParameterData() see MakeParameterData()

BroadcastChangedParameter()

protected:

	status_t BroadcastChangedParameter(int32 parameterID)

　特定のparameterの設定が変更される際に、変更されたparameterのIDでこの関数を呼び出して下さい。そうすることでクライアントは、parameterの新しい設定を認識するnodeをチェックする必要があると知ることになります。

parameterの設定は、parameterの取りうる値の範囲が変更になった時のみ変更になります。例えば、もしparameterの値がCDのトラック数であれば、ユーザがトラック数の違う別のCDを挿入した場合に変更になるでしょう（このようにBroadcastChangedParameter()の呼び出しが要求されます）。

RETURN CODES

B_OK. エラーなし。

• BMessenger::SendMessage()エラー。

BroadcastNewParameterValue()

protected:

	status_t BroadcastNewParameterValue(bigtime_t when,       int32 id, void *newValue, size_t valueSize)

　parameterの値の変更が有効になり、変更について知ることに興味のある人々を同期させたままにしたい時は、この関数を呼び出して下さい。BroadcastChangedParameter()と異なり、この関数は実際にparameterの新しい値を伝えます。

　引数whenは、変更が有効になったperformance timeを示します。idは、値が変更になったparameterのparameter IDを示します。newValueは、parameterのデータへのポインタであり、valueSizeはデータの大きさを定義します。

RETURN CODES

B_OK. エラーなし。

• その他のエラー. Media Serverまたはroster内のnodeと交信中にエラーが生じた。

GetParameterValue() , SetParameterValue()

protected:

	virtual status_t GetParameterValue(int32 parameterID, bigtime_t *lastChangeTime,       void *value, size_t *ioSize) = 0 virtual void SetParameterValue(int32 parameterID, bigtime_t changeTime,       const void *value, size_t size) = 0

　あなたは、valueポインタによって示されるメモリの中で、指定されたparameterIDのparameterの値を保存するようにGetParameterValue()を実装しなければなりません。ioSizeポインタによって示されるsize_tの値は、値のバッファの大きさを指定します。関数が返るより前に、返されるデータの実際の大きさにioSizeを変更するようGetParameterValue()が実装されます。

　同様に、lastChangeTimeをcontrolの値が変更された最も最近の時間に設定して下さい。

　GetParameterValue()は、処理が終了したらB_OKを返します。或いは、もし何か問題が生じれば、適切なエラーコードを返します。

　同様に、parameterの値を変更するためにSetParameterValue()を実装して下さい。引数changeTimeは、その変更が生じたperformance timeです。言い換えれば、要求された時間に要求が扱われるように、それをキューに入れる必要があります。valueはparameterにセットされる値のポインタを示し、sizeはvalueのデータのバイト数となります。

そのparameterがマルチチャンネルのparameterであれば、ひとつのparameterが値のチャンネルを複数持つ可能性があります。例えば、もしparameterが2チャンネルのスライダー（ひとつのparameter内で左右のチャンネルが独立して制御されるステレオのゲイン制御など）であれば、引数valueは、ふたつのfloatの配列へのポインタを示し、sizeは8（sizeof(float) * 2）となります。

HandleMessage()

	virtual status_t HandleMessage(int32 message, const void *data, size_t size)

　nodeのサービスループがmessageを受け取る際、BMediaNodeや他のあなたのnodeのスーパークラスに渡すのに加えて、それをBControllable::HandleMessage()にも渡して下さい。派生クラスの最外殻（下流）のHandleMessage()の実装から開始し、B_OKが返されるまで基底クラス（上流）の方向に任意の処理を行って下さい。

　もしメッセージがBControllableのインターフェイスに対して企図されたものであれば、それはディスパッチされ、B_OKが返されます。そうでなければ、HandleMessage()はエラーを返します。これによって、あなたは他に何か試す必要があるということを知ります。

   /* Message received */
   
   if ((BControllable::HandleMessage(message, data, size) != B_OK) &&
            (BMediaNode::HandleMessage(message, data, size) != B_OK)) {
      BMediaNode::HandleBadMessage(message, data, size);
   }

　この例では、BControllableのHandleMessage()実装がそのメッセージを扱う最初の機会を得ます。もしその実装がメッセージの扱い方を知らなければ、そのメッセージはBMediaNodeの実装に転送されます。もしメッセージがまだ扱われていなければ、その後にデフォルトのBMediaNode::HandleBadMessage()に送られます。

RETURN CODES

B_OK. メッセージはディスパッチされた。

• 適切な、その他のエラー. 各々のmessageコードは、種々のエラーコードで応答する。

　こちらもご覧下さい: BMediaNode::HandleMessage(),  "About Multiple Virtual Inheritance" 21ページ目

LockParameterWeb() , UnlockParameterWeb()

	bool LockParameterWeb(void) void UnlockParameterWeb(void)

　LockParameterWeb()は、あなたがweb上で作業している間、webへのアクセスを妨げるためにそれをロックします。またUnlockParameterWeb()は、作業が終了する際にそれを解放します。あなたは、webへのアクセスをこれらの呼び出しで囲まなければなりません。

   LockParameterWeb();
   Web()->MakeGroup("EqualizerControls");
   ...
   UnlockParameterWeb();

MakeParameterData() , ApplyParameterData()

protected:

	status_t MakeParameterData(const int32 *parameterList, int32 numParameters,       void *buffer, size_t *ioSize) status_t ApplyParameterData(const void *value, size_t size)

　MakeParameterData()ユーティリティ関数は、parameterListにparameter IDのリストを取り、ioSizeで指定されたサイズが満たされるまで指定されたbufferに値を保存するように、それぞれのparameterに対してGetParameterValue()を呼び出します。使用されたバッファのバイト数は、ioSizeに返されます。

　もしあなたのBControllableが、入力からB_MEDIA_PARAMETERSタイプのデータを受け入れるBBufferConsumerでもあれば、valueにBBuffer::Data()の結果を、sizeにBBuffer::Size()の結果をセットしてApplyParameterData()を呼び出して下さい。この関数は、バッファのparameter変更要求を解析し、要求を実行する目的でSetParameterValue()関数を呼び出すために、それらをディスパッチします。

　これによって、あなたのnodeはparameter情報の自動化を簡単にサポートできます。しかしそれ以上に、BBufferProducerから派生することによっても、またB_MEDIA_PARAMETERSデータフォーマットの出力を供給することでも利益が得られ、それ故に、変更はそれが生じた様に記録されうるのです。これは、それらへのユーザの変更を記録し、その後その変更を再現することによって、parameterの自動化機構を供給します。

RETURN CODES

B_OK. エラーなし。

• B_NO_MEMORY. 出力bufferは小さすぎる。

SetParameterValue() see GetParameterValue()

SetParameterWeb() , Web()

protected:

	status_t SetParameterWeb(BParameterWeb *web) BParameterWeb *Web(void)

　コンストラクタはBParameterWebオブジェクトを生成し、それを引数としてSetParameterWeb()を呼び出します。これは、どのparameterが使用でき、それらがお互いにどう関連しているのかという外部の世界を記述します。言葉を換えれば、これは内部のシグナル経路と、それがどうやって操作されるかを記述します。

　もし引数のwebがNULLでなく、以前にBControllableのnodeに対して確立されたwebとは異っていた場合、B_MEDIA_WEB_CHANGEDメッセージがメディア通知を監視している全てのものに送られます。詳細は、StartWatching()をご覧下さい。

　SetParameterWeb()は、もしwebがエラーなしに設定されればB_OKを返すでしょう。そうでなければ、エラーコードが返されるでしょう。

　Web()関数は、BControllableに割り当てられたBParameterWebを返します。

StartControlPanel()

protected:

	virtual status_t StartControlPanel(BMessenger *outMessenger)

　このフック関数は、クライアントアプリケーションがnodeに対して（ユーザがnodeを設定できるように）nodeの制御パネルのユーザインターフェイスを公開させたい場合に呼び出されます。

　この関数が返る際には、outMessengerが制御パネルと対話するために使用できるBMessengerとなります。

　add-onがMedia Serverの内部で動作し、ユーザインターフェイスの問題がシステム全体に及ぶ可能性があるため、制御パネルは自分自身のteamとして動作することが推奨されます。これは、nodeを（make_media_addon()をexportすることによって）Media Server add-onと（main()を実装し、リンクライブラリにstart_dyn.oを含むことによって）アプリケーションの両方で書くことにより、簡単に実現できます。必ずmulti-launch applicationフラグをあなたのadd-onにセットして下さい。さもないと、これは正しく動作しないでしょう。

　その後、StartControlPanel()の実装は、単純にadd-onをアプリケーションとして起動できます。そしてもしユーザがadd-onをダブルクリックすれば、add-onは制御パネルを公開するでしょう。加えて、ユーザはadd-onを適切に動作させるために、ひとつのファイルをインストールするだけですむという利益を得ます。

　main()関数への最初のargv引数は、node IDが"%d"に該当する"node=%d"のフォーマットの文字列です。

（アプリケーションとしてadd-onを起動することによってあなたの制御パネルから供給される）上記の実装からは、StartControlPanel()のデフォルトの振る舞いが示唆されます。したがって、もしそれがBControllableを実装する方法であれば、あなたはStartControlPanel()をオーバーライドする必要が全くありません。このケースでは、返されたBMessengerは制御パネルアプリケーションに対するものであり、それが内包される特定のBWindowやBViewではありません。

RETURN CODES

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

• B_ERROR. add-onからnodeがロードされなかった。

• B_BAD_VALUE. nodeが読み込まれたimageの位置を確認する際にエラーが生じたか、或いはadd-onがアプリケーションとして起動できなかった。

• B_LAUNCH_FAILED. 制御パネルは、メモリ不足といった他の何らかの理由で起動できなかった。

UnlockParameterWeb() see LockParameterWeb()

Web() see SetParameterWeb()