The Media Kit Table of Contents     The Media Kit Index

BMediaRoster

Derived from: BLooper

Declared in: be/media/MediaRoster.h

Library: libmedia.so

Allocation: Constructor only

Summary

 BMediaRosterクラスは、Media Kitを使用するアプリケーションがアクセス可能な機能で成り立っています。

 アプリケーションは、BMediaRosterクラスのインスタンスを一つだけ持つ事ができます。そのインスタンスは静的メンバ関数のBMediaRoster::Roster()呼び出しによってアクセスされ、media rosterを作成してMedia Serverとの接続を確立し、その後rosterへのポインタを返します。

 rosterオブジェクトの生成はスレッド保護されているため、同期を行わずに複数のスレッドからBMediaRoster::Roster()を安全に呼び出すことができます。また、両方のスレッドが、同じインスタンスを安全に得ることになります。この同期にかかるコストは十分に低いため、返されたポインタをキャッシュする必要はありません。しかしそう望むなら、それは完璧に安全です。

   BMediaRoster *gMediaRoster;
   
   int main(void) {
      status_t err;
   
      BApplication app("application/x-vnd.me-myself");
      gMediaRoster = BMediaRoster::Roster(&err);
   
      if (!gMediaRoster || (err != B_OK)) {
         /* the Media Server appears to be dead -- handle that here */
      }
   
      /* The Media Server connection is in place -- enjoy! */
   
      return 0;
   }

 BMediaRosterはBLooperから派生しているため、BMediaRoster::Roster()を呼ぶ前にBApplicationを生成して下さい。BApplicationはまだ動作していなくても構いませんが。

 BMediaRoster::Roster()から返されたBMediaRosterは、決して削除しないで下さい。同様に、BMediaRosterからクラスを派生させることはできません。

 もし、例えばnodeがオンラインやオフラインになったというような特定の変化が生じた際にMedia Serverから通知を受け取りたければ、StartWatching()を呼び出すことで、そのような通知を受け取るように登録することができます。


