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.

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.

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.

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

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.

If your add-on provides nodes that can either read or write media data from files, you should implement this function to describe the media_file_formats you can read and write.

On input, the flavorID argument indicates which flavor you should return information about. You should fill the array outWritableFormats with a list of the file formats the corresponding flavor can write, and the outReadableFormats array with a list of the file formats the flavor can read. The inWriteItems and inReadItems arguments indicate how many items can be stored in each array.

Note

Both outWritableFormats and outReadableFormats can be NULL. Don't write into these arrays if the corresponding pointer is NULL.

On output, you should set outWriteItems to be the number of file formats you can write—even if it's larger than inWriteItems. This lets the caller resize the array and call you back to get the complete list. Likewise, outReadItems should be set to the number of file formats you can read.

The reserved argument isn't currently used, and should always be specified as NULL.

Warning

Only implement this function if your node derives from BFileInterface.

If an error occurs, return an appropriate error code; otherwise, return B_OK.

Implement GetFlavorAt() to store in outInfo a pointer to a static 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. For example, if your add-on only supports one 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;
}

Note

If you allocate memory for the flavor_info structure, be sure to discard it before your add-on is unloaded (the destructor is a good place to do this). If you forget to discard the memory, you'll leak, and that can be really embarrassing.

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 or, if an error occurs, an appropriate error code.

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.

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.

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, although it may not have any fields of interest in it.

The simplest implementation of this function, in which there's no configuration possible, might look like this:

BMediaNode* BMyConsumerAddOn::InstantiateNodeFor(const flavor_info* info,
            BMessage* config, status_t* outError) {
   return new MyConsumerNode((const char *) "My Consumer Node");
}

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

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.

Note

If your node deals with both producers and consumers, you shouldn't implement SniffType(). Implement SniffTypeKind() instead. If SniffTypeKind() is implemented, SniffType() won't be called.

SniffTypeKind() limits the search to the kinds indicated by inKinds. This lets the caller indicate whether it's looking for a consumer or a producer, for example.

In any 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 (where 0.0 means you can't handle it well at all and 1.0 means you can handle it perfectly), and in outInternalID, the internal ID of the flavor that handles the data.

Warning

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.

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.

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.

This function can be quite simple:

BMediaAddOn* make_media_addon(image_id myImage) {
   return new MyConsumerAddOn(myImage);
}

It simply creates an instance of the add-on object (in this case, MyConsumerAddOn), and returns it.

Declared in: 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];
};

The dormant_flavor_info structure describes a flavor in a dormant node.

Declared in: 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.

Declared in: 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);
};