BMediaAddOn

Derived from: none

Declared in: be/media/MediaAddOn.h

Library: libmedia.so

Allocation: Constructor only

[method summary]

A BMediaAddOn-derived object is an executable program that lives in a disk file and is loaded by the Media Server when it's needed. A BMediaAddOn tells the Media Server what kinds of nodes it can create and handles the actual creation of those nodes when called upon by the Media Server to do so.

It's important to note that the functions in the BMediaAddOn class will typically only be called by the Media Kit (and from within the add-on itself). These functions aren't called by client applications.

Getting to Node You...

A given node can support as many media kinds and formats as it wants (although if you support too many widely disparate media types, your add-on may get difficult to maintain, but that's another issue entirely). For example, a node that supports video might support inputting AVI, QuickTime, and MPEG-2, but might only be able to output AVI. This is information that the Media Kit needs to know. For this reason, the BMediaAddOn needs to provide information about the media flavors it supports.

This is done using the flavor_info structure:

   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);
   };

The name and info fields provide a human-readable name, and information about the flavor.

The kinds field should indicate all the relevant kinds that the node matches; this is a bit field, and it's possible that more than one flag may be relevant. See node_kind .

The flavor_flags field is reserved and should be zero.

The internal_id is an internal ID number that your add-on can use to identify the flavor; the flavor will be requested by the Media Kit using this ID number.

The possible_count field specifies to the Media Kit the maximum number of instances of your node can be in existence at the same time. For example, if your node provides support for a particular sound card, this value should be equal to the number of cards you support that are currently installed in the computer.

in_format_count specifies how many input formats the flavor supports, and in_formats is a list of all the input formats supported by the flavor.

in_format_flags provides informational flags about the flavor's inputs. There aren't any defined values for this field yet; be sure to set it to 0.

out_format_count specifies how many output formats the flavor supports, and out_formats is a list of all the output formats supported by the flavor.

out_format_flags provides informational flags about the flavor's outputs. There aren't any defined values for this field yet; be sure to set it to 0.

If your node is a physical input, such as a sound card, your node's kinds field should include B_PHYSICAL_INPUT among the flags set therein. Likewise, if your node is a physical output, or a system mixer, you should include B_PHYSICAL_OUTPUT or B_SYSTEM_MIXER.

Your node's constructor should also call AddNodeKind() to add these kind flags; the base classes only add B_BUFFER_CONSUMER, B_BUFFER_PRODUCER, and so forth; the flags indicating that the node represents a physical input, physical output, or system mixer aren't added automatically. For example, a sound digitizer node's constructor might have the following form:

   MyBufferProducer::MyBufferProducer(const char *name) :
            BMediaNode(name),
            BBufferProducer() {
   
      AddNodeKind(B_PHYSICAL_INPUT);
   
      /* constructor stuff goes here */
   }

<<<Provide an example>>>

Member Function Summary

Function		Description
virtual	AutoStart()	Gives the add-on an opportunity to auto-start nodes.
virtual	CountFlavors()	Return the number of flavors the add-on supports
virtual	GetConfigurationFor()	Store information about a node into a BMessage.
virtual	GetFlavorAt()	Return information about a flavor.
	ImageID()	Returns the add-on's image ID.
virtual	InitCheck()	Return text describing the most recent error that occurred.
virtual	InstantiateNodeFor()	Instantiate a new node corresponding to a particular flavor.
virtual	SniffRef()	Attempt to identify the MIME type of a file.
virtual	SniffType()	Given a BMimeType, report how well your add-on can handle that file's contents.
virtual	WantsAutoStart()	Return true if the add-on wants its AutoStart() function to be called.

Global C Function Summary

Function		Description
	make_media_addon()	Export this function, which instantiates and returns the BMediaAddOn that the Media Kit will use to reference your add-on.

Constructor and Destructor

BMediaAddOn()

      explicit BMediaAddOn(image_id image) 

This is the BMediaAddOn constructor; your derived class should perform whatever initialization is necessary in the constructor, and handle any activities necessary in order to properly comply with the media add-on protocol.

The image_id identifies the add-on image from which the add-on was loaded. Your make_media_addon() function should be sure to save the image ID passed to it and pass that value through to the BMediaAddOn constructor, or the Media Kit will be unhappy with you.

~BMediaAddOn

      ~BMediaAddOn() 

You should never delete a BMediaAddOn yourself; the Media Server will do this when the add-on is no longer needed. However, if you're implementing a media add-on, this is a good place to handle disposing of memory you've allocated.

Member Functions

AutoStart()

      virtual status_t AutoStart(int32 index, BMediaNode **outNode,
         int32 *outInternalID, bool *outHasMore) = 0

If WantsAutoStart() returns true, you'll get repeated calls to AutoStart() when your add-on is loaded.

Your AutoStart() function should be implemented to instantiate nodes to your liking, one for each call to AutoStart(). Each time AutoStart() is called, index will be one higher than the previous pass. After creating the new node, store a pointer to it in outNode, and set outInternalID to the internal ID of the flavor represented by that node.

Before returning, set outHasMore to true if there are more nodes to start, and false if there aren't.

Return B_OK if you return a valid node. If there aren't any more nodes to be started, return B_BAD_INDEX. If the specified index fails, but there may be other nodes to start, return B_ADDON_FAILED.

CountFlavors()

      virtual int32 CountFlavors(void) = 0

Implement this hook function to return the number of flavors your add-on can deal with.

