Songbird / Development / Songbird Add-Ons API Documentation

sbIMetadataHandler Interface Reference

An object capable of manipulating the metadata tags for a media file. More...

List of all members.

Public Member Functions

PRInt32 vote (in AString aUrl)
 Vote to be the handler returned for the given url.
PRInt32 read ()
 Start the read operation.
PRInt32 write ()
 Start the write operation.
void onChannelData (in nsISupports aChannel)
 Be thou informst that one's sbIMetadataChannel has just received data.
void close ()
 Close down the internals of the handler, stop any asynchronous operations, free any allocations.

Public Attributes

const PRUint32 METADATA_IMAGE_TYPE_OTHER = 0x00
 Constant for the type of image in the metadata, these are pulled from the taglib/attachedpictureframe.h.
const PRUint32 METADATA_IMAGE_TYPE_FILEICON = 0x01
const PRUint32 METADATA_IMAGE_TYPE_OTHERFILEICON = 0x02
const PRUint32 METADATA_IMAGE_TYPE_FRONTCOVER = 0x03
const PRUint32 METADATA_IMAGE_TYPE_BACKCOVER = 0x04
const PRUint32 METADATA_IMAGE_TYPE_LEAFLETPAGE = 0x05
const PRUint32 METADATA_IMAGE_TYPE_MEDIA = 0x06
const PRUint32 METADATA_IMAGE_TYPE_LEADARTIST = 0x07
const PRUint32 METADATA_IMAGE_TYPE_ARTIST = 0x08
const PRUint32 METADATA_IMAGE_TYPE_CONDUCTOR = 0x09
const PRUint32 METADATA_IMAGE_TYPE_BAND = 0x0A
const PRUint32 METADATA_IMAGE_TYPE_COMPOSER = 0x0B
const PRUint32 METADATA_IMAGE_TYPE_LYRICIST = 0x0C
const PRUint32 METADATA_IMAGE_TYPE_RECORDINGLOCATION = 0x0D
const PRUint32 METADATA_IMAGE_TYPE_DURINGRECORDING = 0x0E
const PRUint32 METADATA_IMAGE_TYPE_DURINGPERFORMANCE = 0x0F
const PRUint32 METADATA_IMAGE_TYPE_MOVIESCREENCAPTURE = 0x10
const PRUint32 METADATA_IMAGE_TYPE_COLOUREDFISH = 0x11
const PRUint32 METADATA_IMAGE_TYPE_ILLUSTRATION = 0x12
const PRUint32 METADATA_IMAGE_TYPE_BANDLOGO = 0x13
const PRUint32 METADATA_IMAGE_TYPE_PUBLISHERLOGO = 0x14
attribute sbIMutablePropertyArray props
 An array of metadata properties.
readonly attribute PRBool completed
 Whether or not the object has completed its read/write operation.
readonly attribute PRBool requiresMainThread
 Whether or not this handler MUST be run on the main thread.
attribute nsIChannel channel
 The object's nsIChannel.


Detailed Description

An object capable of manipulating the metadata tags for a media file.

User code requests a handler by calling sbIMetadataManager::getHandlerForMediaURL that then returns one of these.

See also:
sbIMetadataManager

Definition at line 45 of file sbIMetadataHandler.idl.


Member Function Documentation

PRInt32 sbIMetadataHandler::vote ( in AString  aUrl  ) 

Vote to be the handler returned for the given url.

The sbIMetadataManager will instantiate one of every sbIMetadataHandler subclass and ask it to vote on the given url. Whichever handler returns the highest vote will be used as the handler for the url.

Values less than zero cause that handler to be ignored.

At the moment, our handlers return -1, 0, or 1 (for "no," "maybe," and "yes").

Parameters:
aUrl The url upon which one should vote
Returns:
The vote
See also:
sbIMetadataManager

PRInt32 sbIMetadataHandler::read (  ) 

Start the read operation.

After getting a handler from the sbIMetadataManager, the user code usually calls read upon it, immediately. The implementor may choose to handle the request immediately or asynchronously.

Returns:
-1 if operating asynchronously, otherwise the number of metadata values read (0 on failure)

PRInt32 sbIMetadataHandler::write (  ) 

Start the write operation.

After getting a handler from the sbIMetadataManager, the user code may set an sbIPropertyArray object into the handler and then call write to write the abstract metadata map into the specific metadata requirements of the file format supported by the handler.

Note that the number of items written may not always equal the number of items in the sbIPropertyArray object if the underlying file format does not support the given keys.

Returns:
-1 if operating asynchronously, otherwise the number of metadata values written (0 on failure)

void sbIMetadataHandler::onChannelData ( in nsISupports  aChannel  ) 

Be thou informst that one's sbIMetadataChannel has just received data.

Every time the underlying nsIChannel dumps data on the sbIMetadataChannel, plus once more for when the nsIChannel reports a stop condition.

This is a chance for the handler code to attempt to parse the datastream.

Parameters:
aChannel The sbIMetadataChannel delivering data. You'll have to QI for it. consider removing. sbIMetadataChannel appears to be unused.


Member Data Documentation

attribute sbIMutablePropertyArray sbIMetadataHandler::props

An array of metadata properties.

Metadata properties read from or to be written to the file.

When the handler has successfully completed its read() operation, the values attribute will be filled with the metadata from the url.

Definition at line 81 of file sbIMetadataHandler.idl.

readonly attribute PRBool sbIMetadataHandler::completed

Whether or not the object has completed its read/write operation.

This value is false until the handler completes its read/write operation.

It is up to the implementor to determine if read/write calls should operate asynchronously or by blocking. The user of the handler should not attempt to get the sbIPropertyArray object before the operation is completed.

Definition at line 92 of file sbIMetadataHandler.idl.

readonly attribute PRBool sbIMetadataHandler::requiresMainThread

Whether or not this handler MUST be run on the main thread.

Since nsIChannel and other dependencies are not thread safe, some sbIMetadataHandler implementations can not be run on background threads.

Definition at line 100 of file sbIMetadataHandler.idl.

attribute nsIChannel sbIMetadataHandler::channel

The object's nsIChannel.

The object is assigned an nsIChannel from the sbIMetadataManager after it has successfully voted for an url. In the Read call, the implementor may choose to pull the url from the channel and use that directly, or open the channel (either itself or using an sbIMetadataChannel as a helper) and stream the data to be parsed.

In general, for local files, it is faster to pull the url and handle the metadata read immediately rather than open the channel. For remote files, it's far easier to just use the channel infrastructure already setup.

Definition at line 115 of file sbIMetadataHandler.idl.


The documentation for this interface was generated from the following file:
Generated on Tue Mar 10 14:29:00 2009 for Songbird by  doxygen 1.5.2