Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Attachments

Create an attachment handler

You can use the AttachmentHandler interface to manage an attachment to an email message that appears in the message list on the BlackBerry device.

The BlackBerry Attachment Service receives all attachments first. Third-party attachment handlers cannot override this default behavior. For more information about the BlackBerry Attachment Service, see the BlackBerry Enterprise Server Administration Guide.

Import the required classes and interfaces.

import net.rim.blackberry.api.mail.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.component.*;

Implement the AttachmentHandler interface to create a custom attachment handler.

public class AttachTest implements AttachmentHandler {...}

Implement the supports(String) method, to specify the content type of the attachment supported by your handler.

public boolean supports(String contentType)
{
   return (contentType.toLowerCase().indexOf("contenttype") != -1 ? true : false);
}

Implement the menuString() method, to specify the text of the menu item that displays when a user selects an attachment.

public String menuString()
{
   return "Custom Attachment Viewer";
}

Implement the run() method to specify what should happen when a user clicks the menu item. In the following code sample, a new screen uses the RichTextField class to display a String representation of the content of the attachment.

public void run(Message m, SupportedAttachmentPart p)
{
   MainScreen view = new MainScreen();
   view.setTitle("Attachment Viewer");
   view.add(new RichTextField(new String((byte[])p.getContent())));
}

Invoke AttachmentHandlerManager.addAttachmentHandler(), to register the attachment handler with the manager. Note that the attachment name must be prefixed with "x-rimdevice" for the attachment to be sent and stored on the BlackBerry device.

AttachmentHandlerManager m = AttachmentHandlerManager.getInstance();
CustomAttachmentHandler ah = new CustomAttachmentHandler();
m.addAttachmentHandler(ah);

Retrieve the contents of an attachment

Import the net.rim.blackberry.api.mail.SupportedAttachmentPart class.

Invoke SupportedAttachmentPart.getContent().

String s = new String((byte[])p.getContent());

Retrieve information about an attachment

Import the net.rim.blackberry.api.mail.SupportedAttachmentPart class.

Invoke the methods of the SupportedAttachmentPart class. The SupportedAttachmentPart class represents an attachment with a corresponding viewer on the BlackBerry device. The UnsupportedAttachmentPart class represents an attachment that does not have a viewer on the BlackBerry device.

Send a message with an attachment

Import the required classes and interfaces.

import net.rim.blackberry.api.mail.Message;
import net.rim.blackberry.api.mail.MessagingException;
import net.rim.blackberry.api.mail.Multipart;
import net.rim.blackberry.api.mail.Session;
import net.rim.blackberry.api.mail.SupportedAttachmentPart;
import net.rim.blackberry.api.mail.Transport;

Create a new Multipart object to create a multipart message.

byte[] data = new byte[256]; 
MultiPart multipart = new MultiPart();

Create a SupportedAttachmentPart object, designating the Multipart object as its parent, to create each component of the screen.

SupportedAttachmentPart attach = new SupportedAttachmentPart( multipart,
"application/x-example", "filename", data);

Invoke MultiPart.addBodyPart(SupportedAttachmentPart) to add each supportedAttachmentPart object to the multipart object.

multipart.addBodyPart(attach); 

Invoke Message.setContent(Multipart) and provide as a parameter the Multipart object to set the content of the attachment.

msg.setContent(multipart);

Invoke Session.getTransport() and store the returned object in a variable of type Transport. The Transport object represents the messaging transport protocol.

Transport trans = Session.getTransport();

Invoke Transport.send(Message).

try 
{
   trans.send(msg);
} 
catch(MessagingException e) 
{
   System.out.println(e.getMessage());
}

Download attachments automatically

When a message arrives in the messages application on the BlackBerry device with an attachment, you can automatically download the attachment and store it on the BlackBerry device.

Before downloading attachments, the AttachmentDownloadManager class validates the attachment. AttachmentDownloadManager throws exceptions if any of the following conditions occur.

  • the application attempts to invoke the download while a download is already in progress
  • the application attempts to download zero length files.
  • the size of the attachment is larder than permitted by the application IT policy or service books
  • attachments are encrypted
  • there is not enough space available on the BlackBerry device or SD card

The AttachmentDownloadManager.download() method performs verification during the download process. If verification errors are found, the method throws an exception. For a list of possible verification errors, see the API reference for the BlackBerry Java Development Environment.

The BlackBerry Attachment Service receives all attachments first. Third-party attachment handlers cannot override this default behavior. For more information about the BlackBerry Attachment Service, see the BlackBerry Enterprise Server Administration Guide.

Import the required classes and interfaces.

import java.io.IOException;
import net.rim.blackberry.api.mail.*;

Implement the DownloadProgressListener interface. Create an instance of the AttachmentDownloadManager class.

public class AutoAttachTest implements DownloadProgressListener 
{
   AttachmentDownloadManager _adm = new AttachmentDownloadManager();

Use the methods available in AttachmentDownloadManager to determine information about the attachment.

public String fileSize = getFileSize(BodyPart bodyPart);
public String fileName = getFileName(BodyPart bodyPart);
public String fileType = getFileContentType(BodyPart bodyPart);
public String filePath = getDownloadedFileName(BodyPart bodyPart);

Invoke AttachmentDownloadManager.download(), to download the attachment.

_adm.download(bodyParts, null, this);

Override the DownloadProgressListener callback methods, to provide updates about the status of the download of the attachment.

private void downloadCancelled(String msg)
{
   BodyPart bodyPart = (BodyPart) element;
   _screen.displayProgress("Failed to download " + _adm.getFileName(bodyPart));
}
private void downloadCompleted(Object element)
{
   BodyPart bodyPart = (BodyPart) element;
   _screen.displayProgress(_adm.getFileName(bodyPart) + " downloaded.");
}
public void updateProgress(Object element, int current, int total)
{
}