ice_session.h

Go to the documentation of this file.

/* $Id$ */
/* 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 * Copyright (C) 2003-2008 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__

#include <pjnath/types.h>
#include <pjnath/stun_session.h>
#include <pjnath/errno.h>
#include <pj/sock.h>
#include <pj/timer.h>

PJ_BEGIN_DECL


typedef struct pj_ice_sess_checklist pj_ice_sess_checklist;

typedef enum pj_ice_cand_type
{
    PJ_ICE_CAND_TYPE_HOST,

    PJ_ICE_CAND_TYPE_SRFLX,

    PJ_ICE_CAND_TYPE_PRFLX,

    PJ_ICE_CAND_TYPE_RELAYED,

    PJ_ICE_CAND_TYPE_MAX

} pj_ice_cand_type;


typedef struct pj_ice_sess pj_ice_sess;

typedef struct pj_ice_sess_check pj_ice_sess_check;

typedef struct pj_ice_sess_cand pj_ice_sess_cand;

typedef struct pj_ice_sess_comp
{
    pj_ice_sess_check   *valid_check;

    pj_ice_sess_check   *nominated_check;

    pj_stun_session     *stun_sess;

} pj_ice_sess_comp;


typedef struct pj_ice_msg_data
{
    unsigned    transport_id;

    pj_bool_t   has_req_data;

    union data {
        struct request_data {
            pj_ice_sess             *ice;   
            pj_ice_sess_checklist   *clist; 
            unsigned                 ckid;  
            pj_ice_sess_cand        *lcand; 
            pj_ice_sess_cand        *rcand; 
        } req;
    } data;

} pj_ice_msg_data;


struct pj_ice_sess_cand
{
    unsigned             id;

    pj_ice_cand_type     type;

    pj_status_t          status;

    pj_uint8_t           comp_id;

    pj_uint8_t           transport_id;

    pj_uint16_t          local_pref;

    pj_str_t             foundation;

    pj_uint32_t          prio;

    pj_sockaddr          addr;

    pj_sockaddr          base_addr;

    pj_sockaddr          rel_addr;

};


typedef enum pj_ice_sess_check_state
{
    PJ_ICE_SESS_CHECK_STATE_FROZEN,

    PJ_ICE_SESS_CHECK_STATE_WAITING,

    PJ_ICE_SESS_CHECK_STATE_IN_PROGRESS,

    PJ_ICE_SESS_CHECK_STATE_SUCCEEDED,

    PJ_ICE_SESS_CHECK_STATE_FAILED

} pj_ice_sess_check_state;


struct pj_ice_sess_check
{
    pj_ice_sess_cand    *lcand;

    pj_ice_sess_cand    *rcand;

    int                  foundation_idx;

    pj_timestamp         prio;

    pj_ice_sess_check_state      state;

    pj_stun_tx_data     *tdata;

    pj_bool_t            nominated;

    pj_status_t          err_code;
};


typedef enum pj_ice_sess_checklist_state
{
    PJ_ICE_SESS_CHECKLIST_ST_IDLE,

    PJ_ICE_SESS_CHECKLIST_ST_RUNNING,

    PJ_ICE_SESS_CHECKLIST_ST_COMPLETED

} pj_ice_sess_checklist_state;


struct pj_ice_sess_checklist
{
    pj_ice_sess_checklist_state   state;

    unsigned                 count;

    pj_ice_sess_check        checks[PJ_ICE_MAX_CHECKS];

    unsigned                 foundation_cnt;

    pj_str_t                 foundation[PJ_ICE_MAX_CHECKS * 2];

    pj_timer_entry           timer;

};


typedef struct pj_ice_sess_cb
{
    void        (*on_valid_pair)(pj_ice_sess *ice);

    void        (*on_ice_complete)(pj_ice_sess *ice, pj_status_t status);

    pj_status_t (*on_tx_pkt)(pj_ice_sess *ice, unsigned comp_id, 
                             unsigned transport_id,
                             const void *pkt, pj_size_t size,
                             const pj_sockaddr_t *dst_addr,
                             unsigned dst_addr_len);

    void        (*on_rx_data)(pj_ice_sess *ice, unsigned comp_id,
                              unsigned transport_id, 
                              void *pkt, pj_size_t size,
                              const pj_sockaddr_t *src_addr,
                              unsigned src_addr_len);
} pj_ice_sess_cb;


typedef enum pj_ice_sess_role
{
    PJ_ICE_SESS_ROLE_UNKNOWN,

    PJ_ICE_SESS_ROLE_CONTROLLED,

    PJ_ICE_SESS_ROLE_CONTROLLING

} pj_ice_sess_role;


typedef struct pj_ice_rx_check
{
    PJ_DECL_LIST_MEMBER(struct pj_ice_rx_check); 
    unsigned             comp_id;       
    unsigned             transport_id;  
    pj_sockaddr          src_addr;      
    unsigned             src_addr_len;  
    pj_bool_t            use_candidate; 
    pj_uint32_t          priority;      
    pj_stun_uint64_attr *role_attr;     
} pj_ice_rx_check;


typedef enum pj_ice_sess_trickle
{
    PJ_ICE_SESS_TRICKLE_DISABLED,

    PJ_ICE_SESS_TRICKLE_HALF,

    PJ_ICE_SESS_TRICKLE_FULL

} pj_ice_sess_trickle;


typedef struct pj_ice_sess_options
{
    pj_bool_t           aggressive;

    unsigned            nominated_check_delay;

    int                 controlled_agent_want_nom_timeout;

    pj_ice_sess_trickle trickle;

} pj_ice_sess_options;


struct pj_ice_sess
{
    char                obj_name[PJ_MAX_OBJ_NAME];  
    pj_pool_t           *pool;                      
    void                *user_data;                 
    pj_grp_lock_t       *grp_lock;                  
    pj_ice_sess_role     role;                      
    pj_ice_sess_options  opt;                       
    pj_timestamp         tie_breaker;               
    pj_uint8_t          *prefs;                     
    pj_bool_t            is_nominating;             
    pj_bool_t            is_complete;               
    pj_bool_t            is_destroying;             
    pj_bool_t            valid_pair_found;          
    pj_bool_t            is_trickling;              
    pj_status_t          ice_status;                
    pj_timer_entry       timer;                     
    pj_timer_entry       timer_end_of_cand;         
    pj_ice_sess_cb       cb;                        
    pj_stun_config       stun_cfg;                  
    /* STUN credentials */
    pj_str_t             tx_ufrag;                  
    pj_str_t             tx_uname;                  
    pj_str_t             tx_pass;                   
    pj_str_t             rx_ufrag;                  
    pj_str_t             rx_uname;                  
    pj_str_t             rx_pass;                   
    /* Components */
    unsigned             comp_cnt;                  
    pj_ice_sess_comp     comp[PJ_ICE_MAX_COMP];     
    unsigned             comp_ka;                   
    /* Local candidates */
    unsigned             lcand_cnt;                 
    pj_ice_sess_cand     lcand[PJ_ICE_MAX_CAND];    
    unsigned             lcand_paired;              
    /* Remote candidates */
    unsigned             rcand_cnt;                 
    pj_ice_sess_cand     rcand[PJ_ICE_MAX_CAND];    
    unsigned             rcand_paired;              
    pj_ice_msg_data      tp_data[PJ_ICE_MAX_STUN + PJ_ICE_MAX_TURN];

    /* List of eearly checks */
    pj_ice_rx_check      early_check;               
    /* Checklist */
    pj_ice_sess_checklist clist;                    
    /* Valid list */
    pj_ice_sess_checklist valid_list;               
    union {
        char txt[128];
        char errmsg[PJ_ERR_MSG_SIZE];
    } tmp;
};


