/* $Id: ice_session.h 1242 2007-05-02 11:29:37Z bennylp $ */
/* 
 * Copyright (C) 2003-2005 Benny Prijono <benny@prijono.org>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 */
#ifndef __PJNATH_ICE_SESSION_H__
#define __PJNATH_ICE_SESSION_H__

/**
 * @file ice_session.h
 * @brief ICE session management
 */
#include <pjnath/types.h>
#include <pjnath/stun_session.h>
#include <pj/sock.h>
#include <pj/timer.h>

/**
 * @defgroup PJNATH_ICE Interactive Connectivity Establishment (ICE)
 * @brief Interactive Connectivity Establishment (ICE)
 */


PJ_BEGIN_DECL


/**
 * @defgroup PJNATH_ICE_SESSION ICE Session
 * @brief Transport Independent ICE Session
 * @ingroup PJNATH_ICE
 * @{
 *
 * This module describes #pj_ice_sess, a transport independent ICE session,
 * part of PJNATH - the Open Source NAT helper library.
 *
 * An ICE session, represented by #pj_ice_sess structure, is the lowest 
 * abstraction of ICE in PJNATH, and it is used to perform and manage
 * connectivity checks of transport address candidates <b>within a
 * single media stream</b> (note: this differs from what is described
 * in ICE draft, where an ICE session manages the whole media sessions
 * rather than just a single stream).
 *
 * The ICE session described here is independent from any transports,
 * meaning that the actual network I/O for this session would have to
 * be performed by the application, or higher layer abstraction. 
 * Using this framework, application would give any incoming packets to
 * the ICE session, and it would provide the ICE session with a callback
 * to send outgoing message.
 *
 * For higher abstraction of ICE where transport is included, please 
 * see \ref PJNATH_ICE_STREAM_TRANSPORT.
 */

/**
 * This enumeration describes the type of an ICE candidate.
 */
typedef enum pj_ice_cand_type
{
    /**
     * ICE host candidate. A host candidate represents the actual local
     * transport address in the host.
     */
    PJ_ICE_CAND_TYPE_HOST,

    /**
     * ICE server reflexive candidate, which represents the public mapped
     * address of the local address, and is obtained by sending STUN
     * Binding request from the host candidate to a STUN server.
     */
    PJ_ICE_CAND_TYPE_SRFLX,

    /**
     * ICE peer reflexive candidate, which is the address as seen by peer
     * agent during connectivity check.
     */
    PJ_ICE_CAND_TYPE_PRFLX,

    /**
     * ICE relayed candidate, which represents the address allocated in
     * TURN server.
     */
    PJ_ICE_CAND_TYPE_RELAYED

} pj_ice_cand_type;


/** Forward declaration for pj_ice_sess */
typedef struct pj_ice_sess pj_ice_sess;

/** Forward declaration for pj_ice_sess_check */
typedef struct pj_ice_sess_check pj_ice_sess_check;


/**
 * This structure describes ICE component. 
 * A media stream may require multiple components, each of which has 
 * to work for the media stream as a whole to work.  For media streams
 * based on RTP, there are two components per media stream - one for RTP,
 * and one for RTCP.
 */
typedef struct pj_ice_sess_comp
{
    /**
     * The pointer to ICE check which was nominated for this component.
     * The value will be NULL if a nominated check has not been found
     * for this component.
     */
    pj_ice_sess_check	*valid_check;

    /**
     * The STUN session to be used to send and receive STUN messages for this
     * component.
     */
    pj_stun_session	*stun_sess;

} pj_ice_sess_comp;


/**
 * This structure describes an ICE candidate.
 * ICE candidate is a transport address that is to be tested by ICE
 * procedures in order to determine its suitability for usage for
 * receipt of media.  Candidates also have properties - their type
 * (server reflexive, relayed or host), priority, foundation, and
 * base.
 */
typedef struct pj_ice_sess_cand
{
    /**
     * The component ID of this candidate. Note that component IDs starts
     * with one for RTP and two for RTCP. In other words, it's not zero
     * based.
     */
    pj_uint32_t		 comp_id;

    /**
     * The candidate type, as described in #pj_ice_cand_type enumeration.
     */
    pj_ice_cand_type	 type;

    /**
     * The foundation string, which is an identifier which value will be
     * equivalent for two candidates that are of the same type, share the 
     * same base, and come from the same STUN server. The foundation is 
     * used to optimize ICE performance in the Frozen algorithm.
     */
    pj_str_t		 foundation;

    /**
     * The candidate's priority, a 32-bit unsigned value which value will be
     * calculated by the ICE session when a candidate is registered to the
     * ICE session.
     */
    pj_uint32_t		 prio;

    /**
     * IP address of this candidate. For host candidates, this represents
     * the local address of the socket. For reflexive candidates, the value
     * will be the public address allocated in NAT router for the host
     * candidate and as reported in MAPPED-ADDRESS or XOR-MAPPED-ADDRESS
     * attribute of STUN Binding request. For relayed candidate, the value 
     * will be the address allocated in the TURN server by STUN Allocate
     * request.
     */
    pj_sockaddr		 addr;

    /**
     * Base address of this candidate. "Base" refers to the address an agent 
     * sends from for a particular candidate.  For host candidates, the base
     * is the same as the host candidate itself. For reflexive candidates, 
     * the base is the local IP address of the socket. For relayed candidates,
     * the base address is the transport address allocated in the TURN server
     * for this candidate.
     */
    pj_sockaddr		 base_addr;

    /**
     * Related address, which is used for informational only and is not used
     * in any way by the ICE session.
     */
    pj_sockaddr		 rel_addr;

} pj_ice_sess_cand;


