net.rim.blackberry.api.mail
Class AttachmentDownloadManager

java.lang.Object
  net.rim.blackberry.api.mail.AttachmentDownloadManager

public class AttachmentDownloadManager
extends Object

This class provides the ability to prgrammatically download email attachments for incoming message.

It does not support forwarded or sent messages.

Attachments can be downloaded regardless of its viewable state. That is, an attachment can be supportedAttachmentPart or unsupportedAttachmentPart.

Third party applications can implement DownloadProgressListener to receive downloading outcomes.

Pre-validations are invoked before attachments are downloaded. If any of the following conditions happens, exceptions are thrown and the attachment will not be downloaded.

• Download already in progress.
• Attempt to download zero length files.
• File size is bigger than allowed by IT policy or service records. If third parties are not granted to download attachments, the file size is zero.
• Attachments are encrypted.
• Not enough available space.

NOTE: To have the ability to cancel the attachment download, third parties will need to keep a reference of the AttachmentDownloadmanger object.

Example:

Step 1: Create a class to implement DownloadProgressListener. e.g. class AttachmentAction implements DownloadProgressListener

Step 2: Override the DownloadProgressListener's callbacks.

Step 3: Initialize AttachmentDownloadManager. e.g. AttachmentDownloadManager adm = new AttachmentDownloadManager();

Step 4: Call AttachmentDownloadManager's download method. e.g. adm.download(bodyPart, null, this); // this is the class that implements DownloadProgressListener; bodyPart is (un)supportedAttachmentPart.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

Constructor Summary
	AttachmentDownloadManager() Constructor to initialize AttachmentDownloadManager instance.

Method Summary
	boolean	cancelDownload(BodyPart bodyPart) Cancel downloading.
	void	download(BodyPart bodyPart, String path, DownloadProgressListener listener) Download an attachment.
	void	download(BodyPart[] bodyParts, String path, DownloadProgressListener listener) Download a series of attachments.
	BodyPart[]	getAttachmentBodyParts(Message msg) Return a BodyPart array whose elements contain info of file attachment.
	String	getDefaultLocation(BodyPart bodyPart) Return the default location of the body part.
	String[]	getDefaultLocations(BodyPart[] bodyParts) Return an array of default locations.
	String	getDownloadedFileName(BodyPart bodyPart) Return the downloaded file path and name.
	String	getFileContentType(BodyPart bodyPart) Return file content type.
	String	getFileName(BodyPart bodyPart) Return the attchment name.
	int	getFileSize(BodyPart bodyPart) Return the file size.
	boolean	isDownloaded(BodyPart bodyPart) Check if the file attachment associated with the bodyPart has been downloaded.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttachmentDownloadManager

public AttachmentDownloadManager()

Constructor to initialize AttachmentDownloadManager instance.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

Method Detail

download

public void download(BodyPart bodyPart,
                     String path,
                     DownloadProgressListener listener)
              throws IOException

Download an attachment. Downloading outcomes are notified through the progress listener's callbacks.

Parameters:

bodyPart - - a bodypart object contains info of the email attachment.

path - – define a path where the attachment is stored. A default path is used if it is null.

listener - – A downloadProgressListener provides callbacks for downloading status. e.g. completed, in progress, or cancelled (or failed).

Throws:

IllegalArgumentException - - throws when the BodyPart is null.

IOException - - throws if attachments already downloaded, attachment size excceeds the maximum limit set by IT,

IllegalStateException - - throws if the attachment is being downloaded.

UnsupportedOperationException - - throws if the message is encrypted, or the body part does not carry attachment info.

FileIOException - - throws if there is not enough memory to download the bodyPart's attachment.

ControlledAccessException - - throws if users are not granted to access message-related and file features or cross communicate between applications.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

download

public void download(BodyPart[] bodyParts,
                     String path,
                     DownloadProgressListener listener)
              throws IOException

Download a series of attachments.

if an element in the bodypart array does not contains attachment info, an UnsupportedOperationException will be thrown.

