net.rim.blackberry.api.sms
Class SMS

java.lang.Object
  net.rim.blackberry.api.sms.SMS

public final class SMS
extends Object

Provides advanced utilities for interaction with the SMS messaging system.

In order to obtain similiar functionality for the MMS messaging system use MMS.

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 SMS send listeners.
	static void	removeSendListener(SendListener listener) Removes a SendListener from the list of SMS 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 SMS send listeners. An SMS send listener will be notified prior to SMS 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 SMS.removeSendListener(net.rim.blackberry.api.sms.SendListener).

Usage of SMS 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:

SMS.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 SMS 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 SMS 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:

SMS.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