Playing Media from Disk

 ディスクのメディアファイルを演奏するには、下記の段階を踏みます :

 これを行う実際のサンプルコードをご覧下さい。この例ではムービーファイルを再生することに特化しています。特に、ビデオがエンコードされており(B_MEDIA_ENCODED_VIDEO)、オーディオが生の(raw)オーディオフォーマット(B_MEDIA_RAW_AUDIO)であると仮定しています。しかしながら、これはエンコードされたフォーマットと生の(raw)メディアフォーマットを演奏する方法を実証しており、再生する必要のある任意の型をそれから簡単に推定することができるでしょう。初めにファイルを扱うための適切なnodeを識別する必要があります。また、nodeのインスタンスを生成し、それを演奏したいファイルのために設定する必要があります :

   bigtime_t      duration;
   media_node      timeSourceNode;
   
   media_node      mediaFileNode;      
   media_output   fileNodeOutput;
   int32         fileOutputCount;
   
   media_output   fileAudioOutput;
   int32         fileAudioCount;
   
   media_node      codecNode;
   media_output   codecOutput;
   media_input      codecInput;
   
   media_node      videoNode;
   media_input      videoInput;
   int32         videoInputCount;
   
   media_node      audioNode;
   media_input      audioInput;
   int32         audioInputCount;
   
   dormant_node_info nodeInfo;
   status_t err;
   
   playingFlag = false;
   roster = BMediaRoster::Roster();
   
   initStatus = roster->SniffRef(*ref, 0, &nodeInfo);
   if (initStatus) {
      return;
   }
   
   initStatus = roster->InstantiateDormantNode(nodeInfo, &mediaFileNode);
   if (initStatus) {
      return;
   }
   
   roster->SetRefFor(mediaFileNode, *ref, false, &duration);
   if ((err = Setup()) != B_OK) {
      printf("Error %08lX in Setup()n", err);
   }
   else {
      Start();
   }

 このコードはmedia rosterのポインタを得ることから始まります。その後、refで指定されるファイルからのメディアデータを読み込むためにもっとも適切なnodeを記述しているdormant_node_info構造体を得るためにSniffRef()を呼び出します。

 一旦dormant_node_info構造体に書き込みが行われたら、そのファイルを扱うnodeのインスタンスを生成するためにInstantiateDormantNode()関数が呼び出されます。休眠中(dormant)のnodeは、コードがアプリケーション自身の中でなく、add-onの中に存在するnodeです。nodeInfo構造体はその関数に渡され、返るときにはmediaFileNodeが適切なnodeがセットアップされています。

 media_node mediaFileNodeはファイルを扱うnodeであるため、SetRefFor()関数は新しくインスタンスを生成されたファイルハンドラnodeに対しどのようなファイルを扱うか知らせるために呼び出されます。入力はこういった風です :

 一旦これが達成されると、次はメディアの再生を行うのに必要な他のnodeのインスタンスを作成する番です。コードはこれらの呼び出しを各々チェックしB_OKが返されたときのみ処理を続行します。

 上記の例で使用されているSetup()及びStart()関数は、下記のようにして得られます。Setup()は、メディアデータを演奏するために要求される(codecや出力nodeといった)他のnodeとの接続及びインスタンスの作成を実際にセットアップします。次のSetup()を見てみましょう。

   status_t MediaPlayer::Setup(void) {
      status_t err;
      media_format tryFormat;
      dormant_node_info nodeInfo;
      int32 nodeCount;
   
      err = roster->GetAudioMixer(&audioNode);
      err = roster->GetVideoOutput(&videoNode);

 最初に、GetAudioMixer()及びGetVideoOutput()がオーディオミキサーnodeとビデオ出力nodeを得るために呼び出されます。この関数から返されるnodeはAudioとVideoの初期設定アプリケーションのユーザ設定を基本としています。デフォルトでは、ビデオは、ビデオを表示するためのウィンドウを生成する単純なビデオ出力consumerから出力されます。

 
 VideoConsumer nodeは、R4.5で使用可能になります。R4では提供されていません。加えて、R4ではvideo producer nodeがありません。多様なムービーファイルフォーマットに対応するメディアadd-onも、R4.5から使用できるようになります。


      err = roster->GetTimeSource(&timeSourceNode);
      b_timesource = roster->MakeTimeSourceFor(timeSourceNode);

 このコードは妥当なtime sourceのためのmedia_nodeを得て、その後、同じnodeを参照するBTimeSourceオブジェクトを生成します。ある特定のタイミング情報を後で得るために、いくつかのBTimeSource呼び出しを可能とする必要があります。

 time sourceは、他のnodeと同期するために使用されるnodeです。デフォルトでは、nodeはコンピュータの内部時計であるsystem time sourceに従属しています。しかしながら、このtime sourceは非常に厳密であるにも関わらず、演奏されている実際のメディアとは全く関わりがないというコンセプトであることから、メディアデータの演奏には向いていません。この理由から、ユーザは典型的な使用方法として、nodeのtime sourceを適切なものに変更しようと考えるでしょう。

 (media_node構造体によって表現される)media nodeは、家庭にあるホームシアターシステムであると考えることができます。それには(各々に複数の入力がありうる)オーディオとビデオの入力があり、システムの他のコンポーネントにオーディオとビデオを渡す出力があります。コンポーネントを使用するには、他のコンポーネントの出力をコンポーネントの入力とをケーブルで接続しなければならず、また出力を他のコンポーネントの入力に接続しなければなりません。

 Media Kitは、それと同じ様に動作します。mediaFileNodeからオーディオ出力の位置を特定し、それに対応するaudioNodeの入力を探します。これは、新しいDVDプレーヤのオーディオ出力を選び、それをステレオ受信機のオーディオ入力ジャックに適合させることと類似しています。すでに使用中のポートは使用できないため、フリーなmediaFileNodeの出力ポートを探すためにGetFreeOutputsFor()を呼び出し、フリーなaudioNodeの入力ポートの位置を特定するためにGetFreeInputsFor()を呼び出します。

      err = roster->GetFreeOutputsFor(mediaFileNode, &fileAudioOutput, 1,
                  &fileAudioCount, B_MEDIA_RAW_AUDIO);
      err = roster->GetFreeInputsFor(audioNode, &audioInput, fileAudioCount,
                  &audioInputCount, B_MEDIA_RAW_AUDIO);

 必要なのは、二つのnodeを結ぶ単独のオーディオ接続だけであり(単独の接続でステレオ音声を扱えます)、その接続はB_MEDIA_RAW_AUDIO型です。返される際には、fileAudioOutputaudioInputは、ムービーの音声を演奏するため最終的に接続されるmediaFlieNodeからの出力とaudioNodeへの入力を記述します。

 さらに、mediaFileNodeからの出力とvideoNodeへの入力を探さなければなりません。この場合、しかしながら、mediaFileNodeからのビデオ出力がエンコードされると予想されますし、またvideoNodeがrawで非圧縮なビデオを受け取りたがることが予測されます。それは1分でやり遂げられます。では、二つのポートを見つけましょう。

      err = roster->GetFreeOutputsFor(mediaFileNode, &fileNodeOutput, 1,
                  &fileOutputCount, B_MEDIA_ENCODED_VIDEO)
      err = roster->GetFreeInputsFor(videoNode, &videoInput, fileOutputCount,
                  &videoInputCount, B_MEDIA_RAW_VIDEO);

 現時点での問題は、なんらかの形で(例えばCinepakフォーマットの様に)エンコードされたビデオを出力するということです。videoNodeは、一方でrawなビデオを表示しようとします。もう片方のnodeは、ビデオを(例えばPALビデオをNTSCに変換するアダプターの様に)デコードするためにこれらの間に置かれなければなりません。このnodeは、ビデオをrawな形式に伸長するcodecとなります。

 mediaFileNodeからの出力のビデオ形式を扱うことのできるcodec nodeの位置を特定する必要があります。それはこのように行われます :

      nodeCount = 1;
      err = roster->GetDormantNodes(&nodeInfo, &nodeCount,
                  &fileNodeOutput.format);
      if (!nodeCount) {
         return -1;
      }

 このGetDormantNodes()の呼び出しは、mediaFileNodeの出力するmedia_format構造体によって指定されたメディアフォーマットを扱うことのできる休止中のnodeを探します。このnodeに関する情報はnodeInfoに返されます。nodeCountは、検索によって探しだされたnodeの数を示します。もし0なら、エラーが返されます。

 実際には、いくつかのnodeに対し、それを通じてもっとも用途に適合するものを見つけるまで、フォーマットに目を通すよう要求すべきだということに注意して下さい。

 それから、codec nodeのインスタンスを生成するためにInstantiateDormantNode()を使用し、その(エンコードされたビデオを受け入れる)nodeへの入力と(rawなビデオを出力する)nodeの出力の位置を特定します :

      err = roster->InstantiateDormantNode(nodeInfo, &codecNode);
      err = roster->GetFreeInputsFor(codecNode, &codecInput, 1, &nodeCount, 
                  B_MEDIA_ENCODED_VIDEO);
      err = roster->GetFreeOutputsFor(codecNode, &codecOutput, 1,
                  &nodeCount, B_MEDIA_RAW_VIDEO);

 さて、node達がともに接続を開始する準備が整いました。もしホームシアターシステムをセットアップした場合なら、今はひざ掛けをひざに乗せて 手の中で指の関節の皮をむき、アミューズメントセンターを稼働させようとして後ろに手を伸ばした状態です。Media Kitはそれよりも簡単な方法であり、セールスマンに高価な金メッキのケーブルを買えと言われなくてすみます。

 ファイルnodeのビデオ出力をcodecの出力に接続することで始まります :

      tryFormat = fileNodeOutput.format;
      err = roster->Connect(fileNodeOutput.source, codecInput.destination,
                  &tryFormat, &fileNodeOutput, &codecInput);

 tryFormatは、mediaFileNodeによって出力される予定の、エンコードされたビデオのフォーマットを示します。本質的に、Connect()は、media nodeのビデオ出力(fileNodeOutput)とcodec nodeの入力との間の接続を動作させます。

 fileNodeOutput.source及びcodecInput.destination構造体がどうなったか不思議に思うかも知れません。media_source及びmedia_destination構造体は接続の両端の単純化された記述子(descriptor)です。それらにはMedia Kitが接続を確立するのに絶対的に必要なデータのみが含まれています。これはConnect()呼び出しがが発行された際に、ある程度の時間を節約することができます(そして、特にメディアの仕事では、時は金なり、です)。

 次に、ビデオ出力nodeにcodecを接続する必要があります。これはcodecに渡されるエンコードされたビデオと同じ幅と高さの生(raw)のビデオを記述する、tryFormatをセットアップすることからはじめます。それから接続を確立するためにConnect()を呼び出します :

      tryFormat.type = B_MEDIA_RAW_VIDEO;
      tryFormat.u.raw_video = media_raw_video_format::wildcard;
      tryFormat.u.raw_video.display.line_width =
               codecInput.format.u.encoded_video.output.display.line_width;
      tryFormat.u.raw_video.display.line_count =
               codecInput.format.u.encoded_video.output.display.line_count;
      err = roster->Connect(codecOutput.source, videoInput.destination,
                  &tryFormat, &codecOutput, &videoInput);
   

 さて、メディアファイルからの音声を、オーディオミキサーに接続します。接続の両端は厳密に一致しているので、ファイルの音声出力から得たmedia_formatを複製するだけです。

      tryFormat = fileAudioOutput.format;
      err = roster->Connect(fileAudioOutput.source, audioInput.destination,
                  &tryFormat, &fileAudioOutput, &audioInput);

 接続を設定する最後のステップは、全てのnodeが好ましい(preferred)time sourceに従属することを確実にすることです。これは好ましいtime sourceでnodeが同期する状態(そして、それぞれが互いに合同する状態)を維持します :

      err = roster->SetTimeSourceFor(mediaFileNode.node, timeSourceNode.node);
      err = roster->SetTimeSourceFor(videoNode.node, timeSourceNode.node);
      err = roster->SetTimeSourceFor(codecOutput.node.node,
               timeSourceNode.node);
      err = roster->SetTimeSourceFor(audioNode.node, timeSourceNode.node);
      return B_OK;
   }

 最後に、呼び出し元に対してB_OKを返します。このコードは、それぞれのBMediaRoster呼び出し結果のチェックと、もしB_OKでなければ結果コードを返すことを強調すべきであることに注意して下さい。このことは、この例では簡潔さのために無視されています。

 Start()関数は、実際にムービーの再生を開始します。再生を開始すると、全てのnodeは同時に1つだけの音声再生に関連づけられます。これにはオーディオミキサー(audioNode)、メディアファイルのnode(mediaFileNode)、codec及びビデオnodeが含まれます。

   status_t MediaPlayer::Start(void) {
      status_t err;
      err = roster->GetStartLatencyFor(timeSourceNode, &startTime);
      startTime += b_timesource->PerformanceTimeFor(BTimeSource::RealTime()
                  + 1000000 / 50);
      
      err = roster->StartNode(mediaFileNode, startTime);
      err = roster->StartNode(codecNode, startTime);
      err = roster->StartNode(videoNode, startTime);
   
      return B_OK;
   }

 それぞれのnodeの開始にはタイムラグがあるため、再生開始のためには数瞬だけ未来の時間が選ばれ、それぞれのnodeがその時間に再生開始されるよう予定が組まれます。そうして、未来のその時間を計算することで演奏が開始されます。

 静的メンバ関数であるBTimeSource::RealTime()は、現在の現実のシステム時間を得るために呼ばれます。その時間には50分の1秒が追加され、さらにperformance time単位に変換されます。これはムービーの再生が開始される時間です(基本的に、「今」から50分の1秒後です)。この値はstartTimeに保存されます。これはGetStartLatencyFor()によって返される値に追加されます。GetStartLatencyFor()は実際にそのtime sourceを開始するのに要求され、全てのnodeが従属する時間を返します。

 その後、それぞれのnodeに対しBMediaRoster::StartNode()が単純に呼び出され、再生が開始されるperformance timeとしてstartTimeを指定します。

 この場合も、これらの関数からのエラーコードが実際に返されるように、エラー処理を追加して下さい。

 ムービーの再生を停止させるのは、更に簡単です :

      err = roster->StopNode(mediaFileNode, 0, true);
      err = roster->StopNode(codecNode, 0, true);
      err = roster->StopNode(videoNode, 0, true);

 これはメディアファイル、ビデオcodec及びビデオ出力nodeに対して、即座に停止するよう伝えます。もしnodeを任意の時間に同時に停止させたいなら、適切なperformance timeを演算し、0の代りにそれを渡します。

 
