hamsam.api
Interface IMListener

All Superinterfaces:

java.util.EventListener

All Known Implementing Classes:

IMAdapter

public interface IMListener

extends java.util.EventListener

The listener interface for receiving instant messaging events.

The class that is interested in processing an instant messaging event either implements this interface (and all the methods it contains) or extends the abstract IMAdapter class (overriding only the methods of interest).

The listener object created from that class is then registered with the instant messaging framework using the ProtocolManager.setIMListener(IMListener) method.

See Also:

IMAdapter

Method Summary

void	buddyAdded(Buddy buddy) Invoked when a buddy was successfully added to your buddy list.
void	buddyAddFailed(Buddy buddy, java.lang.String reasonMessage) Invoked when an attempt to add a buddy failed.
void	buddyAddRejected(Buddy buddy, java.lang.String reasonMessage) Invoked when an attempt to add a buddy failed because the buddy rejected your request.
Response	buddyAddRequest(Buddy buddy, Buddy myself, java.lang.String message) Invoked when a buddy wants to add you to his / her buddy list.
void	buddyDeleted(Buddy buddy) Invoked when a buddy was successfully deleted from your buddy list.
void	buddyDeleteFailed(Buddy buddy, java.lang.String reasonMessage) Invoked when an attempt to delete a buddy failed.
void	buddyIgnored(Buddy buddy) Invoked when a buddy was successfully ignored.
void	buddyIgnoreFailed(Buddy buddy, java.lang.String reasonMessage) Invoked when an attempt to ignore a buddy failed.
void	buddyListReceived(Protocol protocol, Buddy[] buddies) Invoked when your buddy list is received after a successful login.
void	buddyStatusChanged(Buddy buddy) Invoked when the status information of a buddy is changed.
void	buddyUnignored(Buddy buddy) Invoked when a buddy was successfully unignored.
void	buddyUnignoreFailed(Buddy buddy, java.lang.String reasonMessage) Invoked when an attempt to unignore a buddy failed.
void	conferenceClosed(Conference conf) Invoked when a conference session is closed, either by the protocol or by a buddy who is authorized to do so.
void	conferenceInvitationAccepted(Conference conf, Buddy buddy) Invoked when a buddy accepts a conference invitation.
void	conferenceInvitationDeclined(Conference conf, Buddy buddy, java.lang.String message) Invoked when a buddy declines a conference invitation.
Response	conferenceInvitationReceived(Conference conf, java.lang.String message) Invoked when a buddy invites you for a conference.
void	conferenceMessageReceived(Conference conf, Buddy buddy, Message message) Invoked when an instant message arrives at a conference.
void	conferenceParticipantJoined(Conference conf, Buddy buddy) Invoked when a buddy joins a conference.
void	conferenceParticipantLeft(Conference conf, Buddy buddy) Invoked when a buddy leaves from a conference.
void	connected(Protocol protocol) Invoked when a protocol completes the start up successfully.
void	connectFailed(Protocol protocol, java.lang.String reasonMessage) Invoked when a protocol failed during the start up.
void	connecting(Protocol protocol) Invoked when a protocol attempts start up.
void	disconnected(Protocol protocol) Invoked when a protocol is disconnected.
void	ignoreListReceived(Protocol protocol, Buddy[] buddies) Invoked when a list of buddies whom you have ignored is received, after a successful login.
void	instantMessageReceived(Buddy buddy, Message message) Invoked when an instant message is received.
void	mailNotificationReceived(Protocol protocol, int count, java.lang.String[] from, java.lang.String[] subject) Invoked when an e-mail notification arrives.
void	offlineMessageReceived(Buddy buddy, java.util.Date time, Message message) Invoked when an offline message is received.
void	protocolMessageReceived(Protocol protocol, Message message) Invoked when the underlying protocol system sends a notification to the user.
void	typingStarted(Buddy buddy) Invoked when a buddy starts typing.
void	typingStopped(Buddy buddy) Invoked when a buddy stops typing.

Method Detail

connecting

public void connecting(Protocol protocol)

Invoked when a protocol attempts start up.

Parameters:

protocol - the protocol which is starting up.

connected

public void connected(Protocol protocol)

Invoked when a protocol completes the start up successfully.

Parameters:

protocol - the protocol which was started up.

connectFailed

public void connectFailed(Protocol protocol,
                          java.lang.String reasonMessage)

Invoked when a protocol failed during the start up.

Parameters:

protocol - the protocol which failed.

reasonMessage - the reason for the failure as a string.

disconnected

public void disconnected(Protocol protocol)

Invoked when a protocol is disconnected.

Parameters:

protocol - the protocol which is disconnected.

buddyAddRequest

public Response buddyAddRequest(Buddy buddy,
                                Buddy myself,
                                java.lang.String message)

Invoked when a buddy wants to add you to his / her buddy list. The listener can decide whether to allow or disallow this request. The listener method overriding this method must return a Response object which describes whether the request was allowed or disallowed, and if it was disallowed, an explanation for that.

