001/**
002 *
003 * Copyright 2003-2007 Jive Software.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.jivesoftware.smackx.xevent;
019
020import org.jivesoftware.smack.SmackException.NotConnectedException;
021
022import org.jxmpp.jid.Jid;
023
024/**
025 *
026 * A listener that is fired anytime a message event request is received.
027 * Message event requests are received when the received message includes an extension
028 * like this:
029 *
030 * <pre>
031 * &lt;x xmlns='jabber:x:event'&gt;
032 *  &lt;offline/&gt;
033 *  &lt;delivered/&gt;
034 *  &lt;composing/&gt;
035 * &lt;/x&gt;
036 * </pre>
037 *
038 * In this example you can see that the sender of the message requests to be notified
039 * when the user couldn't receive the message because he/she is offline, the message
040 * was delivered or when the receiver of the message is composing a reply.
041 *
042 * @author Gaston Dombiak
043 */
044public interface MessageEventRequestListener {
045
046    /**
047     * Called when a request for message delivered notification is received.
048     *
049     * @param from the user that sent the notification.
050     * @param packetID the id of the message that was sent.
051     * @param messageEventManager the messageEventManager that fired the listener.
052     * @throws NotConnectedException if the XMPP connection is not connected.
053     * @throws InterruptedException if the calling thread was interrupted.
054     */
055    void deliveredNotificationRequested(Jid from, String packetID,
056            MessageEventManager messageEventManager) throws NotConnectedException, InterruptedException;
057
058    /**
059     * Called when a request for message displayed notification is received.
060     *
061     * @param from the user that sent the notification.
062     * @param packetID the id of the message that was sent.
063     * @param messageEventManager the messageEventManager that fired the listener.
064     */
065    void displayedNotificationRequested(Jid from, String packetID,
066            MessageEventManager messageEventManager);
067
068    /**
069     * Called when a request that the receiver of the message is composing a reply notification is
070     * received.
071     *
072     * @param from the user that sent the notification.
073     * @param packetID the id of the message that was sent.
074     * @param messageEventManager the messageEventManager that fired the listener.
075     */
076    void composingNotificationRequested(Jid from, String packetID,
077                MessageEventManager messageEventManager);
078
079    /**
080     * Called when a request that the receiver of the message is offline is received.
081     *
082     * @param from the user that sent the notification.
083     * @param packetID the id of the message that was sent.
084     * @param messageEventManager the messageEventManager that fired the listener.
085     */
086    void offlineNotificationRequested(Jid from, String packetID,
087            MessageEventManager messageEventManager);
088
089}