net.rim.blackberry.api.mms
Class MMS

java.lang.Object
  net.rim.blackberry.api.mms.MMS

public final class MMS
extends Object

Provides advanced utilities for interaction with the MMS messaging system.

In order to obtain similar functionality for the SMS messaging system use SMS.

NOTE: Any changes made by an MMS SendListener to the message will be reflected in the message that is sent. For example, if a SendListener adds a recipient and removes another then the removed recipient will not receive the message and the added recipient will. Also, any changes to the message parts will be reflected in the sent message. This affects both MMS message sent via the WMA API (ie. javax.wireless.messaging) and MMS messages sent by the user from the BlackBerry messaging application.

In some previous versions, when MMS messages are sent by the user from the BlackBerry messaging application if the MMS SendListeners modify the message those changes are discarded and the original message is sent. They are, however, still able to forbid the message from being sent by returning false from sendMessage(). Even when this restriction is present, when MMS messages are sent via MessageConnection.send(Message) then the MMS send listeners are fully functional and are able to modify the contents of the message.

See Also:

MessageConnection, MultipartMessage

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 4.6.0

Method Summary
	static void	addSendListener(SendListener listener) Adds a SendListener to the list of MMS send listeners.
	static void	removeSendListener(SendListener listener) Removes a SendListener from the list of MMS send listeners.

Methods inherited from class java.lang.Object

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

Method Detail

addSendListener

public static void addSendListener(SendListener listener)

Adds a SendListener to the list of MMS send listeners. An MMS send listener will be notified prior to MMS messages being added to the send queue. The listener may modify the message before it is sent or deny it from being sent completely by returning false from sendMessage(). Any exceptions thrown by sendMessage() will be silently discarded and will be treated as if the method returned true.

A listener cannot be present multiple times in the list of listeners. If the specified listener is present in the current list of listeners then this method does nothing. Comparison with registered listeners is done using the == operator.

A listener will remain in the list of listeners even after the application exits. That is, a listener is never automatically removed but is only removed when explicity requested via MMS.removeSendListener(net.rim.blackberry.api.mms.SendListener).

Usage of MMS send listeners can be controlled using the "cross-application communication" application control (ApplicationPermissions.PERMISSION_CROSS_APPLICATION_COMMUNICATION). Every invocation of this method checks the application control database and throws ControlledAccessException if permission is denied. Note that the permissions that control this method may change over time and therefore it is advisable to still catch and handle ControlledAccessException even if the application permissions are checked prior to invoking.

Parameters:

listener - The SendListener to add.

Throws:

NullPointerException - if listener is null.

ControlledAccessException - if permissions to modify the list of send listeners is denied.

See Also:

MMS.removeSendListener(SendListener)

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 4.6.0

removeSendListener

public static void removeSendListener(SendListener listener)

Removes a SendListener from the list of MMS send listeners. After a SendListener is removed it will no longer be notified when messages are sent. If the specified listener is not found in the list of listeners then this method does nothing. Comparison with registered listeners is done using the == operator.

Usage of MMS send listeners can be controlled using the "cross-application communication" application control (ApplicationPermissions.PERMISSION_CROSS_APPLICATION_COMMUNICATION). Every invocation of this method checks the application control database and throws ControlledAccessException if permission is denied. Note that the permissions that control this method may change over time and therefore it is advisable to still catch and handle ControlledAccessException even if the application permissions are checked prior to invoking.

Parameters:

listener - The SendListener to remove; if null then this method does nothing.

Throws:

ControlledAccessException - if permissions to modify the list of send listeners is denied.

See Also:

MMS.addSendListener(SendListener)

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 4.6.0