net.rim.blackberry.api.mail
Class Session

java.lang.Object
  net.rim.blackberry.api.mail.Session

public final class Session
extends Object

Provides access to email services, storage, and transport.

See Also:

Service, Store, Transport

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
	static void	addDefaultSessionListener(DefaultSessionListener dl) Registers a listener for Default Session change notification.
	static void	addSendListenerForPINMessages(SendListener listener) Adds a listener to the list of listeners that are notified prior to PIN messages being sent.
	static void	addViewListener(ViewListener listener) Registers a listener for view notification.
	static Session	getDefaultInstance() Retrieves this device's default session.
	static Session	getDefaultInstance(ServiceConfiguration sc) Retrieves default session based on provided service configuration.
	static Session	getInstance(ServiceConfiguration sc) Retrieves session by provided service configuration.
	ServiceConfiguration	getServiceConfiguration() Retrieves the service configuration for this service.
	Store	getStore() Retrieves a Store instance to access message storage on this device.
	Transport	getTransport() Retrieves a Transport instance to access the email transport protocol on the handheld.
	static void	removeDefaultSessionListener(DefaultSessionListener listener) De-registers a default Session listener.
	static void	removeSendListenerForPINMessages(SendListener listener) Removes a listener from the list of listeners that are notified prior to PIN messages being sent.
	static void	removeViewListener(ViewListener listener) De-registers a view notification listener.
	static Session	waitForDefaultSession() Retrieves this device's default mail service (blocking).

Methods inherited from class java.lang.Object

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

Method Detail

getDefaultInstance

public static Session getDefaultInstance()

Retrieves this device's default session.

Use this method to retrieve the default session associated with the handheld (typically the enterprise email account).

There is a possible timing issue with startup. If the various service book entries are not yet present on the handheld, this call returns null. This does not always mean that no service is available; it is possible that the service just is not yet registered.

Returns:

The default session instance associated with the handheld, or null if one can't be created (for instance, due to lack of Service Book configuration information on the device).

Throws:

ControlledAccessException - if the application is not granted to access the default email service.

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

addSendListenerForPINMessages

public static void addSendListenerForPINMessages(SendListener listener)

Adds a listener to the list of listeners that are notified prior to PIN messages being sent. If the given listener is null or is already in the list of listeners then this method does nothing.

Parameters:

listener - the listener to add; may be null

See Also:

Session.removeSendListenerForPINMessages(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 7.0.0

removeSendListenerForPINMessages

public static void removeSendListenerForPINMessages(SendListener listener)

Removes a listener from the list of listeners that are notified prior to PIN messages being sent. If the given listener is null or is not in the list of listeners then this method does nothing.

Parameters:

listener - the listener to remove

See Also:

Session.addSendListenerForPINMessages(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 7.0.0

getInstance

public static Session getInstance(ServiceConfiguration sc)

Retrieves session by provided service configuration.

Parameters:

sc - Service configuration information from which to retrieve service.

Returns:

Session associated with provided service configuration, or null if no such service.

Throws:

ControlledAccessException - if the application is not granted to access the email service.

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

waitForDefaultSession

public static Session waitForDefaultSession()
                                     throws NoSuchServiceException

Retrieves this device's default mail service (blocking).

Note: This call blocks indefinitely if no service is available.

Returns:

the device's default mail service; never returns null

Throws:

NoSuchServiceException - If the default service can't be instantiated (usually due to lack of Service Book configuration information on the device).

ControlledAccessException - if the application is not granted to access the email service.

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

getDefaultInstance

public static Session getDefaultInstance(ServiceConfiguration sc)

Retrieves default session based on provided service configuration.

Parameters:

sc - Service configuration for which to retrieve the mail service.

Returns:

Session instance associated with the configuration provided, or null if one can't be created (for instance, because the device doesn't contain valid service book information for the named service).

Throws:

ControlledAccessException - if the application is not granted to access the email service.

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

getServiceConfiguration

public ServiceConfiguration getServiceConfiguration()

Retrieves the service configuration for this service.

Returns:

Service configuration for this service.

Throws:

ControlledAccessException - if the application is not granted to access the email service or the email functionality on the device.

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

getStore

public Store getStore()

Retrieves a Store instance to access message storage on this device.

Returns:

Instance of the store.

Throws:

ControlledAccessException - if the application is not granted to access the email service or the email functionality on the device..

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

getTransport

public Transport getTransport()

Retrieves a Transport instance to access the email transport protocol on the handheld.

Returns:

Transport instance.

Throws:

ControlledAccessException - if the application is not granted to access the email service or the email functionality on the device.

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

addViewListener

public static void addViewListener(ViewListener listener)

Registers a listener for view notification.

Parameters:

vl - View listener to add.

Throws:

ControlledAccessException - if the application is not granted to access the email functionality on the device.

NullPointerException - if ViewListener is null.

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

removeViewListener

public static void removeViewListener(ViewListener listener)

De-registers a view notification listener.

Parameters:

v1 - View listener to remove.

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

addDefaultSessionListener

public static void addDefaultSessionListener(DefaultSessionListener dl)

Registers a listener for Default Session change notification.

Parameters:

dl - DefaultSessionListener listener to add.

Throws:

NullPointerException - if the listener is null.

ControlledAccessException - if the application is not granted to access the email functionality on the device.

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

removeDefaultSessionListener

public static void removeDefaultSessionListener(DefaultSessionListener listener)

De-registers a default Session listener.

Parameters:

d1 - DefaultSessionListener to remove. If the specified listener is not registered or if the parameter is null, this method silently returns with no action.

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