/**
 * This enumeration describes the state of ICE check.
 */
typedef enum pj_ice_sess_check_state
{
    /**
     * A check for this pair hasn't been performed, and it can't
     * yet be performed until some other check succeeds, allowing this
     * pair to unfreeze and move into the Waiting state.
     */
    PJ_ICE_SESS_CHECK_STATE_FROZEN,

    /**
     * A check has not been performed for this pair, and can be
     * performed as soon as it is the highest priority Waiting pair on
     * the check list.
     */
    PJ_ICE_SESS_CHECK_STATE_WAITING,

    /**
     * A check has not been performed for this pair, and can be
     * performed as soon as it is the highest priority Waiting pair on
     * the check list.
     */
    PJ_ICE_SESS_CHECK_STATE_IN_PROGRESS,

    /**
     * A check has not been performed for this pair, and can be
     * performed as soon as it is the highest priority Waiting pair on
     * the check list.
     */
    PJ_ICE_SESS_CHECK_STATE_SUCCEEDED,

    /**
     * A check for this pair was already done and failed, either
     * never producing any response or producing an unrecoverable failure
     * response.
     */
    PJ_ICE_SESS_CHECK_STATE_FAILED

} pj_ice_sess_check_state;


/**
 * This structure describes an ICE connectivity check. An ICE check
 * contains a candidate pair, and will involve sending STUN Binding 
 * Request transaction for the purposes of verifying connectivity. 
 * A check is sent from the local candidate to the remote candidate 
 * of a candidate pair.
 */
struct pj_ice_sess_check
{
    /**
     * Pointer to local candidate entry of this check.
     */
    pj_ice_sess_cand	*lcand;

    /**
     * Pointer to remote candidate entry of this check.
     */
    pj_ice_sess_cand	*rcand;

    /**
     * Check priority.
     */
    pj_timestamp	 prio;

    /**
     * Connectivity check state.
     */
    pj_ice_sess_check_state	 state;

    /**
     * STUN transmit data containing STUN Binding request that was sent 
     * as part of this check. The value will only be set when this check 
     * has a pending transaction, and is used to cancel the transaction
     * when other check has succeeded.
     */
    pj_stun_tx_data	*tdata;

    /**
     * Flag to indicate whether this check is nominated. A nominated check
     * contains USE-CANDIDATE attribute in its STUN Binding request.
     */
    pj_bool_t		 nominated;

    /**
     * When the check failed, this will contain the failure status of the
     * STUN transaction.
     */
    pj_status_t		 err_code;
};


/**
 * This enumeration describes ICE checklist state.
 */
typedef enum pj_ice_sess_checklist_state
{
    /**
     * The checklist is not yet running.
     */
    PJ_ICE_SESS_CHECKLIST_ST_IDLE,

    /**
     * In this state, ICE checks are still in progress for this
     * media stream.
     */
    PJ_ICE_SESS_CHECKLIST_ST_RUNNING,

    /**
     * In this state, ICE checks have completed for this media stream,
     * either successfully or with failure.
     */
    PJ_ICE_SESS_CHECKLIST_ST_COMPLETED

} pj_ice_sess_checklist_state;


/**
 * This structure represents ICE check list, that is an ordered set of 
 * candidate pairs that an agent will use to generate checks.
 */
typedef struct pj_ice_sess_checklist
{
    /**
     * The checklist state.
     */
    pj_ice_sess_checklist_state   state;

    /**
     * Number of candidate pairs (checks).
     */
    unsigned		     count;

    /**
     * Array of candidate pairs (checks).
     */
    pj_ice_sess_check	     checks[PJ_ICE_MAX_CHECKS];

    /**
     * A timer used to perform periodic check for this checklist.
     */
    pj_timer_entry	     timer;

} pj_ice_sess_checklist;


/**
 * This structure contains callbacks that will be called by the ICE
 * session.
 */
typedef struct pj_ice_sess_cb
{
    /**
     * An optional callback that will be called by the ICE session when
     * ICE negotiation has completed, successfully or with failure.
     *
     * @param ice	    The ICE session.
     * @param status	    Will contain PJ_SUCCESS if ICE negotiation is
     *			    successful, or some error code.
     */
    void	(*on_ice_complete)(pj_ice_sess *ice, pj_status_t status);

    /**
     * A mandatory callback which will be called by the ICE session when
     * it needs to send outgoing STUN packet. 
     *
     * @param ice	    The ICE session.
     * @param comp_id	    ICE component ID.
     * @param pkt	    The STUN packet.
     * @param size	    The size of the packet.
     * @param dst_addr	    Packet destination address.
     * @param dst_addr_len  Length of destination address.
     */
    pj_status_t (*on_tx_pkt)(pj_ice_sess *ice, unsigned comp_id, 
			     const void *pkt, pj_size_t size,
			     const pj_sockaddr_t *dst_addr,
			     unsigned dst_addr_len);