オーディオミキサーnodeを停止させないことに注意して下さい。他のアプリケーションが使用しているかも知れないため、ミキサーnodeは決して停止させてはなりません。


 一旦ムービーの再生が終わり、再生が停止したら、それぞれのnodeの間の接続を切断して下さい :

      err = roster->Disconnect(mediaFileNode.node, fileNodeOutput.source,
                   codecNode.node, codecInput.destination);
      err = roster->Disconnect(codecNode.node, codecOutput.source,
                   videoNode.node, videoInput.destination);
      err = roster->Disconnect(mediaFileNode.node, fileAudioOutput.source,
                   audioNode.node, audioInput.destination);
   

 これは、メディアファイルnodeとビデオcodecの間の接続、codecとビデオ出力の間の接続、そしてファイルnodeとオーディオミキサーの間の接続をクローズします。接続を切断する前にはかならず演奏を中止して下さい。もしnodeの動作中に接続を切断されても、nodeはクラッシュすることを許されません。しかしそれらの動作は指定されておらず、あなたにとって予想のつかないものになるでしょう。

 一旦接続がダメージを受けたら、あなたがインスタンスを生成した休止中の全てのnodeを開放して下さい。これはInstantiateNodeFor()を使用してインスタンスを作成されたnodeのみならず、デフォルトのnodeも含まれます(例えば、GetAudioInput()GetVideoOutput()といった関数を使用して得られたもの) :

      roster->ReleaseNode(codecNode);
      roster->ReleaseNode(mediaFileNode);
      roster->ReleaseNode(videoNode);
      roster->ReleaseNode(audioNode);

 
音声を演奏したい場合、そうするためにBSoundクラス及びBSoundPlayerクラスを使用するほうがとても簡単だと分かるでしょう。R4.5では、Be社によって提供された、ディスクのファイルから音声を供給するためのnodeはありません。



Detecting When Playback Is Complete

 Media Kitの関数には、再生中にメディアがデータの終端に到達したかどうか直接教えてくれるものはありません。しかしながら、下記の簡単に実装できるコードによって、その作業を行わせることができます :

   bigtime_t currentTime;
   bool isPlaying = true;
   
   currentTime = b_timesource->PerformanceTimeFor(BTimeSource::RealTime());
   if (currentTime >= startTime+duration) {
      isPlaying = false;
   }

 これは、time sourceのperformance timeを得、それとムービーの再生が始まってからの時間とムービーの時間的な長さを足したものを比べることによって動作します(両方とも、初期設定時及びムービーの再生時に保存されています。上記の一つ前のセクションのコードをご覧下さい)。

 もし現在のperformance timeが、開始時間とムービーの長さの合計と等しいか大きければ、再生は終了し、isPlayingfalseにセットされます。そうでなければ、この値はtrueのままです。


Using BMediaRoster Functions from Nodes

 あなたはBMediaRosterの関数呼び出しをあなた自身のnodeから発行できますが、しかし一般的なルールとして、BMediaRosterの関数を制御スレッドの中から呼び出したり、あるいは制御スレッドがブロックされている間に呼び出したりしてはいけません。多くのBMediaRoster関数は同期的な動作変更を使用しており、この状況ではデッドロックを生じてしまうのです。安全のため、これらのケースでは全てのBMediaRoster関数がデッドロックを生じると想定して下さい。

 例えば、もしウィンドウでビデオを再生するアプリケーションがあって、そのウィンドウのMessageReceived()関数からStopNode()を呼び出せば、ロックされないウィンドウ上でビデオの再生nodeが待機(waiting)をブロックし、StopNode()関数が(consumer node上で待機をブロックし、そして先へ進むはずの)ビデオ供給nodeを待っている間ウィンドウをロックし続けるなら、デッドロックが生じます。デッドロックが生じ、それはよくないことなのです。

 その代わりに、nodeを管理するためのBLooperを別個に作成することを考慮して下さい。Media Kitの将来のバージョンでは、これのいくつかを行ってくれる便利なクラスが提供される予定です。


Constructor and Destructor


BMediaRoster()

                                                         
  

BMediaRoster()

 BMediaRosterを決してコンストラクトしてはいけません。その代わりに、静的な関数であるRoster()を、使用可能なBMediaRosterクラスのインスタンスを得るために使用して下さい。


~BMediaRoster

                                                         
  

~BMediaRoster()

 決してBMediaRosterを削除してはいけません。アプリケーションが終了する際、自動的に削除されます。


Member Functions


AudioBufferSizeFor()

                                                         
  

ssize_t AudioBufferSizeFor(int32 channelCount,
      uint32 sampleFormat,
      float frameRate,
      bus_type busKind)

 AudioBufferSizeFor()は、sampleFormat及びframeRateで指定された、channelCountチャンネルの音声データについて、Media Kitの推奨する大きさをbyte単位で返します。

 引数busKindは、データが通過するバスの型を示すbus_type値(drivers/config_manager.hをご覧下さい)です。もし分からなければ、B_UNKNOWN_BUSを指定して下さい。


Connect() , Disconnect()

                                                         
  

status_t Connect(const media_source &source,
      const media_destination &destination,
      media_format *ioFormat,
      media_output *outOutput,
      media_input *outInput)

status_t Connect(const media_source &source,
      const media_destination &destination,
      media_format *ioFormat,
      media_output *outOutput,
      media_input *outInput,
      uint32 inFlags,
      void *_reserved = NULL)

status_t Disconnect(media_node_id sourceNode,
      const media_source &source,
      media_node_id destinationNode,
      const media_destination &destination)

 Connect()は、交渉の基礎となるioFormatによって指定されるメディアフォーマットを使用して、sourceからdestinationへの接続を交渉します。ioFormatは、この呼び出しが返る前に、交渉されたフォーマットに変更されます。これは接続を流れる予定のメディアデータのフォーマットを記述します。

 実際の接続は、outOutput及びoutInputにより、出力と入力として返されます。これら2つの構造体には、sourceとdestinationによって解釈されるデータのフォーマットが含まれます。もとのフォーマットにおいてワイルドカードフィールドが使用されていれば、これらのフォーマットの間には相違があるかも知れません。

 二つ目のConnect()の形式では、接続フラグを指定できます。現在のところ、B_CONNECT_MUTEDのみ使用できます。これは、接続が生成される際にはミュートされることを示します。

 接続に実際に使用されるmedia_sourceとmedia_destinationは、sourceまたはdestinationが新しいsourceまたはdestinationを各々の接続要求に対して生成するならば、Connect()に渡されるものとは違うものになります。

 フォーマット交渉に於けるワイルドカードの使用に関する詳細な情報については、media_audio_format::wildcard及びmedia_video_format::wildcardをご覧下さい。B_MEDIA_UNKNOWN_TYPE型のmedia_formatは、任意のメディアクラス及びフォーマットに一致します。source及びdestinationについての特別な知識がなくても、これは見事に役に立つ接続を行うでしょう。

 Disconnect()は、sourcedestinationとの間に確立された接続を中断します。それらは各々がsourceNode及びdestinationNodeに所属しなければなりません。

 現在動作中の接続を中断した結果は定義されていませんが、クラッシュすることは許可されません。アプリケーションは、それらの接続を切断するより先に、関連する両方のnodeを停止させるべきです。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. 接続を終了させる際にエラーは生じなかった。


CurrentRoster() see Roster()


GetAllInputsFor() , GetAllOutputsFor()

                                                         
  

status_t GetAllInputsFor(const media_node &node,
      media_input *outInputs,
      int32 bufNumInputs
      
int32 *outTotalCount)

status_t GetAllOutputsFor(const media_node &node,
      media_output *outOutputs,
      int32 bufNumOutputs
      
int32 *outTotalCount)

 GetAllInputsFor()は、outInputsで指定されるmedia_input構造体の配列に、nodeに所属する全ての入力に関する情報を書込みます。outInputsが持ちうる要素の数は、bufNumInputsで渡されます。

 同様に、GetAllOutputsFor()は配列outOutputsに、nodeで指定される全ての出力に関する情報を書込みます。

 両方の関数とも、outTotalCountのバッファに実際に返される要素の数を返します。もしこの数が要求された数より少なければ、バッファは全てのクエリの結果を受け取るには小さすぎます。この場合は、配列のサイズを変更し、再度挑戦して下さい。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. エラーなし。


GetAllOutputsFor() see GetAllInputsFor()


GetAudioInput() , GetVideoInput()

                                                         
  

status_t GetAudioInput(media_node *outNode)

status_t GetVideoInput(media_node *outNode)

 これらの関数は、音声及びビデオ入力に適切なnodeとしてユーザにデザインされたnodeを返します。outNodeに返される参照を使用して、返されたnodeに対して問い合わせたり、フックしたり、操作したりできます。

 一旦アプリケーションがこれらのnodeを使い終わったら(そしてそれらが停止し、接続を切断されたら)、それらをReleaseNode()呼び出しによって開放して下さい。

RETURN CODES

B_OK. デフォルトの入力nodeのlocatingに際し、エラーは生じなかった。


GetAudioMixer() see GetAudioOutput()