Not all protocols notify the user when somebody adds him / her to their buddy list. In that case this method will not be invoked. To check whether a protocol supports this, use Protocol.isBuddyAddRequestSupported() method.

Parameters:

buddy - the buddy who is trying to add you.

myself - the buddy object corresponding to this user.

message - the message sent along with this request.

Returns:

the response for this request.

buddyAdded

public void buddyAdded(Buddy buddy)

Invoked when a buddy was successfully added to your buddy list.

Parameters:

buddy - the buddy who was added to your buddy list.

buddyAddRejected

public void buddyAddRejected(Buddy buddy,
                             java.lang.String reasonMessage)

Invoked when an attempt to add a buddy failed because the buddy rejected your request.

Parameters:

buddy - the buddy whom you tried to add to your buddy list.

reasonMessage - the explanation provided by the buddy. If the buddy did not provide any explanation, this will be null.

buddyAddFailed

public void buddyAddFailed(Buddy buddy,
                           java.lang.String reasonMessage)

Invoked when an attempt to add a buddy failed.

Parameters:

buddy - the buddy whom you tried to add to your buddy list.

reasonMessage - the reason for the failure as a string.

buddyDeleted

public void buddyDeleted(Buddy buddy)

Invoked when a buddy was successfully deleted from your buddy list.

Parameters:

buddy - the buddy who was deleted from your buddy list.

buddyDeleteFailed

public void buddyDeleteFailed(Buddy buddy,
                              java.lang.String reasonMessage)

Invoked when an attempt to delete a buddy failed.

Parameters:

buddy - the buddy whom you tried to delete from your buddy list.

reasonMessage - the reason for the failure as a string.

buddyIgnored

public void buddyIgnored(Buddy buddy)

Invoked when a buddy was successfully ignored. Ignored buddies cannot send messages to you.

Not all protocols support ignoring buddies. If a specific protocol does not support ignoring, this method will not be invoked. To identify whether this method is supported, use Protocol.isIgnoreSupported() method.

Parameters:

buddy - the buddy who was ignored.

buddyIgnoreFailed

public void buddyIgnoreFailed(Buddy buddy,
                              java.lang.String reasonMessage)

Invoked when an attempt to ignore a buddy failed. Ignored buddies cannot send messages to you.

Not all protocols support ignoring buddies. If a specific protocol does not support ignoring, this method will not be invoked. To identify whether this method is supported, use Protocol.isIgnoreSupported() method.

Parameters:

buddy - the buddy whom you tried to ignore.

reasonMessage - the reason for the failure as a string.

buddyUnignored

public void buddyUnignored(Buddy buddy)

Invoked when a buddy was successfully unignored. Unignoring a previously ignored buddy permits him / her to send messages to you.

Not all protocols support ignoring buddies. If a specific protocol does not support ignoring, this method will not be invoked. To identify whether this method is supported, use Protocol.isIgnoreSupported() method.

Parameters:

buddy - the buddy who was unignored.

buddyUnignoreFailed

public void buddyUnignoreFailed(Buddy buddy,
                                java.lang.String reasonMessage)

Invoked when an attempt to unignore a buddy failed. Unignoring a previously ignored buddy permits him / her to send messages to you.

Not all protocols support ignoring buddies. If a specific protocol does not support ignoring, this method will not be invoked. To identify whether this method is supported, use Protocol.isIgnoreSupported() method.

Parameters:

buddy - the buddy whom you tried to add to your buddy list.

reasonMessage - the reason for the failure as a string.

buddyListReceived

public void buddyListReceived(Protocol protocol,
                              Buddy[] buddies)

Invoked when your buddy list is received after a successful login. If this method is not invoked, the listener can assume that the buddy list is empty.

Parameters:

protocol - the underlying protocol from which this notification was originated.

buddies - the list of buddies.

ignoreListReceived

public void ignoreListReceived(Protocol protocol,
                               Buddy[] buddies)

Invoked when a list of buddies whom you have ignored is received, after a successful login. If this method is not invoked, the listener can assume that the ignore list is empty.

Not all protocols support ignoring buddies. If a specific protocol does not support ignoring, this method will not be invoked. To identify whether this method is supported, use Protocol.isIgnoreSupported() method.

Parameters:

protocol - the underlying protocol from which this notification was originated.

buddies - the list of buddies who are in your ignore list.

buddyStatusChanged

public void buddyStatusChanged(Buddy buddy)

Invoked when the status information of a buddy is changed. The new status can be accessed using the getStatus() method on the buddy object.

Parameters:

buddy - the buddy whose status information was changed.

instantMessageReceived

public void instantMessageReceived(Buddy buddy,
                                   Message message)

Invoked when an instant message is received.

Parameters:

buddy - the buddy who sent this message.

message - the message that was received.

offlineMessageReceived

public void offlineMessageReceived(Buddy buddy,
                                   java.util.Date time,
                                   Message message)

Invoked when an offline message is received. Not all protocols support offline messages. If a specific protocol does not support offline messages, this method will not be invoked. To check whether a protocol supports offline messages or not, use the Protocol.isOfflineMessageSupported() method.

Parameters:

