net.rim.blackberry.api.mail
Interface AttachmentHandler

public interface AttachmentHandler

Defines functionality one must implement to perform custom attachment actions.

Guidelines for use

You can implement this interface to create an attachment handler for custom attachments that applications on the BlackBerry device can use.

When an attachment is created, two bits of information are associated with it: an attachment type and a file name. When the attachment is processed through a BlackBerry Enterprise Server, the content type is truncated. For example, the content type application/x-rimdevice-MySpecialContent is truncated to application/. The file name of the attachment is then appended to produce application/MyFileName.ext.

To accommodate this behaviour, creators of attachments should provide them with filenames that encapsulate the content type. For example, x-rimdevice-MySpecialContent-MyFileName.ext.

Each attachment handler must be able to declare (through the AttachmentHandler.supports(java.lang.String) method) which content types it supports. It is important to be as precise as possible when declaring which types can be supported. Your implementation should not simply return true for all x-rimdevice content, but rather the specific content types you can handle. With the previous examples in mind, your method might return true only when tested against the x-rimdevice-MySpecialContent type or the x-rimdevice-MySpecialContent-MyFileName.txt type.

To alert the system that your handler is available for use, it must register using AttachmentHandlerManager.addAttachmentHandler. Because of the way the system processes incoming messages, your handler will only be eligible to handle content that arrives after you register the handler.

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 3.6.0

Method Summary
	String	menuString() Defines the menu item to display for this attachment handler.
	void	run(Message m, SupportedAttachmentPart p) Performs custom processing on an attachment.
	boolean	supports(String contentType) Determines whether this attachment handler accepts a specific content type.

Method Detail

supports

boolean supports(String contentType)

Determines whether this attachment handler accepts a specific content type.

This method is invoked when the BlackBerry device receives an attachment. Implement this method to return true only when tested against the particular content type this handler accepts.

Parameters:

contentType - MIME content type.

Returns:

True if this handler accepts the specified content type; otherwise, false.

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 3.6.0

menuString

String menuString()

Defines the menu item to display for this attachment handler.

This method is invoked when the user selects an attachment in the Messages screen. Implement this method to return the menu item string to present in the Messages screen when the user selects a supported attachment.

Returns:

Menu item string to present in the Messages screen when this attachment is in focus.

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 3.6.0

run

void run(Message m,
         SupportedAttachmentPart p)

Performs custom processing on an attachment.

The system invokes this method when the user selects the corresponding menu item in the Messages screen.

Note: The system invokes this method on the event thread of the Messages application.

Parameters:

m - Message that contains the attachment.

p - Attachment for this attachment handler to process.

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 3.6.0