|
BMediaAddOnクラスの関数が、典型的にはMedia Kit（及びadd-on自身の内部）からのみ呼び出されるということに留意するのは重要です。これらの関数は、クライアントアプリケーションによって呼び出されません。
|
| The Media Kit Table of Contents | The Media Kit Index |
Derived from: none
Declared in: be/media/MediaAddOn.h
Library: libmedia.so
Allocation: Constructor only
BMediaAddOnから派生するオブジェクトは、ディスクファイルに生息する実行可能なプログラムを記述し、必要になった際にMedia Serverによってロードされます。BMediaAddOnはMedia Serverに呼び出されると、Media Serverに対して自分がどんな種類のnodeを生成し、実際にそれらのnodeを扱うことができるかを伝えます。
|
与えられたnodeは、望むだけの数のメディア種（media kind）とフォーマットをサポートできます（もし異ったメディアタイプを幅広く数多くサポートしすぎたとしたら、そのadd-onは維持しがたくなるでしょう。しかしそれは全く別の話です）。例えば、ビデオをサポートするnodeは、AVI、QuickTime及びMPEG-2の入力をサポートしますが、出力はAVIだけが可能です。これはMedia Kitにとって知る必要のある情報です。この理由によって、BMediaAddOnはそれがサポートするメディアのflavorsに関する情報を提供する必要があります。
これは、flavor_info構造体よって行われます :
struct flavor_info {
char *name;
char *info;
uint64 kinds;
uint32 flavor_flags;
int32 internal_id;
int32 possible_count;
int32 in_format_count;
uint32 in_format_flags;
const media_format *in_formats;
int32 out_format_count;
uint32 out_format_flags;
const media_format *out_formats;
uint32 _reserved_[16];
private:
flavor_info & operator=(const flavor_info &other);
};
name及びinfoフィールドは、人間に読むことのできる名前、及びflavorに関する情報を提供します。
kindsフィールドは、nodeが一致する、関連する全てのkindを示します。これはビットのフィールドであり、一つ以上のフラグが関連できます。"node_kind"の181ページもご覧下さい。
flavor_flagsフィールドは、flavorに関する追加情報を提供するフラグを内包します。
| Constant | Description |
|---|---|
| B_FLAVOR_IS_GLOBAL | flavorは、強制的にMedia Add-on Serverに入れられ、そのインスタンスはひとつだけ存在することになる。 |
| B_FLAVOR_IS_LOCAL | flavorは、強制的にロードしたアプリケーションに入れられ、そのインスタンスは多数存在する。 |
もしどちらのフラグも指定されなければ、Media Kitがそのflavorに何を行うか決定します。
internal_idは、あなたのadd-onがflavorの識別に使用することのできる内部的なID番号です。そのflavorは、このID番号を使用するMedia Kitによって要求されるでしょう。
possible_countフィールドは、同時にあなたのnodeのインスタンスが存在しうる最大数をMedia Kitに対して指定します。例えば、もしあなたのnodeが特定のサウンドカードに対するサポートを提供するなら、この値は現在コンピュータにインストールされている（あなたのサポートする）カードの数と等しくなります。
in_format_countはそのflavorがサポートする入力の数を指定し、in_formatsはそのflavorにサポートされる全ての入力のリストです。
in_format_flagsは、flavorの入力に関する情報フラグを提供します。このフィールドに対しては、まだなんの値も定義されていません。必ず0をセットして下さい。
out_format_countはflavorがサポートする出力フォーマットの数を指定し、out_formatsはflavorによってサポートされる全ての出力フォーマットのリストです。
out_format_flagsは、flavorの出力に関する情報フラグを提供します。このフィールドに対しては、まだなんの値も定義されていません。必ず0をセットして下さい。
もしあなたのnodeがサウンドカードのような物理的な入力であれば、nodeのkindsフィールドは、その中にセットされたフラグにB_PHYSICAL_INPUTも含んでいなければなりません。同様に、もしあなたのnodeが物理的な出力であるか、またはシステムミキサーであれば、B_PHYSICAL_OUTPUTまたはB_SYSTEM_MIXERを含まなければなりません。
あなたのnodeのコンストラクタは、これらのkindフラグを追加するためにAddNodeKind()も呼び出さなければなりません。基底クラスは、B_BUFFER_CONSUMER、B_BUFFER_PRODUCER等を追加するのみです。nodeが物理的入力、物理的出力またはシステムミキサーであると表現することを示すフラグは、自動的に追加されません。例えば、音声のデジタル化を行うnodeのコンストラクタは、下記のような形を取るでしょう :
MyBufferProducer::MyBufferProducer(const char *name) :
BMediaNode(name),
BBufferProducer() {
AddNodeKind(B_PHYSICAL_INPUT);
/* constructor stuff goes here */
}
|
これは、BMediaAddOnのコンストラクタです。派生クラスは、コンストラクタ中で必要な初期化を行い、media add-onのプロトコルに適切に応じるために必要な全ての動作を扱わなければなりません。
image_idは、add-onがロードされたadd-onイメージを識別します。make_media_addon()関数は、必ず渡されたイメージIDを保存し、それをBMediaAddOnコンストラクタに渡さなければなりません。そうしなければ、Media Kitはあなたに不満を持つでしょう。
|
BMediaAddOnは、決してあなた自身で削除しないで下さい。Media Serverは、add-onが必要でなくなった時に削除を行うでしょう。しかし、もしあなたがmedia add-onを実装しているなら、ここはあなたが領域確保したメモリを破棄するのによい場所です。
|
もしWantsAutoStart()がtrueを返すなら、あなたのadd-onがロードされる際にAutoStart()が繰り返し呼び出されるでしょう。
AutoStart()関数は、各々のAutoStart()呼び出しに対して一度ずつ、リンクのためにnodeのインスタンスを生成するよう実装して下さい。AutoStart()が呼び出されるたびに、indexは前回の呼び出しより大きな値になります。新しいnodeを生成した後、outNodeにそのポインタを保存し、outInternalIDにそのnodeによって表現されるflavorの内部的IDをセットして下さい。
この関数が返る前に、もしさらに開始すべきnodeがあればoutHasMoreにtrueを、そうでなければfalseをセットして下さい。
もし有効なnodeを返すなら、B_OKを返して下さい。もしもう開始すべきnodeがなければ、B_BAD_INDEXを返して下さい。もし指定されたindexは機能しないが、他に開始すべきnodeがあるならば、B_ADDON_FAILEDを返して下さい。
|
add-onが扱うことのできるflavorの数を返すために、このフック関数を実装して下さい。
|
与えられたnodeを指定されたメッセージ中に構造を記述する方法に関する情報を保存するように、この関数を実装して下さい。これによって、後でInstantiateNodeFor()を使用してnodeを再構成できるよう、nodeの構造をディスクに保存することができるようになります。
どのような接続がこのnodeを経路として使用していたかに関する情報を保存するのは、意味がないということに留意して下さい。なぜなら、他のnodeはこのnodeが再構成される際に、おそらく存在していないからです。接続をどう再構成するかはアプリケーション次第です。
もし構成情報がエラーなしにconfigに格納されたら、B_OKを返して下さい。そうでなければ、適切なエラーコードを返して下さい。
|
もしあなたのadd-onがファイルからのメディアデータの読み込みまたは書き込みのいずれかが可能なnodeを提供するなら、読み込み及び書き込みの可能なmedia_file_formatsを記述するためにこの関数を実装して下さい。
関数の呼び出し時、引数flavorIDは、情報を返すべきflavorがどれかを示します。対応するflavorが書込むことのできるファイルフォーマットのリストで配列outWritableFormatsを満たし、対応するflovorが読み込むことのできるファイルフォーマットのリストで配列outReadableFormatsを満たします。引数inWriteItems及びinReadItemsは、それぞれの配列に保存されている項目数を示します。
|
関数が返る際、outWriteItemsに、書込むことのできるファイルフォーマットの数をセットして下さい—例えinWriteItemsより大きくてもです。これによって、関数の呼び出し側で配列の大きさを変更し、完全なリストを得るために関数を再度呼び出すことができます。同様に、outReadItemsには、読み込むことのできるファイルフォーマットの数がセットされます。
引数reservedは現在使用されていないため、常にNULLを指定して下さい。
|
もしエラーが生じたら、適切なエラーコードを返して下さい。そうでなければ、B_OKを返して下さい。
|
あなたのadd-onにサポートされたひとつのflavorを記述する静的なflavor_info構造体をoutInfoポインタに保存するために、GetFlavorAt()を実装して下さい。outInfoポインタによって示されるデータは、GetFlavorAt()が返った後にMedia Kitによって複製されるでしょう。例えば、もしadd-onがflavorをひとつだけサポートしているなら :
flavor_info flavorInfo;
status_t MyMediaAddOn::GetFlavorAt(int32 n, const flavor_info **out_info) {
if (n != 0) {
return B_ERROR;
}
flavorInfo->internal_id = n;
flavorInfo->name = strdup("My Media Node");
flavorInfo->info = strdup("This node receives video from spy cameras at area pizza parlors and determines which one is the least busy.");
flavorInfo->kinds = B_BUFFER_CONSUMER | B_PHYSICAL_OUTPUT;
flavorInfo->flavor_flags = 0;
flavorInfo->possible_count = 0;
// Set up the list of input formats. We only support
// raw video input.
flavorInfo->in_format_count = 1;
media_format *aFormat = new media_format;
aFormat->type = B_MEDIA_RAW_VIDEO;
aFormat->u.raw_video = media_raw_video_format::wildcard;
flavorInfo->in_formats = aFormat;
// We don>t output.
flavorInfo->out_format_count = 0;
flavorInfo->out_formats = 0;
// And set up the result pointer
*out_info = flavorInfo;
return B_OK;
}
|
もしflavorNumがCountFlavors() - 1 より大きければ（言い換えれば、もし要求された数があなたのサポートするflavorの数より大きければ）、B_ERRORを返して下さい。そうでなければB_OKを返すか、エラーが生じれば適切なエラーコードを返して下さい。
|
BMediaAddOnのコンストラクタで指定された、add-onのイメージIDを返します。
make_media_addon()関数は、必ず渡されたイメージIDを保存し、それをBMediaAddOnコンストラクタに渡さなければなりません。そうしなければ、Media Kitはあなたに不満を持つでしょう。
|
outFailureTextに、add-onがMedia Serverによって要求された最後の処理に失敗した理由を説明するメッセージを内包する静的なテキストバッファのポインタをセットするよう、このフック関数を実装して下さい。
outFailureTextポインタによって示されるバッファは、add-onが再ロードされるか或いは新たにInitCheck()が呼び出されるまで、削除されるべきではありません。
その処理から返される実際の結果コードも同様に返されます。もし全く問題が生じなければ、B_OKが返されます。
|
（おそらく前回GetFlavorAt()呼び出しによって返された情報の複製である）infoに情報が与えられたら、infoのinternal_idフィールドによって参照されるnodeクラスの新しいオブジェクトのインスタンスを生成し、そのnodeへのポインタを返して下さい。
configメッセージは、前回同じflavorのnodeのインスタンスによって保存された情報を内包し、可能なら新しいnodeを構築するために使用されます。もしそのメッセージに全く興味のあるフィールドがなくても、configは決してNULLにはなりません。
nodeの構築を行わない場合、この関数を最も単純に実装するには、下記のようにして下さい :
BMediaNode *BMyConsumerAddOn::InstantiateNodeFor(const flavor_info *info,
BMessage *config, status_t *outError) {
return new MyConsumerNode((const char *) "My Consumer Node");
}
もし新しいインスタンスが生成できなければ、outErrorに適切なエラーコードをセットしてNULLを返して下さい。そうでなければ、outErrorにB_OKをセットして下さい。
|
もしadd-onがBFileInterfaceをサポートしているなら、SniffRef()を実装してもいいでしょう。指定されたfileが与えられると、ファイルを検証してoutMimeTypeにそのファイルのMIMEタイプを記述します。
加えて、mimeTypeによって指定されるMIMEタイプのデータを持つファイルをどの程度うまく扱えるか報告するために、SniffType()を実装することができます。
|
SniffTypeKind()は、検索をinKindsによって示されるkindに限定します。これによって呼び出し側は、例えばconsumerとproducerのどちらを探しているかを指示することができます。
どのケースについても、outQualityにadd-onがファイルのデータを解釈できる品質のレベル（0.0はデータを全く扱うことができず、1.0はそれを完全に扱うことができることを意味する）を表現する値を保存して下さい。またoutInternalIDには、データを扱うflavorの内部的IDを保存して下さい。
|
もし問題なくnodeを識別できればB_OKを返し、そうでなければ適切なエラーコードを返して下さい。
|
このフック関数は、もしひとつ以上のあなたの（ロードされる際、後にアプリケーションからの明示的なインスタンス生成を待つ代りに、自動的なインスタンス生成を望む）add-onにサポートされるflavorがあればtrueを返すよう実装して下さい。そうでなければ、falseを返して下さい。
|
make_media_addon()は、add-onが広域で自分自身を使用できるように実装する必要のある、グローバルなC関数です。これは、Media Serverがadd-onをロードする際に呼び出され、適切にフック関数を実装されたBMediaAddOnの派生クラスのインスタンスを返さなければなりません。
引数addonIDは、add-onのイメージIDです。make_media_addon()関数は、必ず渡されたイメージIDを保存し、それをBMediaAddOnコンストラクタに渡さなければなりません。そうしなければ、Media Kitはあなたに不満を持つでしょう。
この関数は、極めて単純に実装することができます。
BMediaAddOn *make_media_addon(image_id myImage) {
return new MyConsumerAddOn(myImage);
}
単純に（このケースではMyConsumerAddOnの）add-onオブジェクトのインスタンスを生成し、それを返します。
Declared in: <be/media/MediaAddOn.h>
struct dormant_flavor_info : public flavor_info, public BFlattenable {
dormant_node_info();
virtual ~dormant_node_info();
dormant_flavor_info(const dormant_flavor_info &);
dormant_flavor_info& operator=(const dormant_flavor_info &);
dormant_flavor_info& operator=(const flavor_info &);
dormant_node_info node_info;
void set_name(const char *in_name);
void set_info(const char *in_info);
void add_in_format(const media_format &in_format);
void add_out_format(const media_format &out_format);
virtual bool IsFixedSize() const;
virtual type_code TypeCode() const;
virtual ssize_t FlattenedSize() const;
virtual status_t Flatten(void *buffer, ssize_t size) const;
virtual status_t Unflatten(type_code c, const void *buf, ssize_t size);
private:
void assign_atoms(const flavor_info &that);
media_addon_id addon;
int32 flavor_id;
char name[B_MEDIA_NAME_LENGTH];
private:
char reserved[128];
};
dormant_flavor_info構造体は、休止中のnodeに於けるflavorを記述します。
Declared in: <be/media/MediaAddOn.h>
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];
};
dormant_node_info構造体は、add-onに存在するがメモリ上には存在しないnodeを記述します。例えば、nodeのインスタンスを生成するためにBMediaRoster::InstantiateDormantNode()を発行する際、これを使用するでしょう。
addonフィールドは、nodeが存在するmedia add-onのID番号を示し、flavor_idは、nodeが表現するのがどのflavorかを示す内部的なflavor IDとなります。nameフィールドは、nodeの名前です。
Declared in: <be/media/MediaAddOn.h>
struct flavor_info {
char *name;
char *info;
uint64 kinds;
uint32 flavor_flags;
int32 internal_id;
int32 possible_count;
int32 in_format_count;
uint32 in_format_flags;
const media_format *in_formats;
int32 out_format_count;
uint32 out_format_flags;
const media_format *out_formats;
uint32 _reserved_[16];
private:
flavor_info & operator=(const flavor_info &other);
};
name及びinfoフィールドは、人間に判読できる名前とflavorに関する情報を提供します。
kindsフィールドには、nodeのkindがセットされます。"node_kind"の181ページ目をご覧下さい。
flavor_flagsフィールドは、flavorに関する付加的な情報を提供するフラグを内包します。
| Constant | Description |
|---|---|
| B_FLAVOR_IS_GLOBAL | flavorはMedia Add-on Serverに取り込まれ、そのインスタンスはひとつだけ存在することになります。 |
| B_FLAVOR_IS_LOCAL | flavorは読み込み側のアプリケーションに取り込まれ、そのインスタンスは多数存在することになります。 |
もしいずれのフラグも指定されなければ、Media Kitがflavorをどう扱うか決定します。
internal_idは、add-onがflavorを識別するための内部的なIDです。flavorはこのID番号を使用するMedia Kitによって要求されます。
possible_countフィールドは、nodeのインスタンスが同時に存在することのできる最大の数をMedia Kitに対して指定します。例えば、もしnodeが特定のサウンドカードへのサポートを提供するなら、この値はコンピュータに現在インストールされている（あなたのnodeがサポートする）サウンドカードの数に等しくなります。
in_format_countはflavorがサポートする入力フォーマットの数を指定し、in_formatsはflavorによってサポートされる入力フォーマット全てのリストです。
in_format_flagsは、flavorの入力に関する情報フラグを提供します。現在のところフラグは全く定義されていないため、このフィールドには0をセットして下さい。
out_format_countはflavorのサポートする出力フォーマットの数を指定し、out_formatsはflavorがサポートする出力フォーマット全てのリストになります。
out_format_flagsは、flavorの出力に関する情報フラグを提供します。現在のところフラグは全く定義されていないため、このフィールドには0をセットして下さい。
| The Media Kit Table of Contents | The Media Kit Index |
Copyright © 2000 Be, Inc. All rights reserved..