PJ_DECL(const char*) pj_ice_get_cand_type_name(pj_ice_cand_type type);


PJ_DECL(const char*) pj_ice_sess_role_name(pj_ice_sess_role role);


PJ_DECL(void) pj_ice_calc_foundation(pj_pool_t *pool,
                                     pj_str_t *foundation,
                                     pj_ice_cand_type type,
                                     const pj_sockaddr *base_addr);

PJ_DECL(void) pj_ice_sess_options_default(pj_ice_sess_options *opt);

PJ_DECL(pj_status_t) pj_ice_sess_create(pj_stun_config *stun_cfg,
                                        const char *name,
                                        pj_ice_sess_role role,
                                        unsigned comp_cnt,
                                        const pj_ice_sess_cb *cb,
                                        const pj_str_t *local_ufrag,
                                        const pj_str_t *local_passwd,
                                        pj_grp_lock_t *grp_lock,
                                        pj_ice_sess **p_ice);

PJ_DECL(pj_status_t) pj_ice_sess_get_options(pj_ice_sess *ice,
                                             pj_ice_sess_options *opt);

PJ_DECL(pj_status_t) pj_ice_sess_set_options(pj_ice_sess *ice,
                                             const pj_ice_sess_options *opt);


PJ_DECL(pj_status_t) pj_ice_sess_detach_grp_lock(pj_ice_sess *ice,
                                                 pj_grp_lock_handler *handler);


