ymsg.network.event
Interface SessionListener

All Known Implementing Classes:
SessionAdapter

public interface SessionListener

This interface defines the callbacks necessary for the jYMSG API to communitcate with the client employing it. Most of these method will be called as a direct result of 'packets' arriving from the Yahoo server to the client. Note: this API provides an abstract layer of Yahoo's IM protocol - the methods here to do not necessarily map directly to specific 'packet' types.

Because of the baffling array of different types of data which can be received, the API employs a basic event class, SessionEvent for many events types, but specific subclasses when particular fields need to be added. The fields which are 'active' (not null) for any given event are listed, by way of their accessor methods.

Since:
1.0

Method Summary
 void buzzReceived(SessionEvent ev)
          Someone has sent us a buzz message.
 void chatConnectionClosed(SessionEvent ev)
          The connection to a chat lobby has been lost.
 void chatLogoffReceived(SessionChatEvent ev)
          Someone has left the chatroom lobby we are currently connected to.
 void chatLogonReceived(SessionChatEvent ev)
          Someone has joined the chatroom lobby we are currently connected to.
 void chatMessageReceived(SessionChatEvent ev)
          Someone has sent a message to the chatroom lobby we are currently connected to.
 void chatUserUpdateReceived(SessionChatEvent ev)
          An update to a chat user's details has been received.
 void conferenceInviteDeclinedReceived(SessionConferenceEvent ev)
          Someone has declined an invite to join our conference.
 void conferenceInviteReceived(SessionConferenceEvent ev)
          Someone is inviting us to join a conference.
 void conferenceLogoffReceived(SessionConferenceEvent ev)
          Someone is leaving a conference we are part of.
 void conferenceLogonReceived(SessionConferenceEvent ev)
          Someone has joined a conference we are part of.
 void conferenceMessageReceived(SessionConferenceEvent ev)
          Someone has sent round a message to the conference members.
 void connectionClosed(SessionEvent ev)
          Yahoo connection broken.
 void contactRejectionReceived(SessionEvent ev)
          Someone has rejected our attempts to add them to our friends list.
 void contactRequestReceived(SessionEvent ev)
          Someone wants to add us to their friends list.
 void errorMessageReceived(SessionErrorEvent ev)
          A protocol level error occured.
 void fileTransferReceived(SessionFileTransferEvent ev)
          This will be called when the API becomes aware that someone is attempting to send us a file.
 void friendAddedReceived(SessionFriendEvent ev)
          Successfully added a friend.
 void friendRemovedReceived(SessionFriendEvent ev)
          Successfully removed a friend.
 void friendsUpdateReceived(SessionFriendEvent ev)
          Friend's details have been updated.
 void inputExceptionThrown(SessionExceptionEvent ev)
          An internal API exception occured on the input thread.
 void listReceived(SessionEvent ev)
          The complete groups/friends list update has been received.
 void messageReceived(SessionEvent ev)
          Someone has sent us an instant messenger (personal) message.
 void newMailReceived(SessionNewMailEvent ev)
          Yahoo tells us we have unread Yahoo mail.
 void notifyReceived(SessionNotifyEvent ev)
          Yahoo server wants to notify us of something.
 void offlineMessageReceived(SessionEvent ev)
          Yahoo tells us about a message sent while we were away.
 

Method Detail

fileTransferReceived

public void fileTransferReceived(SessionFileTransferEvent ev)
This will be called when the API becomes aware that someone is attempting to send us a file.

Parameters:
ev - The event object
Since:
1.0

connectionClosed

public void connectionClosed(SessionEvent ev)
Yahoo connection broken. This method can be called in four circumstances:
  1. At some point after we call logout on the session, as confirmation that the session is now dead.
  2. At some point before or after login returns, when there has been a problem logging in (for example, incorrect password).
  3. When network problems mean the connection to Yahoo servers is lost.
  4. When Yahoo wishes to throw us off of the system for any reason (for example another client attempts to log in with the same Yahoo id - the original client is terminated.)

Parameters:
ev - The event object
Since:
1.0

listReceived

public void listReceived(SessionEvent ev)
The complete groups/friends list update has been received. This typically is generated sometime after refreshFriends has been called on the Session object. Note: the list is also received as part of the login process, but this API supresses that event if it occures before login has finished (which it always does!)

Parameters:
ev - The event object
Since:
1.0

messageReceived

public void messageReceived(SessionEvent ev)
Someone has sent us an instant messenger (personal) message.

Parameters:
ev - The event object
Since:
1.0

buzzReceived

public void buzzReceived(SessionEvent ev)
Someone has sent us a buzz message. The official Yahoo client prints a 'buzz' type message and jiggles the client IM window for a short time to simulate vibrations. You, however, may choose to handle such messages differently.

Parameters:
ev - The event object
Since:
1.0

offlineMessageReceived