GetAudioOutput() , GetVideoOutput() , GetAudioMixer()

                                                         
  

status_t GetAudioOutput(media_node *outNode)

status_t GetAudioOutput(media_node *outNode, int32 *outInputID
      
BString *outInputName)

status_t GetVideoOutput(media_node *outNode)

status_t GetAudioMixer(media_node *outNode)

 これらの関数は、音声及びビデオ入力に適切なnodeとしてユーザにデザインされたnodeを返します。outNodeに返される参照を使用して、返されたnodeに対して問い合わせたり、フックしたり、操作したりできます。

 GetAudioOutput()の2番目の形式は、追加情報を返します。それには、音声出力によって使用されるinput ID及び入力の名前が含まれます。

 普段は、音声を演奏するためのnodeを得る際には、GetAudioOutput()関数を使う代りにGetAudioMixer()を使用します。

 GetAudioMixer()関数は、音声のミキシング処理、フォーマット変換及びサンプリング周波数の変換を行うオーディオミキサーへの参照を返し、その後に出力nodeに音声を受け渡します。

 一旦アプリケーションがこれらのnodeを使い終わったら(そしてそれらが停止し、接続を切断されたら)、ReleaseNode()を呼び出してそれらを開放して下さい。

RETURN CODES

B_OK. デフォルトの入力nodeをlocatingする際に、エラーは生じなかった。


GetConnectedInputsFor() , GetFreeInputsFor()

                                                         
  

status_t GetConnectedInputsFor(const media_node &node,
      media_input *outActiveInputsList,
      int32 numListInputs
      
int32 *outNumInputs)

status_t GetFreeInputsFor(const media_node &node,
      media_input *outFreeInputsList,
      int32 numListInputs
      
int32 *outNumInputs,
      media_type filterType = B_MEDIA_UNKNOWN_TYPE)

 GetConnectedInputsFor()は、outActiveInputsListによって指定されるmedia_input構造体の配列に、現在何らかの出力に接続されているnodeに所属する全ての入力に関する情報を書込みます。outActiveInputsListが持ちうる要素の数は、numListInputsで渡されます。

 同様に、GetFreeInputsFor()は、配列outFreeInputsListに、nodeによって指定される、まだ使用可能な全ての入力に関する情報を書込みます。

 
例えnodeがフリーな入力が特定の数だけ使用できると報告したとしても、nodeは必要なときにより多くの入力を作成することができます。これが生じるかどうかを知る方法はないため、GetFreeInputsFor()は、あるnodeが生成を必要とされる接続を全て受け入れられるかどうかを教えてはくれないでしょう。


 両方の関数とも、outNumInputsのバッファに、実際に返される要素の数を返します。もしこの数がnumListInputsより小さければ、バッファが全ての検索結果を受け取るには小さすぎるということです。この場合、配列の大きさを変更して、再度試してみて下さい。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. nodeのクローズ時にエラーなし。


GetConnectedOutputsFor() , GetFreeOutputsFor()

                                                         
  

status_t GetConnectedOutputsFor(const media_node &node,
      media_output *outActiveOutputsList,
      int32 numListOutputs
      
int32 *outNumOutputs)

status_t GetFreeOutputsFor(const media_node &node,
      media_output *outFreeOutputsList,
      int32 numListOutputs
      
int32 *outNumOutputs,
      media_type filterType = B_MEDIA_UNKNOWN_TYPE)

 GetConnectedOutputsFor()は、outActiveOutputsListで指定されるmedia_output構造体の配列に、現在なんらかの入力に接続しているnodeに所属している全ての出力に関する情報を書込みます。outActiveOutputsListが持ちうる要素の数は、numListOutputsで渡されます。

 同様に、GetFreeOutputsFor()は、配列outFreeOutputsListに、指定されたnodeで使用可能な全ての出力に関する情報を書込みます。B_MEDIA_UNKNOWN_TYPEではなくfilterTypeを指定することで、特定のメディア型の出力(または任意のメディア型を扱える出力)のリストを得られます。これは、アプリケーションがサポートする、使用可能なメディア型のリストにのみ興味がある場合、特に便利です。

 
 例えnodeがフリーな出力が特定の数だけ使用できると報告したとしても、nodeは必要なときにより多くの出力を作成することができます。これが生じるかどうかを知る方法はないため、GetFreeOutputsFor()は、あるnodeが生成を必要とされる接続を全て受け入れられるかどうかを教えてはくれないでしょう。


 両方の関数とも、outNumInputsのバッファに、実際に返される要素の数を返します。もしこの数がnumListInputsより小さければ、バッファが全ての検索結果を受け取るには小さすぎるということです。この場合、配列の大きさを変更して、再度試してみて下さい。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. No error.


GetDormantFlavorInfoFor()

                                                         
  

status_t GetDormantFlavorInfoFor(const dormant_node_info &inDormantNode,
      dormant_flavor_info *outFlavor)

 この関数は、outFlavorに、休止中のnode inDormantNodeにサポートされている休止中のフレーバーを記述する情報を書込んで戻ります。

RETURN CODES

B_OK. エラーなし。


GetDormantNodes()

                                                         
  

status_t GetDormantNodes(dormant_node_info *outDormantNodeList,
      int32 *inOutNumNodes,
      const media_format *hasInputFormat = NULL,
      const media_format *hasOutputFormat = NULL,
      char *name = NULL,
      uint64 requireKinds = 0,
      uint64 denyKinds = 0)

 休止中のnode(アプリケーションの中より、むしろadd-onの中に生息している)を検索し、その中から指定された入力に一致するnodeを返します。もしhasInputFormatNULLでなければ、nodeはBBufferConsumerのはずであり、hasInputFormatに記述されたものと互換性のある入力フォーマットを持つはずです。同様に、もしhasOutputFormatNULLでなければ、nodeはhasOutputFormatに記述されたフォーマットと互換性のあるBBufferProducerのはずです。

 もしnameNULLでなければ、nodeはnameと等しい名前をもつか、もしnameの最後の文字がアスタリスク ("*") であれば、最初からアスタリスクまでの文字列がnameに一致するが、アスタリスクは含まない名前でなければなりません。

 引数requireKinds及びdenyKindsはそれぞれ、返されたnodeによってサポートされるはずの種類を指定するものと、サポートされないはずの種類を指定するものです。

 一致したnodeは、outDormantNodeListで返されます。outDormantNodeListの配列のサイズを、inOutNumNodesに渡して下さい。この関数が返ったとき、inOutNumNodesの値は、エラーが起こらなかった場合、一致したnodeの実際の数に変更されます。

 GetDormantNodes()を使用して得られたnodeは、使い終わったら開放しなければなりません。これを行うには、nodeが停止し、接続が解除されていることを確認した後、ReleaseNode()を呼び出して下さい。

RETURN CODES

B_OK. nodeを閉じる際にエラーは生じなかった。


GetFileFormatsFor()

                                                         
  

status_t GetFileFormatsFor(const media_node &fileInterface,
      media_file_format *outFormatList,
      int32 *inOutFormatCount)

 fileInterfaceBFileInterface nodeを与えると、配列outFormatListに、ファイルインターフェイスが扱うことのできるファイルのフォーマットに関する情報を返します。関数の呼び出し時、inOutFormatCountは、outFormatListによって指定される配列に見合うmedia_file_format構造体の数へのポインタを指します。関数が戻る際には、GetFileFormatsFor()がエラーを返さなければ、これには返されたフォーマットの実際の数が収まっています。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. モード設定の要求を送信する際、エラーが生じなかった。


GetFormatFor()

                                                         
  

status_t GetFormatFor(const media_output &output,
      media_format *ioFormat, uint32 flags = 0)

status_t GetFormatFor(const media_input &input,
      media_format *ioFormat, uint32 flags = 0)

status_t GetFormatFor(const media_node &node,
      media_format *ioFormat, float quality = B_MEDIA_ANY_QUALITY)

 GetFormatFor()は、与えられたオブジェクトに使用されているmedia_formatを返します。media_formatは、おそらくmedia_outputか、media_inputか、あるいはmedia_nodeでしょう。オブジェクトのフォーマットによって埋められるように、ioFormatにmedia_formatオブジェクトへのポインタを渡して下さい。

 現在のところ、flagsは必ずゼロでなければなりません。

RETURN CODES

B_OK. エラーなし。


GetFreeInputsFor() see GetConnectedInputsFor()


GetFreeOutputsFor() see GetConnectedOutputsFor()


GetInitialLatencyFor()

                                                         
  

