net.rim.blackberry.api.blackberrymessenger
Class BlackBerryMessenger

java.lang.Object
  net.rim.blackberry.api.blackberrymessenger.BlackBerryMessenger

public abstract class BlackBerryMessenger
extends Object

Provides access to the BlackBerryMessenger application. Use this class to get MessengerContact objects from your contact list, register your application as a Service or to know when the local user has accepted a Session with a remote user.

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

Method Summary
	abstract void	addSessionRequestListener(SessionRequestListener listener, ApplicationDescriptor application) Adds a SessionRequestListener to the BlackBerry Messenger application.
	abstract MessengerContact	chooseContact() Provides a UI by which the user can select a contact and then returns that selected contact.
	abstract void	deregisterService(Service service) Removes a registered Service from the BlackBerry Messenger application.
	static BlackBerryMessenger	getInstance() Retrieves the singleton instance of the BlackBerryMessenger instance.
	abstract MessengerContact	getMyContactInfo() Retrieves the current user's contact information
	abstract void	registerService(Service service, String name, ApplicationDescriptor application) Registers a Service with the BlackBerry Messenger application.
	abstract void	removeSessionRequestListener(SessionRequestListener listener) Removes a SessionRequestListener from the BlackBerry Messenger application.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static BlackBerryMessenger getInstance()

Retrieves the singleton instance of the BlackBerryMessenger instance.

Returns:

BlackBerryMessenger instance if BlackBerry Messenger is installed on the BlackBerry device, null otherwise.

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

chooseContact

public abstract MessengerContact chooseContact()

Provides a UI by which the user can select a contact and then returns that selected contact. Note: Third party applications should only call this method from their event thread.

Returns:

The selected contact or null if no contact was selected or if this method was called from a non-event thread.

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

getMyContactInfo

public abstract MessengerContact getMyContactInfo()

Retrieves the current user's contact information

Returns:

The current user's contact information

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

registerService

public abstract void registerService(Service service,
                                     String name,
                                     ApplicationDescriptor application)

Registers a Service with the BlackBerry Messenger application.

Parameters:

service - Service to register. Any given Service can only be registered once. If the Service has already been registered, this method does nothing.

name - The name of the Service. The name provided will appear in a list shown by the "Start Service..." menu item in all conversation windows in the BlackBerry Messenger application. The menu item will only appear if there is one or more Services currenty registered.

application - An ApplicationDescriptor that describes the application registering the Service. The application will be started to run the code in the Service.start() method.

Throws:

IllegalArgumentException - if service is null, if name is null or zero-length or if the ApplicationDescriptor passed in does not refer to the calling application.

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

deregisterService

public abstract void deregisterService(Service service)

Removes a registered Service from the BlackBerry Messenger application. If the Service is not currently registered this method does nothing.

Parameters:

service - Service 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.2.1

addSessionRequestListener

public abstract void addSessionRequestListener(SessionRequestListener listener,
                                               ApplicationDescriptor application)

Adds a SessionRequestListener to the BlackBerry Messenger application. The listener will be notified of all SessionRequestListener events. You must register a SessionRequestListener to receive notification of Sessions accepted by the local user.

The application registered locally must have the same (unique) name as the remote application that will be sending Session requests. The application name is what BlackBerry Messenger uses to distinguish applications.

Parameters:

listener - The listener to register with the BlackBerry Messenger application.

application - An ApplicationDescriptor that describes your application. The BlackBerry Messenger application will start your application using the ApplicationDescriptor before passing the listener any events.

Throws:

IllegalArgumentException - if application does not describe the calling application, or if the application name is zero-length, or if listener 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.2.1

removeSessionRequestListener

public abstract void removeSessionRequestListener(SessionRequestListener listener)

Removes a SessionRequestListener from the BlackBerry Messenger application.

Parameters:

listener - The listener to remove. If this listener has not been added this method does nothing.

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