sbIDeviceBase Interface Reference

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

import"sbIDeviceBase.idl";

Inheritance diagram for sbIDeviceBase:
[legend]
Collaboration diagram for sbIDeviceBase:
[legend]

Public Member Functions

void initialize ()
 Initialize the device category handler. More...
 
void finalize ()
 Finalize usage of the device category handler. More...
 
void addCallback (in sbIDeviceBaseCallback aCallback)
 Add a device category handler callback. More...
 
void removeCallback (in sbIDeviceBaseCallback aCallback)
 Remove a device category handler callback. More...
 
sbILibrary getLibrary (in AString aDeviceIdentifier)
 Get the device library representing the content available on the device. More...
 
unsigned long getDeviceState (in AString aDeviceIdentifier)
 Get the device's current state. More...
 
nsIURI getTransferLocation (in AString aDeviceIdentifier, in sbIMediaItem aMediaItem)
 Get preferred transfer location for item. More...
 
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. More...
 
unsigned long updateItems (in AString aDeviceIdentifier, in nsIArray aMediaItems)
 Update items on the device. More...
 
unsigned long deleteItems (in AString aDeviceIdentifier, in nsIArray aMediaItems)
 Delete items from the device. More...
 
unsigned long deleteAllItems (in AString aDeviceIdentifier)
 
unsigned long createPlaylists (in AString aDeviceIdentifier, in nsIArray aMediaLists)
 
unsigned long deletePlaylists (in AString aDeviceIdentifier, in nsIArray aMediaLists)
 
unsigned long addToPlaylist (in AString aDeviceIdentifier, in sbIMediaList aMediaList, in nsIArray aMediaItems, in unsigned long aBeforeIndex)
 
unsigned long removeFromPlaylist (in AString aDeviceIdentifier, in sbIMediaList aMediaList, in sbIMediaItem aMediaItem, in unsigned long aIndex)
 
unsigned long movePlaylistItem (in AString aDeviceIdentifier, in sbIMediaList aMediaList, in unsigned long aFromIndex, in unsigned long aToIndex)
 
unsigned long clearPlaylist (in AString aDeviceIdentifier, in sbIMediaList aMediaList)
 
sbIMediaItem beginTransfer (in AString aDeviceIdentifier)
 Begin transfer operations. More...
 
unsigned long cancelTransfer (in AString aDeviceIdentifier, in nsIArray aMediaItems)
 Cancel a transfer by removing it from the queue. More...
 
unsigned long suspendTransfer (in AString aDeviceIdentifier)
 Suspend all transfers. More...
 
unsigned long resumeTransfer (in AString aDeviceIdentifier)
 Resume pending transfers. More...
 
long long getUsedSpace (in AString aDeviceIdentifier)
 Get the amount of used space from a device. More...
 
long long getAvailableSpace (in AString aDeviceIdentifier)
 Get the amount of available space from a device. More...
 
nsIArray getSupportedFormats (in AString aDeviceIdentifier)
 Returns a list of file extensions representing the formats supported by a specific device. More...
 
boolean isDownloadSupported (in AString aDeviceIdentifier)
 Download is to copy a track from the device to the host. More...
 
boolean isUploadSupported (in AString aDeviceIdentifier)
 Is uploading supported on this device? More...
 
boolean isDeleteSupported (in AString aDeviceIdentifier)
 Is it possible to delete items from the device? More...
 
boolean isUpdateSupported (in AString aDeviceIdentifier)
 Is it possible to update items directly on the device? More...
 
boolean isEjectSupported (in AString aDeviceIdentifier)
 Is eject or unmount supported by the device?. More...
 
boolean ejectDevice (in AString aDeviceIdentifier)
 Eject or unmount the device from the system. More...
 

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. More...
 
const unsigned long OP_DOWNLOAD = 2
 
const unsigned long OP_MOVE = 3
 
attribute AString name
 The name of the device category handler. More...
 
readonly attribute AString deviceCategory
 Device category name for this class of devices. More...
 