status_t GetInitialLatencyFor(media_node &producer,
      bigtime_t *outLatency, uint32 *outFlags = NULL)

 outLatencyに、特定のproducer nodeが信号を同期するために要求する、マイクロ秒単位の時間が返されます。例えば、TVキャプチャカードがフィールドの途中をキャプチャしている最中に開始された場合、実際にproducerのバッファを開始する前に、次のフィールドが開始されるまで待つ必要があります。

 outFlagsは、producerによって返されるフラグを設定します。現在のところフラグは定義されていませんので、今はゼロが返されます。

RETURN CODES

B_OK. エラーなし。


GetInstancesFor()

                                                         
  

status_t GetInstancesFor(media_addon_id addon, int32 flavor,
      media_node_id *outID, int32 *ioCount = 0)

 指定したaddon IDとflavorを与えることで、この関数は指定したadd-onから派生したnodeのoutIDリストをioCount node IDに格納します。もしioCountにゼロを指定したら、一つのnode IDが返されます。戻る際には、ioCountに、リストとして返されたnodeがいくつだったか示す値に変更されます。

RETURN CODES

B_OK. エラーなし。


GetLatencyFor()

                                                         
  

status_t GetLatencyFor(const media_node &producer, bigtime_t *outLatency)

 現在の接続から得られたBBufferProducerであるproducerによって指定された下流に於ける最大の遅延時間 (latency) をBBufferProducerで報告します。

 もしエラーが生じれば、outLatencyは信頼できない値となります。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. エラーなし。


GetLiveNodes()

                                                         
  

status_t GetLiveNodes(live_node_info *outLiveNodeList, int32 *ioTotalCount,
      const media_format *hasInput = NULL,
      const media_format *hasOutput = NULL,
      const char *name = NULL,
      uint64 nodeKinds = 0)

 (動作しているか否かに関わらず)現在アクティブな全てのnodeのリストを得るためにMedia Serverを検索し、outLiveNodeListによって指定される配列にnodeに関する情報を格納します。配列のサイズは—それが格納しうる要素がいくつなのかという観点からすると—引数ioTotalCountによって指定すべきです。返されたリストのエントリの実際の数は、関数が戻る前にioTotalCountに保存されます。

 add-on中に存在し、InstantiateDormantNode()によってインスタンスが作成される時にのみロードされる休止中のnodeに対し、アクティブなnodeはシステムにあらかじめロードされ、常に使用可能です。

 引数hasInputhasOutputname及びnodeKindsのうち一つまたはそれ以上を指定することで、さらに具体的な結果リストを得ることができます。hasInput及びhasOutputは、指定されたフォーマットの入力(または出力)を受け入れるnodeを格納している結果リストを限定します。

 nodeKindsには、常に0を指定して下さい。このパラメータは、現在使用されていません。

RETURN CODES

B_OK. エラーなし。


GetNodeAttributesFor()

                                                         
  

ssize_t GetNodeAttributesFor(const media_node &node,
      media_node_attributes *outArray, size_t inMaxCount)

 与えられたnodeinMaxCount個までの属性(アトリビュート)で、配列outArrayを埋めます。返された属性の数を返します。もし結果がゼロより小さければ、エラーが生じたということです。

<<<node attributeで更に解説します>>>


GetNodeFor()

                                                         
  

status_t GetNodeFor(media_node_id nodeID, media_node *clonedNode)

 node_idによって指定されたnodeを与えることにより、GetNodeFor()clonedNodeに、そのnodeの複製(クローン)へのmedia_node型の参照を返します。clonedNodeを使うことにより、そのnodeで使用可能な入力や出力等を探索することができます。

 一旦アプリケーションが返されたnodeを使い終わったら(そしてnodeが停止させられ、接続が解除されていれば)、ReleaseNode()を呼び出してそのnodeを開放して下さい。

RETURN CODES

B_OK.  nodeを複製する際にエラーは生じなかった。


GetParameterWebFor()

                                                         
  

status_t GetParameterWebFor(const media_node & node,
      BParameterWeb **outWeb)

 指定された制御可能(controllable)なnodeの内部的な配置を記述し、outWebBParameterWebへのポインタを保存するBParameterWebのインスタンスを生成します。制御するために何があるのかを判断し、ユーザインターフェイスをnodeのパラメータに与えるために、様々なBParameterを使うことができます。それが終わったら、outWebで与えられるポインタを削除して下さい。

 StartControlPanel()関数が、nodeの設定のためのユーザインターフェイスを自動的に与えるための、簡単で負担の少ない方法を提供するということに留意して下さい。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. BParameterWebを得る際にエラーが生じなかった。

StartControlPanel()もご覧下さい。


GetReadFileFormatListFor() , GetWriteFileFormatListFor()

                                                         
  

status_t GetReadFileFormatList(const dormant_node_info &inNode,
      media_file_format *outReadFormats,
      int32 inReadCount, int32 *outReadCount)

status_t GetWriteFileFormatList(const dormant_node_info &inNode,
      media_file_format *outWriteFormats,
      int32 inWriteCount, int32 *outWriteCount)

 これらの2つの関数は、inNodeによって記述される休止中のnodeが読み書きできるファイルフォーマットのリストを返します。

 GetReadFileFormatList()は、outReadFormatsによって指定される配列に、そのnodeが読み込めるファイルフォーマットのリストを返します。inReadCountに、配列outReadFormatsが持ちうるフォーマットの数を指定して下さい。関数が返る際に、outReadCountは、配列に返されたフォーマットがいくつであるかを示します。

 GetWriteFileFormatList()は、outWriteFormatsで指定される配列に、そのnodeが書込むことのできるファイルフォーマットのリストを返します。inWriteCountに、配列outWriteFormatsが持ちうるフォーマットの数を指定して下さい。関数が返る際に、outWriteCountは、配列に返されたフォーマットがいくつであるかを示します。

RETURN CODES

B_OK. リストはエラーなしに返された。


GetRealtimeFlags() , SetRealtimeFlags()

                                                         
  

status_t GetRealtimeFlags(uint32 *outEnabled)

status_t SetRealtimeFlags(uint32 inEnabled)

 GetRealtimeFlags()は、Media Serverがメモリをロックダウンする必要があるか否か決定するために使用するフラグを返します。SetRealtimeFlags()は、これらのフラグを設定し、一般的にMedia preferenceアプリケーションからのみ呼び出されます。

 これらのうち任意の、または全てのフラグを、組み合わせて設定できます。

Constant Description
B_MEDIA_REALTIME_ALLOCATOR セットすると、rtm_alloc()はロックされたメモリを返す。
B_MEDIA_REALTIME_AUDIO Media Serverのオーディオadd-onはメモリ上にロックされ、add-onのスレッドスタックのうちmedia_init_realtime_thread()を使用するものをロックする。
B_MEDIA_REALTIME_VIDEO ビデオadd-onはメモリ上にロックされ、add-onのスレッドスタックのうちmedia_init_realtime_thread()を使用するものをロックする。
B_MEDIA_REALTIME_ANYKIND 全てのMedia add-onはメモリ上にロックされ、add-onのスレッドスタックのうちmedia_init_realtime_thread()を使用するものをロックする。

 リアルタイムな領域確保とスレッドスタックのロックに関する論議は、BMediaNodeの概要をご覧下さい。

RETURN CODES

B_OK. エラーなし。


GetRefFor() see SetRefFor()


GetStartLatencyFor()

                                                         
  

status_t GetStartLatencyFor(const media_node &timeSource, bigtime_t *outLatency)

 現在の接続を与えることによって、outLatencyに、timeSourceで指定されたnodeのtime sourceから下流(downstream)の最大遅延時間(maximum latency)を求め、報告します。

 もしエラーが生じたら、outLatencyの値は信頼できないものとなります。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. エラーなし。


GetSystemTimeSource()

                                                         
  

status_t GetSystemTimeSource(media_node *clonedTimeSource)

 この関数は、clonedTimeSourceに、system time sourceの複製への参照を返します。system time sourceは、他のsourceが全く使用できないときに使用される頼みの綱のtime sourceです。その時間は、system_time()による現実の時刻から派生しています。それだけなら、このtime sourceは極めて正確ですが、メディアの入力及び出力に使用されるハードウェア機器のタイミングとは適切に関連していません。このように、このsourceはマスタークロックとしては良い選択ではないのです—しかし、何も使えるものがなければ、これを使うことができます。

 デフォルトでは、新しいnodeはsystem time sourceに従属しています。

RETURN CODES

B_OK. nodeの複製に際して、エラーは生じなかった。


GetTimeSource() , MakeTimeSourceFor()

                                                         
  

status_t GetTimeSource(media_node *outNode)