buddy - the buddy who sent this message.

time - the time when this message was sent by the buddy.

message - the message that was received.

protocolMessageReceived

public void protocolMessageReceived(Protocol protocol,
                                    Message message)

Invoked when the underlying protocol system sends a notification to the user.

Parameters:

protocol - the underlying protocol from which this notification was originated.

message - the message that was received.

typingStarted

public void typingStarted(Buddy buddy)

Invoked when a buddy starts typing. Not all protocols support typing notifications. If a specific protocol does not support typing notifications, this method will not be invoked. To check whether a protocol supports typing notifications or not, use Protocol.isTypingNotifySupported() method.

Parameters:

buddy - the buddy who started typing.

typingStopped

public void typingStopped(Buddy buddy)

Invoked when a buddy stops typing. Not all protocols support typing notifications. If a specific protocol does not support typing notifications, this method will not be invoked. To check whether a protocol supports typing notifications or not, use Protocol.isTypingNotifySupported() method.

Parameters:

buddy - the buddy who stopped typing.

conferenceInvitationReceived

public Response conferenceInvitationReceived(Conference conf,
                                             java.lang.String message)

Invoked when a buddy invites you for a conference. The listener method overriding this method must return a Response object which describes whether the request was allowed or disallowed, and if it was disallowed, an explanation for that.

Not all protocols support conferences. If a specific protocol does not support conferences, this method will not be invoked. To check whether a protocol supports conferences or not, use Protocol.isConferenceSupported() method.

Parameters:

conf - an object representing this conference.

message - an invitation message from the host.

conferenceInvitationDeclined

public void conferenceInvitationDeclined(Conference conf,
                                         Buddy buddy,
                                         java.lang.String message)

Invoked when a buddy declines a conference invitation. Not all protocols support conferences. If a specific protocol does not support conferences, this method will not be invoked. To check whether a protocol supports conferences or not, use Protocol.isConferenceSupported() method.

Parameters:

conf - an object representing this conference.

buddy - the buddy who declined.

message - a message from the buddy explaining why (s)he did not join.

conferenceInvitationAccepted

public void conferenceInvitationAccepted(Conference conf,
                                         Buddy buddy)

Invoked when a buddy accepts a conference invitation. This indicates that this buddy has joined the conference.

Not all protocols support conferences. If a specific protocol does not support conferences, this method will not be invoked. To check whether a protocol supports conferences or not, use Protocol.isConferenceSupported() method.

Parameters:

conf - an object representing this conference.

buddy - the buddy who accepeted the invitation.

conferenceMessageReceived

public void conferenceMessageReceived(Conference conf,
                                      Buddy buddy,
                                      Message message)

Invoked when an instant message arrives at a conference. Not all protocols support conferences. If a specific protocol does not support conferences, this method will not be invoked. To check whether a protocol supports conferences or not, use Protocol.isConferenceSupported() method.

Parameters:

conf - an object representing this conference.

buddy - the buddy who sent this message.

message - the instant message that was received.

conferenceParticipantJoined

public void conferenceParticipantJoined(Conference conf,
                                        Buddy buddy)

Invoked when a buddy joins a conference. Not all protocols support conferences. If a specific protocol does not support conferences, this method will not be invoked. To check whether a protocol supports conferences or not, use Protocol.isConferenceSupported() method.

Parameters:

conf - an object representing this conference.

buddy - the buddy who joined the conference.

conferenceParticipantLeft

public void conferenceParticipantLeft(Conference conf,
                                      Buddy buddy)

Invoked when a buddy leaves from a conference. Not all protocols support conferences. If a specific protocol does not support conferences, this method will not be invoked. To check whether a protocol supports conferences or not, use Protocol.isConferenceSupported() method.

Parameters:

conf - an object representing this conference.

buddy - the buddy who left the conference.

conferenceClosed

public void conferenceClosed(Conference conf)

Invoked when a conference session is closed, either by the protocol or by a buddy who is authorized to do so. Who all can close a conference session is protocol dependant.

Parameters:

conf - the conference that is closed.

mailNotificationReceived

public void mailNotificationReceived(Protocol protocol,
                                     int count,
                                     java.lang.String[] from,
                                     java.lang.String[] subject)

Invoked when an e-mail notification arrives. Many protcols have associated e-mail accounts. When an e-mail arrives in that account, a notification is sent. If a specific protocol does not support e-mail notifications, this method will not be invoked. To check wheter a protocol supports e-mail notifications, use Protocol.isMailNotifySupported() method.

The parameter count specifies the number of mails. If this is -1, it means that the number of mails is not known. The parameter from is a list of e-mail addresseswho are the senders of each e-mail message, in order. The parameter subject is the subject line of each e-mail message, in order. Both these parameters can be null, indicating that the from addresses or subject lines are not known.

Parameters:

protocol - the underlying protocol from which this notification was originated.

count - the number of e-mails received. If this is -1, the number of e-mails is not known.

from - the senders' e-mail addresses. If this is null, the sender addresses are unknown.

subject - the subject lines of the e-mails. If this is null, the subject lines are unknown.