readonly attribute
nsIStringEnumerator 
deviceIdentifiers
 Contains nsISupportsStrings representing the device unique identifiers for all connected devices of this category. More...
 
readonly attribute unsigned long deviceCount
 Get the number of devices currently connected. More...
 

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::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
aCallbackThe device category handler callback you wish to add.
unsigned long sbIDeviceBase::addToPlaylist ( in AString  aDeviceIdentifier,
in sbIMediaList  aMediaList,
in nsIArray  aMediaItems,
in unsigned long  aBeforeIndex 
)
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
aDeviceIdentifierThe device unique identifier
aMediaItemsAn array of media items.
Returns
The number of transfers actually cancelled.
unsigned long sbIDeviceBase::clearPlaylist ( in AString  aDeviceIdentifier,
in sbIMediaList  aMediaList 
)
unsigned long sbIDeviceBase::createPlaylists ( in AString  aDeviceIdentifier,
in nsIArray  aMediaLists 
)
unsigned long sbIDeviceBase::deleteAllItems ( in AString  aDeviceIdentifier)
unsigned long sbIDeviceBase::deleteItems ( in AString  aDeviceIdentifier,
in nsIArray  aMediaItems 
)

Delete items from the device.

Parameters
aDeviceIdentifierThe device unique identifier.
aMediaItemsAn array of sbIMediaItem objects.
Returns
Number of items actually deleted from the device.
unsigned long sbIDeviceBase::deletePlaylists ( in AString  aDeviceIdentifier,
in nsIArray  aMediaLists 
)
boolean sbIDeviceBase::ejectDevice ( in AString  aDeviceIdentifier)

Eject or unmount the device from the system.

Parameters
aDeviceIdentifierThe device unique identifier.
Returns
True or false.
void sbIDeviceBase::finalize ( )

Finalize usage of the device category handler.

This effectively prepares the device category handler for application shutdown.

long long sbIDeviceBase::getAvailableSpace ( in AString  aDeviceIdentifier)

Get the amount of available space from a device.

Parameters
aDeviceIdentifierThe device unique identifier.
Returns
The amount of available space, in bytes.
unsigned long sbIDeviceBase::getDeviceState ( in AString  aDeviceIdentifier)

Get the device's current state.

Parameters
aDeviceIdentifierThe device unique identifier.
Returns
The current state of the device.
sbILibrary sbIDeviceBase::getLibrary ( in AString  aDeviceIdentifier)

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

Parameters
aDeviceIdentifierThe unique device identifier.
Returns
The library for the specified device.
nsIArray sbIDeviceBase::getSupportedFormats ( in AString  aDeviceIdentifier)

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

Parameters
aDeviceIdentifierThe device unique identifier.
Returns
An array of nsISupportsString containing the supported formats in file extension format.
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 its own set of criteria.

Parameters
aDeviceIdentifierThe device unique identifier.
aMediaItemThe media item that is about to be transferred.
Returns
The transfer location for the item.
long long sbIDeviceBase::getUsedSpace ( in AString  aDeviceIdentifier)

Get the amount of used space from a device.

Parameters
aDeviceIdentifierThe device unique identifier.
Returns
The amount of used space on the device, in bytes.
void sbIDeviceBase::initialize ( )

Initialize the device category handler.

boolean sbIDeviceBase::isDeleteSupported ( in AString  aDeviceIdentifier)

Is it possible to delete items from the device?

Parameters
aDeviceIdentifierThe device unique identifier.
Returns
True or false.
boolean sbIDeviceBase::isDownloadSupported ( in AString  aDeviceIdentifier)

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

Parameters
aDeviceIdentifierThe device unique identifier.
Returns
True or false.
boolean sbIDeviceBase::isEjectSupported ( in AString  aDeviceIdentifier)

Is eject or unmount supported by the device?.