BTimeSource *MakeTimeSourceFor(media_node &node)

 GetTimeSource()は、outNodeに、他のnodeが従属できる優先権のあるマスタークロックを返します。全てのnodeが一つのマスタークロックに従属することで、良好な同期が保証されます。

 典型的には、優先権のあるマスタークロックはデフォルトの音声出力と同じnodeになります(これは音声出力nodeもBTimeSourceであると仮定した場合です。そうあるべきですが)。音声回路の構成要素であるDACは、タイミング参照のために使用されます。これは(system_time()広域関数で定義される)system clockに比べて正確ではありませんが、トラブルのない音声演奏が、メディア実行の同期に音声出力を用いることで最もよく保証されます。

 デフォルトでは、nodeはsystem time sourceに従属しています(上記のGetSystemTimeSource() をご覧下さい)。普通、より正確なtime sourceを得るためにこの関数を使用し、その後にnodeをこのsourceに従属させます :

   media_node timeSource;
   roster->GetTimeSource(&media_node);
   roster->SetTimeSourceFor(myNode, timeSource.node);

 これは、すでに生成されているnodeであるmyNodeを、優先権のあるtime sourceに従属させます。

 
time sourceの参照カウントは、GetTimeSource()によってインクリメントされません。GetTimeSource()によって返されたnodeでは、決してReleaseNode()を呼び出さないで下さい。


 MakeTimeSourceFor()は、指定されたnodeのtime sourceと一致するBTimeSourceオブジェクトを返します。このオブジェクトは、(例えば現在のperformance timeを決定するといった)タイミングの決定と調整のためにBTimeSource呼び出しを発行する場合に使用できます。

RETURN CODES

B_OK. デフォルトの入力nodeの位置を確認する際にエラーは生じなかった。


GetVideoInput() see GetAudioInput()


GetVideoOutput() see GetAudioOutput()


GetWriteFileFormatListFor() see GetReadFileFormatListFor()


InstantiateDormantNode()

                                                         
  

status_t InstantiateDormantNode(const dormant_node_info &inInfo,
      media_node *outNode)

status_t InstantiateDormantNode(const dormant_node_info &inInfo,
      media_node *outNode, uint32 flags)

 これらの関数は、dormant_node_info構造体によって指定された情報を与えることで、add-onからのnodeのインスタンスを生成します :

   struct dormant_node_info {
      dormant_node_info();
      ~dormant_node_info();
   
      media_addon_id addon;
      int32 flavor_id;
      char name[B_MEDIA_NAME_LENGTH];
   
   private:
      char reserved[128];
   };

 addonフィールドは、処理のためにnodeのインスタンスを作成したadd-onのadd-on IDを格納して下さい。flavor_idには、処理のためにインスタンスを作成されたnodeのflavorのID番号を収めて下さい。典型的には、GetDormantNodes()といった関数を、適切なnodeを記述するdormant_node_info構造体を探すために使用します。

 そのnodeを使い終わり、その動作を停止させて接続を解除したら、Media Serverにそのことを知らせるために必ずReleaseNode()を呼び出して下さい。これにより、Media Serverは、それをまだ使用しているアプリケーションの数を元にして、nodeのadd-onがアンロードできるかどうか追跡することができます。

 これら2つの関数の違いは、2つ目の形式ではnodeのインスタンスがどうやって作成されるかを制御するフラグが指定できることです。B_FLAVOR_IS_GLOBALフラグは、Media Add-on Serverのメモリ空間にnodeのインスタンスを生成し、一方B_FLAVOR_IS_LOCALフラグはアプリケーションのメモリにnodeのインスタンスを生成します。B_FLAVOR_IS_LOCALを使用すると、nodeがクラッシュした場合に生じる動作の異常から、他のアプリケーション—Media Serverはいうまでもなく—を保護します。可能な限り、ローカルにnodeのインスタンスを生成して下さい。B_FLAVOR_IS_GLOBALは、アプリケーションが終了した後にもnodeをそのまま維持する必要がある場合のみ使用して下さい

RETURN CODES

B_OK. nodeのインスタンスを生成する際に、エラーは生じなかった。


MakeTimeSourceFor() see GetTimeSource()


MediaFlags()

                                                         
  

static ssize_t MediaFlags(media_flags flag, void *buffer, size_t bufferSize)

 Media Serverに、特定のフィーチャーと能力をサポートしているか問い合わせます。

 指定されたbufferに、指定されたフラグの値を示すデータが収められます。もし(bufferSizeで示されるように)bufferが小さすぎた場合は、結果データの最初からbufferSizeバイトだけがバッファに保存されますが、エラーは生じません。

Constant Description
B_MEDIA_FLAGS_VERSION Media Kitのバージョンをint32型の値で返します。

 もし結果が負の数であれば、エラーが生じたか、Media Serverが動作していないということです。


NodeIDFor()

                                                         
  

media_node_id NodeIDFor(port_id sourceOrDestinationPort)

 sourceまたはdestinationのポートを与えると、この関数はそれに一致するnodeのID番号を返します。


PrerollNode()

                                                         
  

status_t PrerollNode(const media_node &node)

 PrerollNode()を呼び出すと、指定されたnodeにprerollメッセージが送られます。このとき、nodeのPreroll()フック関数が呼び出されます。このフック関数が返ると、PrerollNode()も返ります。プリロールされたnodeは、StartNode()の呼び出しに対して非常に素早く反応しなければなりません。なぜなら、Preroll()フックによって、時間消費のセットアップ動作がすでに終わっているからです。

 アプリケーションにとってStartNode()を呼び出す前にPrerollNode()を呼ぶことは強制ではありませんが、そうするよう推奨されます。そうすることによって一旦nodeが開始されたリアルタイム動作が改善されるだろうからです。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. モードの変更要求を送信する際に、エラーは生じなかった。


RegisterNode() , UnregisterNode()

                                                         
  

status_t RegisterNode(BMediaNode *node)

status_t UnregisterNode(BMediaNode *node)

 RegisterNode()は、media rosterにBMediaNodeから派生したクラスのオブジェクトを登録し、それにnode_idを割り当てます。BMediaNodeから派生したオブジェクトを完全にコンストラクトし、Media Serverでnodeと他の関係するものを接続するよう企図する前に、この関数を一度呼び出して下さい。

 RegisterNode()は、add-onからインスタンスを生成されたnodeに対し、自動的に呼び出されます。しかしアプリケーションは、node自身を生成した任意のnodeに対して、この関数を呼び出さなければなりません。

 もしBMediaNodeのサブクラスを独自に生成した場合は、コンストラクタが返る前に、コンストラクタ中でそれ自身のためにRegisterNode()を呼び出すことができます(コンストラクタが行う最後の動作である必要があります)。

 UnregisterNode()は、nodeをMedia Serverから登録削除を行います。これは自動的にBMediaNodeのデストラクタから呼ばれますが、nodeの実装や状況に応じて、nodeのインスタンスを削除する前のどこかで呼び出す方が便利かも知れません。

 これらの関数は、一般的にユーザが自分自身のnodeクラスを作成した場合にのみ使用されます。

RETURN CODES

B_OK. seek要求を送る際にエラーは生じなかった。


ReleaseNode()

                                                         
  

status_t ReleaseNode(const media_node &node)

 指定されたnodeを開放します。このnodeは、以前にInstantiateDormantNode()GetNodeFor()またはデフォルトのnode関数(GetVideoNode()GetAudioMixer()といった)を使用して得たものです。

RETURN CODES

B_OK. nodeを開放する際にエラーは生じなかった。


RollNode()

                                                         
  

status_t RollNode(const media_node &node, bigtime_t startPerformanceTime,
      bigtime_t stopPerformanceTime,
      bigtime_t atMediaTime = -B_INFINITE_TIMEOUT)

 与えられたnodeの開始と停止を自動的にキューに入れます。nodeはstartPerformanceTimeで示されるperformance timeに演奏を開始し、stopPerformanceTimeで示されるperformance timeに演奏を停止します。

 もし引数atMediaTimeが与えられれば、そのmedia timeへのseekがキューに追加されます。

 この関数は、特にオフラインレンダリングの場合に便利です(B_OFFLINE実行モード)。これによって、偶然に大きく外れることなく、確実な時間の範囲を計算することができます。もしStart()及びStop()を用いて開始と停止をキューに入れる場合は、Stop()呼び出しが起こる前に、要求された停止時刻がすでに計算されているでしょう。RollNode()は、この問題を回避します。

RETURN CODES

B_OK. エラーなし。


Roster() , CurrentRoster()

                                                         
  

static BMediaRoster *Roster(status_t *outError = NULL)