PJ_DECL(pj_status_t) pj_ice_sess_destroy(pj_ice_sess *ice);


PJ_DECL(pj_status_t) pj_ice_sess_change_role(pj_ice_sess *ice,
                                             pj_ice_sess_role new_role);


PJ_DECL(pj_status_t) pj_ice_sess_set_prefs(pj_ice_sess *ice,
                                           const pj_uint8_t prefs[4]);



PJ_DECL(pj_status_t) pj_ice_sess_add_cand(pj_ice_sess *ice,
                                          unsigned comp_id,
                                          unsigned transport_id,
                                          pj_ice_cand_type type,
                                          pj_uint16_t local_pref,
                                          const pj_str_t *foundation,
                                          const pj_sockaddr_t *addr,
                                          const pj_sockaddr_t *base_addr,
                                          const pj_sockaddr_t *rel_addr,
                                          int addr_len,
                                          unsigned *p_cand_id);

PJ_DECL(pj_status_t) pj_ice_sess_find_default_cand(pj_ice_sess *ice,
                                                   unsigned comp_id,
                                                   int *p_cand_id);

PJ_DECL(pj_status_t) 
pj_ice_sess_create_check_list(pj_ice_sess *ice,
                              const pj_str_t *rem_ufrag,
                              const pj_str_t *rem_passwd,
                              unsigned rem_cand_cnt,
                              const pj_ice_sess_cand rem_cand[]);


PJ_DECL(pj_status_t) 
pj_ice_sess_update_check_list(pj_ice_sess *ice,
                              const pj_str_t *rem_ufrag,
                              const pj_str_t *rem_passwd,
                              unsigned rem_cand_cnt,
                              const pj_ice_sess_cand rem_cand[],
                              pj_bool_t trickle_done);


PJ_DECL(pj_status_t) pj_ice_sess_start_check(pj_ice_sess *ice);


PJ_DECL(pj_status_t) pj_ice_sess_send_data(pj_ice_sess *ice,
                                           unsigned comp_id,
                                           const void *data,
                                           pj_size_t data_len);

PJ_DECL(pj_status_t) pj_ice_sess_on_rx_pkt(pj_ice_sess *ice,
                                           unsigned comp_id,
                                           unsigned transport_id,
                                           void *pkt,
                                           pj_size_t pkt_size,
                                           const pj_sockaddr_t *src_addr,
                                           int src_addr_len);



PJ_END_DECL


#endif  /* __PJNATH_ICE_SESSION_H__ */