Parameters
aDeviceIdentifierThe 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
aDeviceIdentifierThe 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
aDeviceIdentifierThe device unique identifier.
Returns
True or false.
unsigned long sbIDeviceBase::movePlaylistItem ( in AString  aDeviceIdentifier,
in sbIMediaList  aMediaList,
in unsigned long  aFromIndex,
in unsigned long  aToIndex 
)
void sbIDeviceBase::removeCallback ( in sbIDeviceBaseCallback  aCallback)

Remove a device category handler callback.

Parameters
aCallbackThe device category handler callback you wish to remove.
unsigned long sbIDeviceBase::removeFromPlaylist ( in AString  aDeviceIdentifier,
in sbIMediaList  aMediaList,
in sbIMediaItem  aMediaItem,
in unsigned long  aIndex 
)
unsigned long sbIDeviceBase::resumeTransfer ( in AString  aDeviceIdentifier)

Resume pending transfers.

Resume pending transfers for a device.

Parameters
aDeviceIdentifierThe device unique identifier.
Returns
Number of transfer items actually resumed.
unsigned long sbIDeviceBase::suspendTransfer ( in AString  aDeviceIdentifier)

Suspend all transfers.

Suspend all active transfers.

Parameters
aDeviceIdentifierThe device unique identifier.
Returns
Number of transfer items actually suspended.
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
aDeviceIdentifierThe device unique identifier.
aMediaItemsAn array of media items to transfer.
aDestinationPathThe desired destination path, path may include full filename.
aDeviceOperationThe desired operation (upload, download, move).
aBeginTransferNowBegin the transfer operation immediately?
aDestinationLibraryThe desired destination library.
Returns
Number of items actually queued for transfer.
unsigned long sbIDeviceBase::updateItems ( in AString  aDeviceIdentifier,
in nsIArray  aMediaItems 
)

Update items on the device.

Member Data Documentation

readonly attribute AString sbIDeviceBase::deviceCategory

Device category name for this class of devices.

Definition at line 206 of file sbIDeviceBase.idl.

readonly attribute unsigned long sbIDeviceBase::deviceCount

Get the number of devices currently connected.

Definition at line 217 of file sbIDeviceBase.idl.

readonly attribute nsIStringEnumerator sbIDeviceBase::deviceIdentifiers

Contains nsISupportsStrings representing the device unique identifiers for all connected devices of this category.

Definition at line 212 of file sbIDeviceBase.idl.

const PRUint32 sbIDeviceBase::FILE_FORMAT_MP3 = 1

Definition at line 139 of file sbIDeviceBase.idl.

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::FILE_FORMAT_WAV = 0

Definition at line 138 of file sbIDeviceBase.idl.

const PRUint32 sbIDeviceBase::FILE_FORMAT_WMA = 2

Definition at line 140 of file sbIDeviceBase.idl.

attribute AString sbIDeviceBase::name

The name of the device category handler.

Definition at line 171 of file sbIDeviceBase.idl.

const unsigned long sbIDeviceBase::OP_DOWNLOAD = 2

Definition at line 165 of file sbIDeviceBase.idl.

const unsigned long sbIDeviceBase::OP_MOVE = 3

Definition at line 166 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.

const PRUint32 sbIDeviceBase::STATE_BUSY = 1

Definition at line 153 of file sbIDeviceBase.idl.

const PRUint32 sbIDeviceBase::STATE_DELETING = 6

Definition at line 158 of file sbIDeviceBase.idl.

const PRUint32 sbIDeviceBase::STATE_DOWNLOAD_PAUSED = 4

Definition at line 156 of file sbIDeviceBase.idl.

const PRUint32 sbIDeviceBase::STATE_DOWNLOADING = 2

Definition at line 154 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 PRUint32 sbIDeviceBase::STATE_UPLOAD_PAUSED = 5

Definition at line 157 of file sbIDeviceBase.idl.

const PRUint32 sbIDeviceBase::STATE_UPLOADING = 3

Definition at line 155 of file sbIDeviceBase.idl.


The documentation for this interface was generated from the following file: