Starting or Joining a Chat Session

A Chat Session represents the conduit through which all instant messaging communication with a tar-get user passes, so you can only maintain a single Chat Session per contact per IM Session.

New Chat Sessions are created through an IM Session, using the getChatSession or createChatSession methods.

If a Chat Session already exists for a given contact, retrieve it by passing in the username of the person with whom you wish to converse, as shown in the following snippet. If there is no active Chat Session with the specified user, this method returns null.

IChatSession cs = imSession.getChatSession(targetContactEmailAddress);

If you haven’t established a Chat Session with a particular user, create one using the createChatSession method, passing in the target contact’s username. If the IM Session is unable to create a new Chat Session, this method will return null.

IChatSession chatSession = imSession.createChatSession(targetContactEmailAddress);

The following pattern checks to see if there is an existing Chat Session with a target user before creat-ing a new one if necessary:

IChatSession chatSession = imSession.getChatSession(targetContactEmailAddress); if (chatSession == null)

chatSession = imSession.createChatSession(targetContactEmailAddress);

Group Chat Sessions are also represented using the IChatSession interface, but they’re handled a little differently. Group chat functionality is explored in more detail later in this chapter.

Sending Instant Text Messages

Once you have an active Chat Session, use the sendChatMessage method to send messages to the contact(s) in that session, as shown in the following code snippet:

chatSession.sendChatMessage(“Hello World!”);

The message text specified will be transmitted to all the contacts involved in the current Chat Session.

Receiving Instant Text Messages

To listen for incoming messages, implement the IChatListener interface, overriding its newMessageReceived handler. You can register this interface with either a specific Chat Session or the more generic IM Session using the addRemoteChatListener method.

The following snippet shows the skeleton code for creating and registering a new Chat Listener inter-face for both a specific Chat Session and an IM Session. Note that the IChatListener interface includes a Stub class that you should extend when creating your own Chat Listener implementation.

IChatListener chatListener = new IChatListener.Stub() {

public void newMessageReceived(String from, String body) { // TODO Handle incoming messages.

}

Required group chat implementation stubs.

public void convertedToGroupChat(String oldJid,

String groupChatRoom,

long groupId) {}
public void participantJoined(String groupChatRoom, String nickname) {} public void participantLeft(String groupChatRoom, String nickname) {} public void chatClosed(String groupChatRoom) throws RemoteException {} public void chatRead(String arg0) throws RemoteException {}

};

Add Chat Listener to the chat session. chatSession.addRemoteChatListener(chatListener);

Add Chat Listener to the instant messaging session. imSession.addRemoteChatListener(chatListener);

Chat Listeners registered with an IM Session receive every message received by any Chat Session associ-ated with that session, so the message handling here should be fairly generic. In contrast, listeners regis-tered to a single Chat Session are only notified of messages and events relevant to that specific session.

Chat Rooms and Group Chats

Chat rooms are an excellent way to encourage a sense of community within a collaborative or multi-user application.

The GTalk Service supports chat rooms and group chats. They are managed using the same IChatSession interface used for simple P2P Chat Sessions.

To create a new chat room, use the createGroupChatSession method on an IM Session, passing in a nickname for the room and a list of users to invite, as shown in the following snippet:

String nickname = “Android Development”; String[] contacts = { “bill”, “fred” }; imSession.createGroupChatSession(nickname, contacts);

Alternatively, you may want to join group chats that others have invited you to. Use the IGroupChatInvitationListener interface to listen for group chat invitations. Each invitation includes the address and password needed to join an existing chat room.

To join an existing chat room, use the joinGroupChatSession method from an active IM Session, passing in the address of the room you want to join, a nickname for you to identify it, and the pass-word required to join, as shown in the following snippet:

imSession.joinGroupChatSession(address, nickname, password);

The following skeleton code shows how to register a Group Chat Invitation Listener on an active IM Session to listen for, and accept, invitations to join chat rooms.

IGroupChatInvitationListener listener = new IGroupChatInvitationListener.Stub() { public boolean onInvitationReceived(GroupChatInvitation _invite)

throws RemoteException {

String address = _invite.getRoomAddress(); String password = _invite.getPassword(); String nickname = _invite.getInviter(); imSession.joinGroupChatSession(address, nickname, password); return true;

}

};

try {

imSession.addGroupChatInvitationListener(listener);

} catch (RemoteException e) { }