GetConfigurationFor()

      virtual status_t GetConfigurationFor(BMediaNode *node, BMessage *config) = 0

Implement this function to save information about how the given node is configured into the specified message. This lets the node's configuration be saved to disk for future rehydration using InstantiateNodeFor().

Note that it's not reasonable to save information about what connections are routed through the node, since the other nodes probably won't exist when the node is rehydrated. It's up to the application to reconstruct the connections itself, as it wishes.

If the configuration information is stashed into config without errors, return B_OK; otherwise, return an appropriate error code.

GetFlavorAt()

      virtual status_t GetFlavorAt(int32 flavorNum, const flavor_info **outInfo) = 0

Implement GetFlavorAt() to store in outInfo a pointer to a flavor_info structure describing one flavor supported by your add-on. The data pointed to by outInfo will be copied by the Media Kit after GetFlavorAt() returns.

If flavorNum is greater than CountFlavors()-1 (in other words, if the requested number is larger than the number of flavors you support), return B_ERROR.. Otherwise, return B_OK.

ImageID()

      image_id ImageID(void)

Returns the add-on's image ID, as specified by the BMediaAddOn constructor.

Your make_media_addon() function should be sure to save the image ID passed to it and pass that value through to the BMediaAddOn constructor, or the Media Kit will be unhappy with you.

InitCheck()

      virtual status_t InitCheck(const char **outFailureText) = 0

Implement this hook function to set outFailureText to point to a static text buffer that contains a message explaining why your add-on failed the most recent operation requested by the Media Server. This doesn't include errors reported by nodes instantiated by your add-on, but only to errors caused directly by your BMediaAddOn-derived object.

The buffer pointed to by outFailureText shouldn't go away until the add-on is reloaded or a new call to InitCheck() is made.

Also returned is the actual result code from that operation; if all is well, B_OK should be returned.

InstantiateNodeFor()

      virtual BMediaNode *InstantiateNodeFor(const flavor_info *info,
         BMessage *config, status_t *outError) = 0

Given the information in info (which might be a copy of information you previously returned from a GetFlavorAt() call), you should instantiate a new object of the node class referenced by info's internal_id field and return a pointer to that node.

The config message might contain information saved by a previous instance of the same flavor node, and should be used to configure the new node if possible. config will never be NULL.

If a new instance can't be instantiated, set outError to an appropriate error code and return NULL. Otherwise, set outError to B_OK.

SniffRef(), SniffType()

      virtual status_t SniffRef(const entry_ref &file, BMimeType *outMimeType,
         float *outQuality, int32 *outInternalID)
      virtual status_t SniffType(BMimeType &mimeType,
         float *outQuality, int32 *outInternalID)

If your add-on supports BFileInterface nodes, you may implement SniffRef(). Given the specified file, examine the file and set outMimeType to describe the MIME type of the file.

Additionally, you can implement SniffType() to report how well your add-on can handle a file containing data of the MIME type specified by mimeType.

In either case, you should also store, in outQuality, a value representing the quality level at which your add-on can interpret the data in the file, and in outInternalID, the internal ID of the flavor that handles the data.

Don't implement these functions if your add-on doesn't support BFileInterface nodes.

Return B_OK if you've successfully identified the node; otherwise, return an appropriate error code.

WantsAutoStart()

      virtual bool WantsAutoStart(void) = 0

Implement this hook function to return true if there are one or more node flavors supported by your add-on that want to be instantiated automatically when the add-on is loaded, instead of waiting until they're explicitly instantiated by an application's request later. Return false otherwise.

Global C Functions

make_media_addon()

      BMediaAddOn *make_media_addon(image_id addonID)

make_media_addon() is the global C function your add-on needs to implement in order to make itself available to the world. It will be called when the Media Server loads your add-on, and you should return an instance of your BMediaAddOn-derived class, with the appropriate overrides to the hook functions.

The addonID argument is your add-on's image ID. Your make_media_addon() function should be sure to save the image ID passed to it and pass that value through to the BMediaAddOn constructor, or the Media Kit will be unhappy with you.

Structures

dormant_node_info

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];
   };

The dormant_node_info structure describes a node that resides in an add-on and that may not be in memory. You might use it when issuing the BMediaRoster::InstantiateDormantNode() to instantiate a node, for example.

The addon field indicates the ID number of the media add-on in which the node resides, and the flavor_id is the flavor ID internal to that add-on indicating which flavor the node should represent. The name field is the node's name.

flavor_info

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);
   };

The name and info fields provide a human-readable name, and information about the flavor.

The kinds field should be set to the node kind. See node_kind .

The flavor_flags field is reserved and should be zero.

The internal_id is an internal ID number that your add-on can use to identify the flavor; the flavor will be requested by the Media Kit using this ID number.

The possible_count field specifies to the Media Kit the maximum number of instances of your node can be in existence at the same time. For example, if your node provides support for a particular sound card, this value should be equal to the number of cards you support that are currently installed in the computer.

in_format_count specifies how many input formats the flavor supports, and in_formats is a list of all the input formats supported by the flavor.

in_format_flags provides informational flags about the flavor's inputs. <<<more info>>>

out_format_count specifies how many output formats the flavor supports, and out_formats is a list of all the output formats supported by the flavor.

out_format_flags provides informational flags about the flavor's outputs. <<<more info>>>

The Be Book, in lovely HTML, for BeOS Release 4.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified December 9, 1998.