sbIMetadataHandler Interface Reference

An object capable of returning the metadata from the url to a file. More...

List of all members.

Public Member Functions

PRInt32 vote (in AString aUrl)
 Vote to be the handler returned for the given url.
void supportedMIMETypes (out PRUint32 nMIMECount,[array, size_is(nMIMECount), retval] out wstring aMIMETypes)
 Get the mimetypes supported by this handler (probably DEPRECATED).
void supportedFileExtensions (out PRUint32 nExtCount,[array, size_is(nExtCount), retval] out wstring aExts)
 Get the extensions supported by this handler (probably DEPRECATED).
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 downloads, free any allocations.

Public Attributes

attribute sbIMetadataValues values
 The values object containing the metadata information.
readonly attribute PRBool completed
 Whether or not the object has completed its read() operation.
attribute nsIChannel channel
 The object's nsIChannel.


Detailed Description

An object capable of returning the metadata from the url to a 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

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.

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)

void sbIMetadataHandler::supportedFileExtensions ( out PRUint32  nExtCount,
[array, size_is(nExtCount), retval] out wstring  aExts 
)

Get the extensions supported by this handler (probably DEPRECATED).

Todo:
Make sure it's safe to deprecate these. Only the cores should need to return mimetype/extension info, I think.
Parameters:
nExtCount The number of extensions returned in the array
aExts The array of extensions supported by this handler

void sbIMetadataHandler::supportedMIMETypes ( out PRUint32  nMIMECount,
[array, size_is(nMIMECount), retval] out wstring  aMIMETypes 
)

Get the mimetypes supported by this handler (probably DEPRECATED).

Todo:
Make sure it's safe to deprecate these. Only the cores should need to return mimetype/extension info, I think.
Parameters:
nMIMECount The number of mimetypes returned in the array
aMIMETypes The array of mimetypes supported by this handler

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::write (  ) 

Start the write operation.

After getting a handler from the sbIMetadataManager, the user code may set an sbIMetadataValues 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 sbIMetadataValues object if the underlying file format does not support the given keys.

Todo:
Make anything actually work with a write operation
Returns:
-1 if operating asynchronously, otherwise the number of metadata values written (0 on failure)


Member Data Documentation

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 79 of file sbIMetadataHandler.idl.

readonly attribute PRBool sbIMetadataHandler::completed

Whether or not the object has completed its read() operation.

This value is false until the handler completes its read() operation.

It is up to the implementor to determine if a read() call should operate asynchronously or by blocking. The user of the handler should not attempt to get the sbIMetadataValues object before the read() is completed.

Definition at line 64 of file sbIMetadataHandler.idl.

attribute sbIMetadataValues sbIMetadataHandler::values

The values object containing the metadata information.

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

Definition at line 53 of file sbIMetadataHandler.idl.


The documentation for this interface was generated from the following file:
Generated on Mon Aug 21 21:01:55 2006 for Songbird by  doxygen 1.4.7