/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
 * Copyright (C) 2004 Jive Software. All rights reserved.
 *
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
 */

package org.jivesoftware.messenger;

import org.jivesoftware.messenger.auth.UnauthorizedException;
import java.util.Date;

/**
 * <p>Allows the simple creation, reading, and updating of presence packets.<p>
 * <p>The methods used are mainly convenience interfaces to the various parts
 * of a typical presence packet.</p>
 * <p>A Presence encapsulates information relating to the owning user such as login time, status and
 * last update time.</p>
 *
 * @author Iain Shigeoka
 */
public interface Presence extends XMPPPacket {


    /**
     * <p>Sender is available for messaging.</p>
     */
    Type AVAILABLE = new Type("");
    /**
     * <p>Sender is unavailable for messaging.</p>
     */
    Type UNAVAILABLE = new Type("unavailable");
    /**
     * <p>Sender is available for message reciept but presence should not be broadcast to roster members.</p>
     */
    Type INVISIBLE = new Type("invisible");
    /**
     * <p>Sender wishes to subscribe to recipient's roster.</p>
     */
    Type SUBSCRIBE = new Type("subscribe");
    /**
     * <p>Indicates the sender should be unsubscribed from the recipient's roster.</p>
     */
    Type UNSUBSCRIBE = new Type("unsubscribe");
    /**
     * <p>Sent to indicate a pending subcription request has been filled.</p>
     */
    Type SUBSCRIBED = new Type("subscribed");
    /**
     * <p>Sent to indicate a pending subscription removal request has been filled.</p>
     */
    Type UNSUBSCRIBED = new Type("unsubscribed");
    /**
     * <p>Used when the sender wants to know the recipient's presence.</p>
     */
    Type PROBE = new Type("probe");

    int NO_PRIORITY = -10;

    public static final int STATUS_ONLINE = 0;

    public static final int STATUS_IDLE = 1;

    public static final int STATUS_OFFLINE = 4;

    public static final int STATUS_PROBE = -1;

    /**
     * Available to chat show state
     */
    public static final int SHOW_CHAT = 100;
    /**
     * No show state
     */
    public static final int SHOW_NONE = 101;
    /**
     * Away show state
     */
    public static final int SHOW_AWAY = 102;
    /**
     * "Extended away" show state
     */
    public static final int SHOW_XA = 103;
    /**
     * Do not disturb show state
     */
    public static final int SHOW_DND = 104;

    /**
     * The online/offline status of the user. Being available indicates that the node can be
     * sent packets and does not imply how the presence is propogated or presented to users.
     *
     * @return True if the node is available for messaging
     */
    public boolean isAvailable();

    /**
     * Sets the online/offline status of the user.
     *
     * @param online True if the node is available for messaging
     */
    public void setAvailable(boolean online) throws UnauthorizedException;

    /**
     * Gets the visibility of the user. Invisible nodes can be sent packets, but don't
     * automatically propagate presence to subscribers.
     *
     * @return True if the user is visible
     *         (presence should be automatically propagated to subscribers)
     */
    public boolean isVisible();

    /**
     * Sets the visibility of the user. Invisible nodes can be sent packets, but don't
     * automatically propagate presence to subscribers.
     *
     * @param visible True if the node is visible (presence is broadcast)
     * @throws UnauthorizedException If the caller doesn't have permission
     */
    public void setVisible(boolean visible) throws UnauthorizedException;

    /**
     * Returns the unique ID for this status. The ID in the default implmentation is the user's
     * session ID, which is unique within a single JVM.
     *
     * @return the unique ID for the presence.
     */
    public String getID();

    /**
     * Return the user owning the presence.
     *
     * @return the presence owner.
     */
    public String getUsername();

    /**
     * Return the time when the presence was created.
     *
     * @return the time when the presence was created.
     */
    public Date getLoginTime();

    /**
     * Return the time when the presence was last updated (when the user last visited).
     *
     * @return the time when the presence was last updated (when the user last visited).
     */
    public Date getLastUpdateTime();

    /**
     * Set the time when the presence was last updated (when the user last visited).
     *
     * @param time the time of the last update.
     * @throws UnauthorizedException If the caller doesn't have permissions to make this modification
     */
    public void setLastUpdateTime(Date time) throws UnauthorizedException;

    /**
     * Returns the status of the presence.
     *
     * @return the status of the presence.
     */
    public int getShow();

    /**
     * Sets the status of the user.
     *
     * @param status the status of the user.
     * @throws UnauthorizedException If the caller doesn't have permissions to make this modification
     */
    public void setShow(int status) throws UnauthorizedException;

    /**
     * Gets the free text status of the user. (e.g. "out to lunch").
     *
     * @return The status text for the user or null if none has been set
     */
    public String getStatus();

    /**
     * Sets the free text status of the user. (e.g. "out to lunch").
     *
     * @param status The new status or null if none is set
     * @throws UnauthorizedException
     */
    public void setStatus(String status) throws UnauthorizedException;

    /**
     * Obtain the priority associated with this presence if any
     *
     * @return The priority of this presence or -1 to indicate none set
     */
    public int getPriority();

    /**
     * Sets the new priority for this presence
     *
     * @param priority The new priority value
     * @throws UnauthorizedException If the caller doesn't have the appropriate authorization
     */
    public void setPriority(int priority) throws UnauthorizedException;
}