static BMediaRoster *CurrentRoster(void)

 Roster()は、デフォルトのBMediaRosterのインスタンスへのポインタを返すか、あるいはもしまだ存在していなければ、BMediaRosterのインスタンスを生成した後にそのポインタを返します。もしまだrosterが存在していない場合にrosterを作りだしたくなければ、CurrentRoster()関数を使用して下さい(この関数は、rosterがなければNULLを返します)。

 CurrentRoster()はmedia rosterを作成しないため、少なくとも一度はアプリケーション中でrosterを作成するためにRoster()を使用しなければなりません。

 これらの静的なメンバ関数は、明示的なスコープによって呼び出されますが、参照されない状態では決して呼び出されません。これは他の全てのmedia roster関数呼び出し時に経由するBMediaRosterを得る方法です。例えば :

   BMediaRoster *r = BMediaRoster::Roster();
   status_t err = r->GetFreeOutputsFor(some_node, some_array, 3, &n);

 関数が返る際、outErrorは、もしデフォルトのBMediaRosterがうまく返された場合はB_OKに設定され、また(例えばMedia Serverが動作していなかった場合など)なにかがうまくいかなければ負のエラーコードに設定されます。もしoutErrorNULLであれば、エラーコードは返されません。

 いずれの場合でも、エラーが生じればRoster()NULLを返します。


SeekNode()

                                                         
  

status_t SeekNode(const media_node &node, bigtime_t newMediaTime,
      bigtime_t atPerformanceTime = 0)

 指定されたnodeに対し、一旦 performance time atPerformanceTimeに到達したら、演奏位置を media time newMediaTimeに変更するよう要求を送ります。

 もしnodeが動作していなければ、seek要求は即座に処理され、引数atPerformanceTimeは無視されます。

 この関数から返されるエラーは、要求がうまく送信されたか否かのみを示します。nodeは、seek処理を実行しようとして、後ほどトラブルに巻き込まれるでしょう。

 
 もしnodeがtime sourceであり、そのtime sourceで(全ての従属するnodeを探すのに)nodeのaspectを操作しようとするなら、代りにSeekTimeSource()を呼び出して下さい。


RETURN CODES

B_OK. seek要求を送信した際に、エラーは生じなかった。

StartNode(), StopNode()をご覧下さい。


SeekTimeSource()

                                                         
  

status_t SeekTimeSource(const media_node &timeSource,
      bigtime_t newPerformanceTime,
      bigtime_t atRealTime)

 指定されたtimeSourceに対して、一旦performance timeがatRealTimeに到達したら、それに従属するnodeに出力するperformance timeを時刻newPerformanceTimeに変更するように要求を送ります。

 もしtimeSourceが動作していなければ、seek要求は即座に処理され、引数atRealTimeは無視されます。

 この関数によって返されるエラーは、要求がうまく送信されたか否かのみを示します。nodeは後ほど、seek処理を実行しようとして問題に巻き込まれるでしょう。

RETURN CODES

B_OK. seek要求を送信する際、エラーが生じなかった。

StartTimeSource(), StopTimeSource()もご覧下さい。


SetAudioInput() , SetVideoInput()

                                                         
  

status_t SetAudioInput(const media_node &defaultNode)

status_t SetAudioInput(const dormant_node_info &defaultNodeInfo)

status_t SetVideoInput(const media_node &defaultNode)

status_t SetVideoInput(const dormant_node_info &defaultNodeInfo)

 これらの関数は、優先権のあるnodeにオーディオ及びビデオの入力をセットします。もし指定されたnodeがシステムのデフォルトとしての能力がなければ、エラーが返されます(例えば、アプリケーションによって定義されたnodeがシステムのデフォルト—Media Kitのadd-onによって定義されたnodeの場合のみ、システムのデフォルトでありえます)。

 
一般的に、BeOSのオーディオまたはビデオ初期設定パネルの機能を再実装するソフトウェアを書いているのでもないかぎり、これらの関数は呼び出さないで下さい。


RETURN CODES

B_OK. デフォルトの入力nodeを設定する際にエラーは生じなかった。


SetAudioOutput() , SetVideoOutput()

                                                         
  

status_t SetAudioOutput(const media_node &defaultNode)

status_t SetAudioOutput(const dormant_node_info &defaultNodeInfo)

status_t SetAudioOutput(const media_input &inputToOutput)

status_t SetVideoOutput(const media_node &defaultNode)

status_t SetVideoOutput(const dormant_node_info &defaultNodeInfo)

 これらの関数は、オーディオ及びビデオの出力のために優先権のあるnodeをセットします。もし指定されたnodeにシステムのデフォルトとしての能力がなければ、エラーが返されます(例えば、アプリケーションによって定義されたnodeはシステムのデフォルトになれません—Media Kit add-onによって定義されたnodeのみが、システムのデフォルトになれます)。

 
一般的に、BeOSのオーディオまたはビデオ初期設定パネルの機能を再実装するソフトウェアを書いているのでもないかぎり、これらの関数は呼び出さないで下さい。


RETURN CODES

B_OK. デフォルト入力nodeを設定する際にエラーは生じなかった。


SetProducerRate()

                                                         
  

status_t SetProducerRate(const media_node &node,
      int32 numerator, int32 demominator)

 この関数は、producerに対して指定された要素でデータレートの再サンプリングを行わせるために呼び出されます。値 1 を指定すると(即ちnumerator/denominator = 1 の場合)、データがnodeから来たものと同じ再生レートで出力されることを示します。データのフォーマットは変更されません。

 
nodeは、データレートを制御するために、これらの機構をサポートするよう要求されていません。したがって、この呼び出しは無効です。


RETURN CODES

B_OK. エラーなし。

BBufferProducer::SetPlayRate()もご覧下さい。


SetProducerRunModeDelay()

                                                         
  

status_t SetProducerRunModeDelay(const media_node &node,
      bigtime_t delay,
      BMediaNode::run_mode mode = B_RECORDING)

 実行モードを与えられたproducer nodeをmodeにします。同様に、producerによって送られたバッファそれぞれに対して、指定されたdelayを付加します。この関数はB_RECORDINGモードのためにだけ呼び出して下さい。この関数は、レコーディングモードのnodeとそうでないnodeを接続するときに、その時間補正のために供給されます。

RETURN CODES

B_OK. エラーなし。


SetRealtimeFlags() see GetRealtimeFlags()


SetRefFor() , GetRefFor()

                                                         
  

status_t SetRefFor(const media_node &fileInterface,
      entry_ref &file,
      bool createAndTruncate,
      bigtime_t *outDuration)

status_t GetRefFor(const media_node &fileInterface,
      entry_ref *outFile,
      BMimeType *outMimeType = NULL)

 SetRefFor()は、BFileInterfaceであるfileInterfaceに対し、fileによって指定されたentry_refの示すファイル上で作業するように伝えます。もしcreateAndTruncatetrueであれば、その参照を持つ過去のファイルは削除され、ファイルは新しい出力に対して準備されるでしょう。もしcreateAndTruncatefalseであれば、関数が返る際、outDurationにはファイルから見つけた演奏データの長さが収められます。

 GetRefFor()は、指定されたfileInterfacenodeが作業しているファイルへの参照を、指定されたentry_ref型のoutFileに収めます。もしoutMimeTypeNULLではなく、エラーが生じなければ、それにはファイルタイプを記述するBMimeTypeオブジェクトが収められます。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. エラーなし。


SetRunModeNode()

                                                         
  

status_t SetRunModeNode(const media_node &node,
      BMediaNode::run_mode newMode)

 指定されたnodeに対し、リアルタイム処理の途中に処理が遅れたといった状況を扱うために、nodeの方針を変更するよう要求を送ります。

 この関数から返されたエラーは、要求がうまく送信されたか否かのみを示します。

RETURN CODES

B_OK. mode設定の要求を送信する際にエラーが生じなかった。


SetTimeSourceFor()

                                                         
  

status_t SetTimeSourceFor(media_node_id node,
      media_node_id timeSource)

 指定されたnodeのタイミングをtimeSourceに従属させます。一旦これが実行されると、nodeはtimeSourceからの時間経過の意志(notion)を受け取ります。したがって、timeSourceが停止するとnodeは停止しますし、他の動作も同様となります。

 
デフォルトでは、nodeはsystem time sourceに従属しているため、nodeを他のtime sourceに従属させる必要がある場合のみ、この関数を呼び出す必要があります。


 nodeにとって、メディア再生に於けるミスの原因がなく、nodeがtimeSourceの意志(notion)に忠実であったとしても、予防策は依然として必要です。例えば、もしサウンドカードのnodeにtimeSourceから流れてくるDACがあったとして、それはサンプリング周波数を少し変化させたり、時にはバッファを脱落させたり複製したりして問題を修正しようとします。これは、マスターのtime sourceとして—system time sourceよりも—優先的なtime sourceを使用すべきであるという理由です。優先的なtime sourceは通常、メディア出力を提供するのに使用されるDACから直接派生します。

