Songbird / Development / Songbird Add-Ons API Documentation

sbIDeviceBase Interface Reference

[SOON TO BE DEPRECATED AFTER 0.3] Base interface for all supported devices. More...

import "sbIDeviceBase.idl";

Inheritance diagram for sbIDeviceBase:

sbIDownloadDevice sbIWMDevice List of all members.

Public Member Functions

void initialize ()
 Initialize the device category handler.
void finalize ()
 Finalize usage of the device category handler.
void addCallback (in sbIDeviceBaseCallback aCallback)
 Add a device category handler callback.
void removeCallback (in sbIDeviceBaseCallback aCallback)
 Remove a device category handler callback.
sbILibrary getLibrary (in AString aDeviceIdentifier)
 Get the device library representing the content available on the device.
unsigned long getDeviceState (in AString aDeviceIdentifier)
 Get the device's current state.
nsIURI getTransferLocation (in AString aDeviceIdentifier, in sbIMediaItem aMediaItem)
 Get preferred transfer location for item.
unsigned long transferItems (in AString aDeviceIdentifier, in nsIArray aMediaItems, in nsIURI aDestionationPath, in unsigned long aDeviceOperation, in boolean aBeginTransferNow, in sbILibrary aDestinationLibrary)
 Transfer items to a library or destination.
unsigned long updateItems (in AString aDeviceIdentifier, in nsIArray aMediaItems)
 Update items on the device.
unsigned long deleteItems (in AString aDeviceIdentifier, in nsIArray aMediaItems)
 Delete items from the device.
sbIMediaItem beginTransfer (in AString aDeviceIdentifier)
 Begin transfer operations.
unsigned long cancelTransfer (in AString aDeviceIdentifier, in nsIArray aMediaItems)
 Cancel a transfer by removing it from the queue.
unsigned long suspendTransfer (in AString aDeviceIdentifier)
 Suspend all transfers.
unsigned long resumeTransfer (in AString aDeviceIdentifier)
 Resume pending transfers.
long long getUsedSpace (in AString aDeviceIdentifier)
 Get the amount of used space from a device.
long long getAvailableSpace (in AString aDeviceIdentifier)
 Get the amount of available space from a device.
nsIArray getSupportedFormats (in AString aDeviceIdentifier)
 Returns a list of file extensions representing the formats supported by a specific device.
boolean isDownloadSupported (in AString aDeviceIdentifier)
 Download is to copy a track from the device to the host.
boolean isUploadSupported (in AString aDeviceIdentifier)
 Is uploading supported on this device?
boolean isDeleteSupported (in AString aDeviceIdentifier)
 Is it possible to delete items from the device?
boolean isUpdateSupported (in AString aDeviceIdentifier)
 Is it possible to update items directly on the device?
boolean isEjectSupported (in AString aDeviceIdentifier)
 Is eject or unmount supported by the device?.
boolean ejectDevice (in AString aDeviceIdentifier)
 Eject or unmount the device from the system.

Public Attributes

const PRUint32 FILE_FORMAT_UNDEFINED = 9999
const PRUint32 FILE_FORMAT_WAV = 0
const PRUint32 FILE_FORMAT_MP3 = 1
const PRUint32 FILE_FORMAT_WMA = 2
const PRUint32 STATE_IDLE = 0
const PRUint32 STATE_BUSY = 1
const PRUint32 STATE_DOWNLOADING = 2
const PRUint32 STATE_UPLOADING = 3
const PRUint32 STATE_DOWNLOAD_PAUSED = 4
const PRUint32 STATE_UPLOAD_PAUSED = 5
const PRUint32 STATE_DELETING = 6
const unsigned long OP_UPLOAD = 1
 Device Operation Constants.
const unsigned long OP_DOWNLOAD = 2
const unsigned long OP_MOVE = 3
attribute AString name
 The name of the device category handler.
readonly attribute AString deviceCategory
 Device category name for this class of devices.
readonly attribute nsIStringEnumerator deviceIdentifiers
 Contains nsISupportsStrings representing the device unique identifiers for all connected devices of this category.
readonly attribute unsigned
long 
deviceCount
 Get the number of devices currently connected.

Detailed Description

[SOON TO BE DEPRECATED AFTER 0.3] Base interface for all supported devices.

Base interface for all supported devices. The supported devices can be CD, Windows Media Device, iPod, etc., and even a download device for downloading and uploading files.

All devices implement this base interface to perform the basic operations such as enumerating tracks (media files) and perform supported I/O operations.

In addition, a device class instance, not to be confused with a device instance, can provide extended information about a device, for example recording speed for a CD drive.

"Device Category" is used in identifying device class instances (using sbIDeviceManager) and "Device String" is for identifying a device. For instance "Songbird CD Device" is the Device Category and "D:\" is the Device String.

Definition at line 127 of file sbIDeviceBase.idl.


Member Function Documentation

void sbIDeviceBase::finalize (  ) 

Finalize usage of the device category handler.

This effectively prepares the device category handler for application shutdown.

void sbIDeviceBase::addCallback ( in sbIDeviceBaseCallback  aCallback  ) 

Add a device category handler callback.

Enables you to get callbacks when devices are connected and when transfers are initiated.

Parameters:
aCallback The device category handler callback you wish to add.

void sbIDeviceBase::removeCallback ( in sbIDeviceBaseCallback  aCallback  ) 

Remove a device category handler callback.

Parameters:
aCallback The device category handler callback you wish to remove.

sbILibrary sbIDeviceBase::getLibrary ( in AString  aDeviceIdentifier  ) 

Get the device library representing the content available on the device.

Parameters:
aDeviceIdentifier The unique device identifier.
Returns:
The library for the specified device.