public void offlineMessageReceived(SessionEvent ev)
Yahoo tells us about a message sent while we were away.

Parameters:
ev - The event object
Since:
1.0

errorMessageReceived

public void errorMessageReceived(SessionErrorEvent ev)
A protocol level error occured. Typically Yahoo is flagging an error in a recent operation.

Parameters:
ev - The event object
Since:
1.0

inputExceptionThrown

public void inputExceptionThrown(SessionExceptionEvent ev)
An internal API exception occured on the input thread. The input thread runs in parallel with the main application. If it throws an exception there is no direct way to report this to the application layer - this event provides a mechanism for reporting such exceptions. (Under normal circumstances the input thread should never throw exceptions, but just in case...)

Parameters:
ev - The event object
Since:
1.0

newMailReceived

public void newMailReceived(SessionNewMailEvent ev)
Yahoo tells us we have unread Yahoo mail. Note: this informs us of the number of unread e-mails, but documentation suggests that it may alternatively contain the details of an e-mail itself. [*] = These fields are set only if the count, getMail is zero.

Parameters:
ev - The event object
Since:
1.0

notifyReceived

public void notifyReceived(SessionNotifyEvent ev)
Yahoo server wants to notify us of something.

Parameters:
ev - The event object
Since:
1.0

contactRequestReceived

public void contactRequestReceived(SessionEvent ev)
Someone wants to add us to their friends list.

Parameters:
ev - The event object
Since:
1.0

contactRejectionReceived

public void contactRejectionReceived(SessionEvent ev)
Someone has rejected our attempts to add them to our friends list.

Parameters:
ev - The event object
Since:
1.0

conferenceInviteReceived

public void conferenceInviteReceived(SessionConferenceEvent ev)
Someone is inviting us to join a conference. Use the Session methods, acceptConferenceInvite to accept or declineSessionInvite to decline.

Parameters:
ev - The event object
Since:
1.0

conferenceInviteDeclinedReceived

public void conferenceInviteDeclinedReceived(SessionConferenceEvent ev)
Someone has declined an invite to join our conference.

Parameters:
ev - The event object
Since:
1.0

conferenceLogonReceived

public void conferenceLogonReceived(SessionConferenceEvent ev)
Someone has joined a conference we are part of.

Parameters:
ev - The event object
Since:
1.0

conferenceLogoffReceived

public void conferenceLogoffReceived(SessionConferenceEvent ev)
Someone is leaving a conference we are part of.

Parameters:
ev - The event object
Since:
1.0

conferenceMessageReceived

public void conferenceMessageReceived(SessionConferenceEvent ev)
Someone has sent round a message to the conference members.

Parameters:
ev - The event object
Since:
1.0

friendsUpdateReceived

public void friendsUpdateReceived(SessionFriendEvent ev)
Friend's details have been updated.

Parameters:
ev - The event object
Since:
1.0

friendAddedReceived

public void friendAddedReceived(SessionFriendEvent ev)
Successfully added a friend.

Parameters:
ev - The event object
Since:
1.0

friendRemovedReceived

public void friendRemovedReceived(SessionFriendEvent ev)
Successfully removed a friend.

Parameters:
ev - The event object
Since:
1.0

chatLogonReceived

public void chatLogonReceived(SessionChatEvent ev)
Someone has joined the chatroom lobby we are currently connected to. Note: the protocol supports more than one user listed in a single chat packet (and therefore a single event) - but this facility appears not to be used.

Parameters:
ev - The event object
Since:
1.0

chatLogoffReceived

public void chatLogoffReceived(SessionChatEvent ev)
Someone has left the chatroom lobby we are currently connected to. Note: the protocol supports more than one user listed in a single chat packet (and therefore a single event) - but this facility appears not to be used. Also: beware - it appears possible to very occassionally receive logoff packets for users we were never told about in the first place! Perhaps they joined simultaneously with us, and were never included in the initial list of users, or subsequent updates? (Or maybe Yahoo's chat server is buggy!?!!)

Parameters:
ev - The event object
Since:
1.0

chatMessageReceived

public void chatMessageReceived(SessionChatEvent ev)
Someone has sent a message to the chatroom lobby we are currently connected to. Note: the protocol supports more than one user listed in a single chat packet (and therefore a single event) - but this facility appears not to be used. Also: it may be possible to receive messages from users we were never told about - see chatLogoffReceived above. Note: this method will also be called if a packet of code 0x20 is received (an old-style YCHT personal message packet?).

Parameters:
ev - The event object
Since:
1.0

chatUserUpdateReceived

public void chatUserUpdateReceived(SessionChatEvent ev)
An update to a chat user's details has been received.

Parameters:
ev - The event object
Since:
1.0

chatConnectionClosed

public void chatConnectionClosed(SessionEvent ev)
The connection to a chat lobby has been lost. For example, if the chat system timed us out after a period of inactivity.

Parameters:
ev - The event object
Since:
1.0