/*
 * SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
 *
 * Distributable under LGPL license.
 * See terms of license at gnu.org.
 */
package net.java.sip.communicator.service.protocol;

/**
 * The CallParticipantState class reflects the current state of a call
 * participant. In other words when you start calling your grand mother she will
 * be in a INITIATING_CALL state, when her phone rings her state will change to
 * ALERTING_REMOTE_SIDE, and when she replies she will enter a CONNCECTED state.
 *
 * <p>Though not mandatory CallParticipantState would generally have one of the
 * following life cycles
 *
 * <p> In the case with your grand mother that we just described we have:
 * <br>INITIATING_CALL -> CONNECTING -> ALERTING_REMOTE_USER -> CONNECTED -> DISCONNECTED
 *
 * <p> If your granny was already on the phone we have:
 * <br>INITIATING_CALL -> CONNECTING -> BUSY -> DISCONNECTED
 *
 * <p>Whenever someone tries to reach you:
 * <br>INCOMING_CALL -> CONNECTED -> DISCONNECTED
 *
 * <p>A FAILED state is prone to appear at any place in the above diagram and is
 * generally followed by a disconnected state.
 *
 * <p>Information on call participant is shonw in the phone user interface until
 * they enter the DISCONNECTED state. At that point call participant information
 * is automatically removed from the user interface and the call is considered
 * terminated.
 *
 * @author Emil Ivov
 */
public class CallParticipantState
{
    /**
     * This constant value indicates a String representation of the UNKNOWN
     * call state.
     * <br>This constant has the String value "Unknown".
     */
    public static final String _UNKNOWN      = "Unknown";

    /**
     * This constant value indicates that the state of the call participant is
     * is UNKNOWN - which means that there is no information on the state for
     * the time being (this constant should be used as a default value for
     * newly created call participant that don't yet have an attributed call
     * state.
     */
    public static final CallParticipantState UNKNOWN =
                                        new CallParticipantState(_UNKNOWN);

    /**
     * This constant value indicates a String representation of the
     * INITIATING_CALL call state.
     * <br>This constant has the String value "Initiating Call".
     */
    public static final String _INITIATING_CALL      = "Initiating Call";

    /**
     * This constant value indicates that the state of the call participant is
     * is INITIATING_CALL - which means that we're currently trying to open a
     * socket and send our request. In the case of SIP for example we will leave
     * this state the moment we receive a "100 Trying" request from a proxy or
     * the remote side.
     */
    public static final CallParticipantState INITIATING_CALL =
                                        new CallParticipantState(_INITIATING_CALL);

    /**
     * This constant value indicates a String representation of the CONNECTING
     * call state.
     * <br>This constant has the String value "Connecting".
     */
    public static final String _CONNECTING      = "Connecting";

    /**
     * This constant value indicates that the state of the call participant is
     * is CONNECTING - which means that a network connection to that participant
     * is currently being established.
     */
    public static final CallParticipantState CONNECTING =
                                        new CallParticipantState(_CONNECTING);

    /**
     * This constant value indicates a String representation of the
     * ALERTING_REMOTE_SIDE call state.
     * <br>This constant has the String value "Alerting Remote User".
     */
    public static final String _ALERTING_REMOTE_SIDE
                                             = "Alerting Remote User (Ringing)";

    /**
     * This constant value indicates that the state of the call participant is
     * is ALERTING_REMOTE_SIDE - which means that a network connection to that participant
     * has been established and participant's phone is currently alerting the
     * remote user of the current call.
     */
    public static final CallParticipantState ALERTING_REMOTE_SIDE =
                                new CallParticipantState(_ALERTING_REMOTE_SIDE);

    /**
     * This constant value indicates a String representation of the
     * INCOMING_CALL call state.
     * <br>This constant has the String value "Incoming Call".
     */
    public static final String _INCOMING_CALL         = "Incoming Call";

    /**
     * This constant value indicates that the state of the call participant is
     * is INCOMING_CALL - which means that the participant is willing to start
     * a call with us. At that point local side should be playing a sound or a
     * graphical alert (the phone is ringing).
     */
    public static final CallParticipantState INCOMING_CALL
                                         = new CallParticipantState(_INCOMING_CALL);

    /**
     * This constant value indicates a String representation of the CONNECTED
     * call state.
     * <br>This constant has the String value "Connected".
     */
    public static final String _CONNECTED       = "Connected";

    /**
     * This constant value indicates that the state of the call participant is
     * is CONNECTED - which means that there is an ongoing call with that
     * participant.
     */
    public static final CallParticipantState CONNECTED
                                       = new CallParticipantState(_CONNECTED);

    /**
     * This constant value indicates a String representation of the DISCONNECTED
     * call state.
     * <br>This constant has the String value "Disconnected".
     */
    public static final String _DISCONNECTED    = "Disconnected";

    /**
     * This constant value indicates that the state of the call participant is
     * is DISCONNECTET - which means that this participant is not participating :)
     * in the call any more.
     */
    public static final CallParticipantState DISCONNECTED    =
                                      new CallParticipantState(_DISCONNECTED);

    /**
     * This constant value indicates a String representation of the BUSY
     * call state.
     * <br>This constant has the String value "Busy".
     */
    public static final String _BUSY            = "Busy";

    /**
     * This constant value indicates that the state of the call participant is
     * is BUSY - which means that an attempt to establish a call with that
     * participant has been made and that it has been turned down by them (e.g.
     * because they were already in a call).
     */
    public static final CallParticipantState BUSY
                                            = new CallParticipantState(_BUSY);

    /**
     * This constant value indicates a String representation of the FAILED
     * call state.
     * <br>This constant has the String value "Failed".
     */
    public static final String _FAILED          = "Failed";
    /**
     * This constant value indicates that the state of the call participant is
     * is ON_HOLD - which means that an attempt to establish a call with that
     * participant has failed for an unexpected reason.
     */
    public static final CallParticipantState FAILED
                                          = new CallParticipantState(_FAILED);

    /**
     * This constant value indicates a String representation of the ON_HOLD
     * call state.
     * <br>This constant has the String value "On Hold".
     */
    public static final String _ON_HOLD          = "On Hold";
    /**
     * This constant value indicates that the state of the call participant is
     * is ON_HOLD - which means that an attempt to establish a call with that
     * participant has failed for an unexpected reason.
     */
    public static final CallParticipantState ON_HOLD
                                          = new CallParticipantState(_ON_HOLD);

    /**
     * A string representationf this Participant Call State. Could be
     * _CONNECTED, _FAILED, _CALLING and etc.
     */
    private String callStateStr;

    /**
     * Create a participant call state object with a value corresponding to the
     * specified string.
     * @param callParticipantState a string representation of the state.
     */
    private CallParticipantState(String callParticipantState)
    {
        this.callStateStr = callParticipantState;
    }

    /**
     * Returns a String representation of tha CallParticipantSte.
     *
     * @return A string value (one of the _BUSY, _CALLING, _CONNECTED,
     * _CONNECTING, _DISCONNECTED, _FAILED, _RINGING constants) representing
     * this call participant state).
     */
    public String getStateString()
    {
        return callStateStr;
    }

    /**
     * Returns a string represenation of this call state. Strings returned
     * by this method have the following format:
     * CallParticipantState:<STATE_STRING>
     * and are meant to be used for loggin/debugging purposes.
     * @return a string representation of this object.
     */
    public String toString()
    {
        return getClass().getName()+":"+getStateString();
    }
}