Parameters:

bodyPart - - a bodypart object contains info of the email attachment.

path - – define a path where the attachment is stored. A default path is used if it is null.

listener - – A downloadProgressListener provides callbacks for downloading status. e.g. completed, in progress, or cancelled (or failed).

Throws:

IllegalArgumentException - throws if bodyPart array is null or empty.

ControlledAccessException - - throws if users are not granted to access message-related and file features or cross communicate between applications.

UnsupportedOperationException - - throws if the message is encrypted or a bodyPart in the BodyPart array does not carry attachment info.

FileIOException - - throws if the filesystem does not have enough space available to save the attachments.

IOException

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

cancelDownload

public boolean cancelDownload(BodyPart bodyPart)

Cancel downloading.

Parameters:

bodyPart - - a bodypart object contains info of the email attachment.

Returns:

boolean - true if cancelled, false otherwise.

Throws:

UnsupportedOperationException - - throws if the bodyPart does not carry attachment info.

ControlledAccessException - - throws if users are not granted to access message-related features.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

getDefaultLocation

public String getDefaultLocation(BodyPart bodyPart)

Return the default location of the body part.

Parameters:

bodyPart - bodyPart containing attachments

Returns:

String default download path, or null if the bodypart does not carry attachment info.

Throws:

IllegalArgumentException - if bodyPart is null.

ControlledAccessException - - throws if users are not granted to access message-related and file features.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

getDefaultLocations

public String[] getDefaultLocations(BodyPart[] bodyParts)

Return an array of default locations.

Parameters:

bodyParts - an array of bodyPart; each of which contains attachments

Returns:

String array of default download path. An array element is null if a bodypart does not carry attachment info.

Throws:

IllegalArgumentException - if bodyParts or any of an array element is null.

ControlledAccessException - - throws if users are not granted to access message-related and file features.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

getFileContentType

public String getFileContentType(BodyPart bodyPart)

Return file content type. Third parties may call this method to determine if an attachment should be downloaded.

Parameters:

bodyPart - - a bodypart object contains info of the email attachment.

Returns:

String - content type, or null if the bodypart does not carry attachment info.

Throws:

ControlledAccessException - - throws if users are not granted to access message-related features.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

getFileName

public String getFileName(BodyPart bodyPart)

Return the attchment name. Third parties may call this method to determine if an attachment should be downloaded.

Parameters:

bodyPart - - a bodypart object contains info of the email attachment.

Returns:

String - file name, or null if the bodyPart does not carry attachment info.

Throws:

ControlledAccessException - - throws if users are not granted to access message-related features.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

getFileSize

public int getFileSize(BodyPart bodyPart)

Return the file size. Third parties may call this method to determine if an attachment should be downloaded.

Parameters:

bodyPart - - a bodypart object contains info of the email attachment.

Returns:

int - the file size, or zero if the body part does not carry attachment info.

Throws:

UnsupportedOperationException - - throws if the bodyPart does not carry attachment info.

ControlledAccessException - - throws if users are not granted to access message-related feature.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

isDownloaded

public boolean isDownloaded(BodyPart bodyPart)

Check if the file attachment associated with the bodyPart has been downloaded.

Parameters:

bodyPart - - the body part object.

Returns:

true if the attachment has been downloaded; false otherwise.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

getDownloadedFileName

public String getDownloadedFileName(BodyPart bodyPart)

Return the downloaded file path and name.

Parameters:

bodyPart - - a bodypart object contains info of the email attachment.

Returns:

String - file name. Return null if the attachment has yet been downloded or the body part does not carry any attachment info.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

getAttachmentBodyParts

public BodyPart[] getAttachmentBodyParts(Message msg)

Return a BodyPart array whose elements contain info of file attachment.

Parameters:

Message - - the email message object.

Returns:

BodyPart[] - The bodypart elements contain attachment info.

Throws:

ControlledAccessException - - throws if users are not granted to access message-related features.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0