net.rim.blackberry.api.mail
Class AttachmentDownloadManager

java.lang.Object
  extended by 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.

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
Category: Signed AttachmentDownloadManager()
          Constructor to initialize AttachmentDownloadManager instance.
 
Method Summary
Category: Signed  boolean cancelDownload(BodyPart bodyPart)
          Cancel downloading.
Category: Signed  void download(BodyPart bodyPart, String path, DownloadProgressListener listener)
          Download an attachment.
Category: Signed  void download(BodyPart[] bodyParts, String path, DownloadProgressListener listener)
          Download a series of attachments.
Category: Signed  BodyPart[] getAttachmentBodyParts(Message msg)
          Return a BodyPart array whose elements contain info of file attachment.
Category: Signed  String getDefaultLocation(BodyPart bodyPart)
          Return the default location of the body part.
Category: Signed  String[] getDefaultLocations(BodyPart[] bodyParts)
          Return an array of default locations.
Category: Signed  String getDownloadedFileName(BodyPart bodyPart)
          Return the downloaded file path and name.
Category: Signed  String getFileContentType(BodyPart bodyPart)
          Return file content type.
Category: Signed  String getFileName(BodyPart bodyPart)
          Return the attchment name.
Category: Signed  int getFileSize(BodyPart bodyPart)
          Return the file size.
Category: Signed  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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.