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.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getLocation - returns the URL of the file
• getTimestamp - returns when the file was sent
• getMessage - returns the accompanying message

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.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getMessage - returns the accompanying message (Utf8)

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.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getMessage - returns the accompanying message - 'BUZZ!' (Utf8)

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.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getMessage - returns the accompanying message (Utf8)
• getTimestamp - returns when the file was sent

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.

• getMessage - returns the accompanying message, or null (Utf8)
• getService - returns the packet service id, see ServiceConstants
• getCode - returns a chat error code (purpose unknown) or -1;

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

• getException - returns the exception object

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.

• getMail - returns the number of unread mail
• getFrom - returns this mail's From field [*]
• getMessage - returns this mail's message text [*]
• getSubject - returns this mail's subject field [*]

[*] = 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.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getMode - returns whether this is an on or off notification
• getService - returns the type of notification (ie: TYPING, GAME)

Parameters:

ev - The event object

Since:

1.0

contactRequestReceived

public void contactRequestReceived(SessionEvent ev)

Someone wants to add us to their friends list.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id (them!)
• getMessage - returns the accompanying message

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.

• getFrom - returns the sender's Yahoo id
• getMessage - returns the accompanying message

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.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getTopic - returns the intive message (see message)
• getMessage - returns the intive message (see topic)
• getRoom - returns the conference name
• getUsers - returns the id's of users invited

Parameters:

ev - The event object

Since:

1.0

conferenceInviteDeclinedReceived

public void conferenceInviteDeclinedReceived(SessionConferenceEvent ev)

Someone has declined an invite to join our conference.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getRoom - returns the conference name

Parameters:

ev - The event object

Since:

1.0

conferenceLogonReceived

public void conferenceLogonReceived(SessionConferenceEvent ev)

Someone has joined a conference we are part of.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getRoom - returns the conference name

Parameters:

ev - The event object

Since:

1.0

conferenceLogoffReceived

public void conferenceLogoffReceived(SessionConferenceEvent ev)

Someone is leaving a conference we are part of.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getRoom - returns the conference name

Parameters:

ev - The event object

Since:

1.0

conferenceMessageReceived

public void conferenceMessageReceived(SessionConferenceEvent ev)

Someone has sent round a message to the conference members.

• getTo - returns the target Yahoo id (us!)
• getFrom - returns the sender's Yahoo id
• getMessage - returns the message text (Utf8)
• getRoom - returns the conference name

Parameters:

ev - The event object

Since:

1.0

friendsUpdateReceived

public void friendsUpdateReceived(SessionFriendEvent ev)

Friend's details have been updated.

• getFriends - returns an array of YahooUser objects detailing the friend users who have changed.

Parameters:

ev - The event object

Since:

1.0

friendAddedReceived

public void friendAddedReceived(SessionFriendEvent ev)

Successfully added a friend.

• getFriend - returns the YahooUser object of the friend
• getGroup - returns the group they were added to

Parameters:

ev - The event object

Since:

1.0

friendRemovedReceived

public void friendRemovedReceived(SessionFriendEvent ev)

Successfully removed a friend.

• getFriend - returns the YahooUser object of the friend
• getGroup - returns the group they were removed from

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.

• getChatuser/s - the user (or list of users) who joined.
• getLobby - the chat lobby they joined.

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!?!!)

• getChatUser/s - the user (or list of users) who joined.
• getLobby - the chat lobby they joined.

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.

• getChatuser(s) - the user (or list of users) who joined.
• getLobby - the chat lobby they joined.
• getMessage - returns the accompanying message

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.

• getChatUser - the updated user.
• getLobby - the chat lobby they're in.

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.

• getLobby - the chat lobby just departed.

Parameters:

ev - The event object

Since:

1.0