RETURN CODES

B_OK. エラーなし。


SetVideoInput() see SetAudioInput()


SetVideoOutput() see SetAudioOutput()


SniffRef() , SniffRefFor()

                                                         
  

status_t SniffRef(const entry_ref &file,
      uint64 requireNodeKinds,
      dormant_node_info *outNode,
      BMimeType outMimeType = NULL)

status_t SniffRefFor(const media_node &fileInterface,
      const entry_ref &file,
      BMimeType outMimeType,
      float *outCapability)

 SniffRef()は、全てのBMediaAddOnのインスタンスに対して、それがfileを識別できることを表すrequireNodeKinds制限を満足するかどうか問い合わせます。引数requireNodeKindsは、node_kind定数から合成されるフラグを含まなければなりません。

 最も大きなoutCapability値を返すnodeが選択され、outNodeにその参照が収められます。ファイルのMIMEタイプはoutMimeTypeに収められます。

 より簡単に表現すると : SniffRef()は、指定されたファイルのメディアデータを最もうまく扱うことのできるnodeを返します。

 一方、SniffRefFor()は、指定されたfileInterface nodeに対し、fileを調べるよう問い合わせます。もしnodeがファイルを認識できれば、ファイルのMIMEタイプがoutMimeTypeバッファに保存され、nodeのファイルを扱う能力がoutCapabilityに返されます。

 もしnodeがfileを認識できなければ、エラーが返されます。もしnodeがファイルフォーマットを認識できるが、そのファイル中に認識できるデータを見つけられなければ、outCapabilityが0.0に設定され、エラーは返されません。

 いずれの場合でも、返されたoutCapability値が高ければ高いほど、nodeがより適切にファイル中のメディアデータを取り扱えることになります。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. mode設定要求の送信時に、エラーは生じなかった。


SniffRefFor() see SniffRef()


StartControlPanel()

                                                         
  

status_t StartControlPanel(const media_node node,
      BMessenger *outMessenger = NULL)

 指定されたnodeに対して、アプリケーションの外で開始されるカスタムの制御パネルを開始するよう伝えます。ユーザが制御パネルを閉じてしまったら、nodeによって出力されているデータのフォーマットを再度交渉するなどして、nodeに対して行うことのできる変更を間接的に検出するほかに、それを伝える方法はありません。

 もしBMessengerStartControlPanel()への入力として提供されるなら、この関数は、制御パネルとの交信に使用できるBMessengerをoutMessengerに入れて返します。

 
これらの関数は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. 制御パネルを開始する際にエラーは生じなかった。


StartNode() , StopNode()

                                                         
  

status_t StartNode(const media_node &node, bigtime_t atPerformanceTime)

status_t StopNode(const media_node &node, bigtime_t atPerformanceTime,
      bool immediate = false)

 StartNode()は、指定されたnodeに対して、nodeのtime sourceに於て引数atPerformanceTimeで指定されたperformance timeにストリーミングデータを開始するよう要求を送ります。

 デフォルトでは、nodeは作成された時点で停止した状態であるため、なにかが起こる前に一旦nodeへの参照を得たらStartNode()を呼び出す必要があります。すでに動作中のnodeを開始しても、影響はありません。

 StopNode()は、nodeに対して、nodeのtime sourceを基準として指定されたperformance time atPerformanceTimeに到達したらストリーミングデータを一旦停止するよう要求を送ります。すでに停止しているnodeを停止しても、影響はありません。もしimmediatetrueであれば、nodeはすぐさま停止するよう指示され、atPerformanceTimeは無視されます。もしimmediatefalseであれば、nodeは指定されたperformance timeに停止します。

 いずれの場合も、要求された変化はatPerformanceTimeで指定された時間に生じます。

 
もしnodeがtime sourceであり、nodeのtime sourceであるという側面(従属する全てのnodeを開始したり停止したりする)から操作を行うならば、代りにSeekTimeSource()を呼び出して下さい。


 これらの関すから返されるエラーは、要求がうまく送信されたか否かのみを示します。後ほどnodeがメディアの開始や停止を行おうとした際に問題が生じるかも知れませんが、これらの関数の結果に基づいてそれを知ることはできません。

 
StopNode()は、もしnodeの制御スレッド中または制御スレッドがブロックされている間に呼び出されると、デッドロックするでしょう。


RETURN CODES

B_OK. 開始または停止要求を送信する際にエラーが生じなかった。

これもご覧下さい : SeekNode()


StartTimeSource() , StopTimeSource()

                                                         
  

status_t StartTimeSource(const media_node &timeSource, bigtime_t atRealTime)

status_t StopTimeSource(const media_node &timeSource, bigtime_t atRealTime,
      bool immediate = false)

 StartTimeSource()は、指定されたtimeSourceに対して、引数atRealTimeによって指定されたreal timeに動作開始の要求を送ります。

 StopTimeSource()は、指定されたtimeSourceに対して、指定されたreal time atRealTimeに到達したら一旦停止するよう要求を送ります。すでに停止しているtime sourceを停止しても影響はありません。もしimmediatetrueならば、time sourceはすぐさま停止するように指示され、引数atRealTimeは無視されます。もしimmediatefalseであれば、time sourceは指定されたreal timeに停止します。

 いずれの場合も、要求された変化は、指定されたatRealTimeに発生します。

 これらの関数から返されるエラーは、要求がうまく送信されたか否かを示すのみのものです。後ほどnodeには開始・停止を行おうとした際に問題が発生する可能性がありますが、これらの関数の結果に基づいてそれを知ることはできません。

RETURN CODES

B_OK. 開始または停止要求を送信する際にエラーが生じなかった。

これもご覧下さい : SeekTimeSource()


StartWatching() , StopWatching()

                                                         
  

status_t StartWatching(const BMessenger &notifyHandler)

status_t StartWatching(const BMessenger &notifyHandler,
      int32 notificationType)

status_t StartWatching(const BMessenger &notifyHandler,
      const media_node &node,
      int32 notificationType)

status_t StopWatching(const BMessenger &notifyHandler)

status_t StopWatching(const BMessenger &notifyHandler,
      int32 notificationType)

status_t StopWatching(const BMessenger &notifyHandler,
      const media_node &node,
      int32 notificationType)

 StartWatching()は、指定されたBHandlerまたはBLooperを、Media Serverからの通知メッセージの受け手として登録します。StopWatching() はこの登録をキャンセルするため、その後の通知は送られません。

 もし特定の通知型にしか興味がないのなら、引数notificationTypeでコードを指定することができます。もし通知型を指定したくないなら、B_MEDIA_WILDCARDが前提となります。これは全ての通知型に一致します。また指定されたnodeを観察することもできます。もしnodeを指定したくなければ、全てのnodeへの通知を受け取ることができます。

 特定のイベントが発生した時、例えばnodeの生成や削除、接続の生成や切断などといったイベントは、登録されたBHandlerやBLooperに送られます。

 受け取ることのできる通知及び対応するメッセージのフォーマットのリストについては"Notification Messages"をご覧下さい。

 
Media Serverは、StopWatching()の明示的な呼び出しなしにはBHandler及びBLooperへの通知を自動的にキャンセルしないにも関わらず、この検出は非常に高価で、明らかにメディアシステムに割り込みます。したがって、BHandlerまたはBLooperに対してnodeの削除を許可する前に、常にStopWatching()を呼び出して下さい。


RETURN CODES

B_OK. nodeを複製する際にエラーなし。


StopNode() see StartNode()


StopWatching() see StartWatching()


SyncToNode()

                                                         
  

status_t SyncNode(const media_node &node, bigtime_t atPerformanceTime,
      bigtime_t timeout = B_INFINITE_TIMEOUT)

 もし与えられたnodeが指定されたperformance timeに到達したことを検出したいなら、SyncToNode()を呼び出すことで可能になります。nodeでモニタリングしたいnodeを指定し、atPerformanceTimeで通知してほしい時間を指定します。オプションとして、timeoutを指定することができます。もしtimeoutマイクロ秒以内に同期が生じなければ、要求は時間切れとなります。

 この関数は、指定されたperformance timeに到達するか、同期動作の時間切れが生じるまで戻りません。

RETURN CODES

B_OK. すべてよし。


Constants


connect_flags

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

Constant Description
B_CONNECT_MUTED 接続は生成時に消音(ミュート)される


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