net.rim.blackberry.api.blackberrymessenger
Interface Session

public interface Session

An object to be used for communication between BlackBerry Messenger contacts.

Sessions have three main states:

• STATE_CLOSED: The Session is closed and cannot be used for any sort of communication. To open a Session, the #sendRequest() method must be invoked. This method will send a request to the MessengerContact associated with this Session and the state will transition to STATE_REQUESTING.
• STATE_REQUESTING: A request to open this Session has been sent. This Session cannot be used for any sort of communication.
• STATE_OPEN: The Session is open and can be used to send data to the associated MessengerContact. To close this session, use the Session.close() method.

  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

  Field Summary
  	static int	STATE_CLOSED A state variable indicating that this Session is currently closed.
  	static int	STATE_OPEN A state variable indicating that this Session is currently open.
  	static int	STATE_REQUESTING A state variable indicating that a request to open this Session has been sent.

  Method Summary
  	void	addListener(SessionListener listener, ApplicationDescriptor application) Adds a SessionListener to this Session.
  	void	close() Closes this Session.
  	void	display(String text) Displays a string in the conversation window for the MessengerContact associated with this Session.
  	void	display(String text, Field field) Displays a Field object in the conversation window for the MessengerContact associated with this Session.
  	MessengerContact	getContact() Returns the MessengerContact associated with this Session.
  	int	getState() Returns the state of this Session.
  	boolean	isOpen() Whether this Session is open or not.
  	void	removeListener(SessionListener listener) Removes a SessionListener from this Session.
  	void	send(Message message) Sends data to this Session's corresponding MessengerContact
  	void	sendRequest(SessionSetupListener listener, ApplicationDescriptor application, String url) Sends a message to this Session's MessengerContact to request that this Session be opened.

  
  
  

  Field Detail

  STATE_CLOSED

  static final int STATE_CLOSED

  A state variable indicating that this Session is currently closed.

  See Also:

  Constant Field Values

  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

  STATE_REQUESTING

  static final int STATE_REQUESTING

  A state variable indicating that a request to open this Session has been sent.

  See Also:

  Constant Field Values

  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

  STATE_OPEN

  static final int STATE_OPEN

  A state variable indicating that this Session is currently open.

  See Also:

  Constant Field Values

  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 Detail

  isOpen

  boolean isOpen()

  Whether this Session is open or not.

  Returns:

  true if this Session is open, false 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

  getState

  int getState()

  Returns the state of this Session.

  Returns:

  The state of this Session.

  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

  close

  void close()

  Closes this Session. Applications will no longer be able to send data using this Session. The remote user's application will be notified and their corresponding Session will also be closed.

  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

  send

  void send(Message message)

  Sends data to this Session's corresponding MessengerContact

  Parameters:

  message - A Message containing information to be sent.

  Throws:

  IllegalStateException - If this Session is closed.

  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

  addListener

  void addListener(SessionListener listener,
                   ApplicationDescriptor application)

  Adds a SessionListener to this Session.

  Parameters:

  listener - The listener to be added. If this listener has already been added this method does nothing.

  application - An ApplicationDescriptor describing your application. Your application will be started using the descriptor before notifications are passed to the corresponding listener.

  Throws:

  IllegalArgumentException - If application is null or does not describe the registering application, 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

  removeListener

  void removeListener(SessionListener listener)

  Removes a SessionListener from this Session. If the SessionListener is not already added, this method does nothing.

  Parameters:

  listener - The listener to be removed.

  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

  sendRequest

  void sendRequest(SessionSetupListener listener,
                   ApplicationDescriptor application,
                   String url)

  Sends a message to this Session's MessengerContact to request that this Session be opened. After calling this method the state of this Session will be set to STATE_REQUESTING. If the remote user accepts the request, the state will be set to STATE_OPEN. If the remote user declines, or if there is another error, the state will return to STATE_CLOSED.

  Parameters:

  listener - A SessionSetupListener that will be notified of the request's status. Must not be null.

  application - An ApplicationDescriptor that describes your application. Your application will be started using the descriptor before any listener events are given to the specified SessionSetupListener.

  The application provided must be named uniquely, and the remote contact's device must have already registered an application with the same unique name with a SessionRequestListener for the request to complete successfully.

  url - If the remote user does not have an application on their device that has registered the same unique name as this application, the URL will be displayed to the remote user. The URL should provide the user the ability to download this application.

  url can be null if no URL is needed.

  Throws:

  IllegalStateException - If this Session is in the STATE_REQUESTING state.

  IllegalArgumentException - If listener is null, if application is null or if application does not describe 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

  display

  void display(String text)

  Displays a string in the conversation window for the MessengerContact associated with this Session.

  Parameters:

  text - The text to display in the conversation window

  Throws:

  IllegalStateException - If this Session is closed.

  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

  display

  void display(String text,
               Field field)

  Displays a Field object in the conversation window for the MessengerContact associated with this Session.

  Parameters:

  text - A textual description of the field. To be used as a preview in the contact list screen.

  field - The Field to display in the conversation window.

  Throws:

  IllegalStateException - If this Session is closed.

  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

  getContact

  MessengerContact getContact()

  Returns the MessengerContact associated with this Session.

  Returns:

  A MessengerContact object.

  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