unsigned long sbIDeviceBase::getDeviceState ( in AString  aDeviceIdentifier  ) 

Get the device's current state.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
The current state of the device.

nsIURI sbIDeviceBase::getTransferLocation ( in AString  aDeviceIdentifier,
in sbIMediaItem  aMediaItem 
)

Get preferred transfer location for item.

Get a transfer location for the specified media item. This enables the device to determine where best to put this media item based on it's own set of criteria.

Parameters:
aDeviceIdentifier The device unique identifier.
aMediaItem The media item that is about to be transferred.
Returns:
The transfer location for the item.

unsigned long sbIDeviceBase::transferItems ( in AString  aDeviceIdentifier,
in nsIArray  aMediaItems,
in nsIURI  aDestionationPath,
in unsigned long  aDeviceOperation,
in boolean  aBeginTransferNow,
in sbILibrary  aDestinationLibrary 
)

Transfer items to a library or destination.

If you call this method with a library only, the device will attempt to read the library's preferred transfer destination and use it.

If you call this method with a destination only, the device will attempt to transfer the items to that destination only.

If you call this method with a library and destination path, the device will attempt to simply pass a destination if you do not wish to add the item to a library after the transfer is complete.

Parameters:
aDeviceIdentifier The device unique identifier.
aMediaItems An array of media items to transfer.
aDestinationPath The desired destination path, path may include full filename.
aDeviceOperation The desired operation (upload, download, move).
aBeginTransferNow Begin the transfer operation immediately?
aDestinationLibrary The desired destination library.
Returns:
Number of items actually queued for transfer.

unsigned long sbIDeviceBase::deleteItems ( in AString  aDeviceIdentifier,
in nsIArray  aMediaItems 
)

Delete items from the device.

Parameters:
aDeviceIdentifier The device unique identifier.
aMediaItems An array of sbIMediaItem objects.
Returns:
Number of items actually deleted from the device.

sbIMediaItem sbIDeviceBase::beginTransfer ( in AString  aDeviceIdentifier  ) 

Begin transfer operations.

Returns:
The media item that began transferring.

unsigned long sbIDeviceBase::cancelTransfer ( in AString  aDeviceIdentifier,
in nsIArray  aMediaItems 
)

Cancel a transfer by removing it from the queue.

Cancel a transfer by removing it from the queue. If the item has already been transfered this function has no effect.

Parameters:
aDeviceIdentifier The device unique identifier
aMediaItems An array of media items.
Returns:
The number of transfers actually cancelled.

unsigned long sbIDeviceBase::suspendTransfer ( in AString  aDeviceIdentifier  ) 

Suspend all transfers.

Suspend all active transfers.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
Number of transfer items actually suspended.

unsigned long sbIDeviceBase::resumeTransfer ( in AString  aDeviceIdentifier  ) 

Resume pending transfers.

Resume pending transfers for a device.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
Number of transfer items actually resumed.

long long sbIDeviceBase::getUsedSpace ( in AString  aDeviceIdentifier  ) 

Get the amount of used space from a device.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
The amount of used space on the device, in bytes.

long long sbIDeviceBase::getAvailableSpace ( in AString  aDeviceIdentifier  ) 

Get the amount of available space from a device.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
The amount of available space, in bytes.

nsIArray sbIDeviceBase::getSupportedFormats ( in AString  aDeviceIdentifier  ) 

Returns a list of file extensions representing the formats supported by a specific device.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
An array of nsISupportsString containing the supported formats in file extension format.

boolean sbIDeviceBase::isDownloadSupported ( in AString  aDeviceIdentifier  ) 

Download is to copy a track from the device to the host.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
True or false.

boolean sbIDeviceBase::isUploadSupported ( in AString  aDeviceIdentifier  ) 

Is uploading supported on this device?

Upload is to copy a track from host to the device

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
True or false.

boolean sbIDeviceBase::isDeleteSupported ( in AString  aDeviceIdentifier  ) 

Is it possible to delete items from the device?

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
True or false.

boolean sbIDeviceBase::isUpdateSupported ( in AString  aDeviceIdentifier  ) 

Is it possible to update items directly on the device?

This method could be used for updating tracks on a device or applying CDDB match for a CD.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
True or false.

boolean sbIDeviceBase::isEjectSupported ( in AString  aDeviceIdentifier  ) 

Is eject or unmount supported by the device?.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
True or false.

boolean sbIDeviceBase::ejectDevice ( in AString  aDeviceIdentifier  ) 

Eject or unmount the device from the system.

Parameters:
aDeviceIdentifier The device unique identifier.
Returns:
True or false.


Member Data Documentation

const PRUint32 sbIDeviceBase::FILE_FORMAT_UNDEFINED = 9999

File format constants

XXXben We have an explicit -1 here but later we have PRUint32 as a param for get/set Upload and Download FileType. Also, should these be renamed to FILE_TYPE_XXX or should we change the other funcs to use FileFormat?

Definition at line 137 of file sbIDeviceBase.idl.

const PRUint32 sbIDeviceBase::STATE_IDLE = 0

Device State constants

Generally speaking I/O commands can be issued to a device if device state is STATE_IDLE for the device. But if STATE_DOWNLOADING then it can be asked to transfer more tracks, and the same applies to STATE_UPLOADING and STATE_DELETING. STATE_TRANSFERRING_PAUSED indicates a paused transfer.

XXXben STATE_TRANSFERRING_PAUSED no longer exists

Definition at line 152 of file sbIDeviceBase.idl.

const unsigned long sbIDeviceBase::OP_UPLOAD = 1

Device Operation Constants.

See also:
transferItems

Definition at line 164 of file sbIDeviceBase.idl.


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