Ignore:
Timestamp:
Mar 28, 2007 3:49:48 PM (17 years ago)
Author:
bennylp
Message:

Updated projects and Makefiles with the new pjnath library

File:
1 moved

Legend:

Unmodified
Added
Removed

  • pjproject/trunk/pjnath/include/pjnath/ice_session.h

    r1110 r1111  
    2121 
    2222/** 
    23  * @file ice.h 
     23 * @file ice_session.h 
    2424 * @brief ICE session management 
    2525 */ 
    … …  
    4444 * @{ 
    4545 * 
    46  * This module describes #pj_ice, a transport independent ICE session, 
     46 * This module describes #pj_ice_sess, a transport independent ICE session, 
    4747 * part of PJNATH - the Open Source NAT helper library. 
    4848 * 
    49  * An ICE session, represented by #pj_ice structure, is the lowest  
     49 * An ICE session, represented by #pj_ice_sess structure, is the lowest  
    5050 * abstraction of ICE in PJNATH, and it is used to perform and manage 
    5151 * connectivity checks of transport address candidates <b>within a 
    … …  
    7070typedef enum pj_ice_cand_type 
    7171{ 
    72     PJ_ICE_CAND_TYPE_HOST,      /**< ICE host candidate.                */ 
    73     PJ_ICE_CAND_TYPE_SRFLX,     /**< ICE server reflexive candidate.    */ 
    74     PJ_ICE_CAND_TYPE_PRFLX,     /**< ICE peer reflexive candidate.      */ 
    75     PJ_ICE_CAND_TYPE_RELAYED    /**< ICE relayed candidate.             */ 
     72    /** 
     73     * ICE host candidate. A host candidate represents the actual local 
     74     * transport address in the host. 
     75     */ 
     76    PJ_ICE_CAND_TYPE_HOST, 
     77 
     78    /** 
     79     * ICE server reflexive candidate, which represents the public mapped 
     80     * address of the local address, and is obtained by sending STUN 
     81     * Binding request from the host candidate to a STUN server. 
     82     */ 
     83    PJ_ICE_CAND_TYPE_SRFLX, 
     84 
     85    /** 
     86     * ICE peer reflexive candidate, which is the address as seen by peer 
     87     * agent during connectivity check. 
     88     */ 
     89    PJ_ICE_CAND_TYPE_PRFLX, 
     90 
     91    /** 
     92     * ICE relayed candidate, which represents the address allocated in 
     93     * TURN server. 
     94     */ 
     95    PJ_ICE_CAND_TYPE_RELAYED 
     96 
    7697} pj_ice_cand_type; 
    7798 
    … …  
    89110}; 
    90111 
    91 /** Forward declaration for pj_ice */ 
    92 typedef struct pj_ice pj_ice; 
    93  
    94 /** Forward declaration for pj_ice_check */ 
    95 typedef struct pj_ice_check pj_ice_check; 
     112/** Forward declaration for pj_ice_sess */ 
     113typedef struct pj_ice_sess pj_ice_sess; 
     114 
     115/** Forward declaration for pj_ice_sess_check */ 
     116typedef struct pj_ice_sess_check pj_ice_sess_check; 
    96117 
    97118 
    … …  
    103124 * and one for RTCP. 
    104125 */ 
    105 typedef struct pj_ice_comp 
     126typedef struct pj_ice_sess_comp 
    106127{ 
    107128    /** 
    … …  
    110131     * for this component. 
    111132     */ 
    112     pj_ice_check        *valid_check; 
    113  
    114 } pj_ice_comp; 
     133    pj_ice_sess_check   *valid_check; 
     134 
     135} pj_ice_sess_comp; 
    115136 
    116137 
    … …  
    123144 * base. 
    124145 */ 
    125 typedef struct pj_ice_cand 
     146typedef struct pj_ice_sess_cand 
    126147{ 
    127148    /** 
    … …  
    185206    pj_stun_session     *stun_sess; 
    186207 
    187 } pj_ice_cand; 
     208} pj_ice_sess_cand; 
    188209 
    189210 
    … …  
    191212 * This enumeration describes the state of ICE check. 
    192213 */ 
    193 typedef enum pj_ice_check_state 
     214typedef enum pj_ice_sess_check_state 
    194215{ 
    195216    /** 
    … …  
    198219     * pair to unfreeze and move into the Waiting state. 
    199220     */ 
    200     PJ_ICE_CHECK_STATE_FROZEN, 
     221    PJ_ICE_SESS_CHECK_STATE_FROZEN, 
    201222 
    202223    /** 
    … …  
    205226     * the check list. 
    206227     */ 
    207     PJ_ICE_CHECK_STATE_WAITING, 
     228    PJ_ICE_SESS_CHECK_STATE_WAITING, 
    208229 
    209230    /** 
    … …  
    212233     * the check list. 
    213234     */ 
    214     PJ_ICE_CHECK_STATE_IN_PROGRESS, 
     235    PJ_ICE_SESS_CHECK_STATE_IN_PROGRESS, 
    215236 
    216237    /** 
    … …  
    219240     * the check list. 
    220241     */ 
    221     PJ_ICE_CHECK_STATE_SUCCEEDED, 
     242    PJ_ICE_SESS_CHECK_STATE_SUCCEEDED, 
    222243 
    223244    /** 
    … …  
    226247     * response. 
    227248     */ 
    228     PJ_ICE_CHECK_STATE_FAILED 
    229  
    230 } pj_ice_check_state; 
     249    PJ_ICE_SESS_CHECK_STATE_FAILED 
     250 
     251} pj_ice_sess_check_state; 
    231252 
    232253 
    … …  
    238259 * of a candidate pair. 
    239260 */ 
    240 struct pj_ice_check 
     261struct pj_ice_sess_check 
    241262{ 
    242263    /** 
    243264     * Pointer to local candidate entry of this check. 
    244265     */ 
    245     pj_ice_cand         *lcand; 
     266    pj_ice_sess_cand    *lcand; 
    246267 
    247268    /** 
    248269     * Pointer to remote candidate entry of this check. 
    249270     */ 
    250     pj_ice_cand         *rcand; 
     271    pj_ice_sess_cand    *rcand; 
    251272 
    252273    /** 
    … …  
    258279     * Connectivity check state. 
    259280     */ 
    260     pj_ice_check_state   state; 
     281    pj_ice_sess_check_state      state; 
    261282 
    262283    /** 
    … …  
    285306 * This enumeration describes ICE checklist state. 
    286307 */ 
    287 typedef enum pj_ice_checklist_state 
     308typedef enum pj_ice_sess_checklist_state 
    288309{ 
    289310    /** 
    290311     * The checklist is not yet running. 
    291312     */ 
    292     PJ_ICE_CHECKLIST_ST_IDLE, 
     313    PJ_ICE_SESS_CHECKLIST_ST_IDLE, 
    293314 
    294315    /** 
    … …  
    296317     * media stream. 
    297318     */ 
    298     PJ_ICE_CHECKLIST_ST_RUNNING, 
     319    PJ_ICE_SESS_CHECKLIST_ST_RUNNING, 
    299320 
    300321    /** 
    … …  
    302323     * either successfully or with failure. 
    303324     */ 
    304     PJ_ICE_CHECKLIST_ST_COMPLETED 
    305  
    306 } pj_ice_checklist_state; 
     325    PJ_ICE_SESS_CHECKLIST_ST_COMPLETED 
     326 
     327} pj_ice_sess_checklist_state; 
    307328 
    308329 
    … …  
    311332 * candidate pairs that an agent will use to generate checks. 
    312333 */ 
    313 typedef struct pj_ice_checklist 
     334typedef struct pj_ice_sess_checklist 
    314335{ 
    315336    /** 
    316337     * The checklist state. 
    317338     */ 
    318     pj_ice_checklist_state   state; 
     339    pj_ice_sess_checklist_state   state; 
    319340 
    320341    /** 
    … …  
    326347     * Array of candidate pairs (checks). 
    327348     */ 
    328     pj_ice_check             checks[PJ_ICE_MAX_CHECKS]; 
     349    pj_ice_sess_check        checks[PJ_ICE_MAX_CHECKS]; 
    329350 
    330351    /** 
    … …  
    333354    pj_timer_entry           timer; 
    334355 
    335 } pj_ice_checklist; 
     356} pj_ice_sess_checklist; 
    336357 
    337358 
    … …  
    340361 * session. 
    341362 */ 
    342 typedef struct pj_ice_cb 
     363typedef struct pj_ice_sess_cb 
    343364{ 
    344365    /** 
    … …  
    350371     *                      successful, or some error code. 
    351372     */ 
    352     void        (*on_ice_complete)(pj_ice *ice, pj_status_t status); 
     373    void        (*on_ice_complete)(pj_ice_sess *ice, pj_status_t status); 
    353374 
    354375    /** 
    … …  
    364385     * @param dst_addr_len  Length of destination address. 
    365386     */ 
    366     pj_status_t (*on_tx_pkt)(pj_ice *ice, unsigned comp_id,  
     387    pj_status_t (*on_tx_pkt)(pj_ice_sess *ice, unsigned comp_id,  
    367388                             unsigned cand_id, 
    368389                             const void *pkt, pj_size_t size, 
    … …  
    382403     * @param src_addr_len  The length of source address. 
    383404     */ 
    384     void        (*on_rx_data)(pj_ice *ice, unsigned comp_id, 
     405    void        (*on_rx_data)(pj_ice_sess *ice, unsigned comp_id, 
    385406                              void *pkt, pj_size_t size, 
    386407                              const pj_sockaddr_t *src_addr, 
    387408                              unsigned src_addr_len); 
    388 } pj_ice_cb; 
    389  
    390  
    391 /** 
    392  * This enumeration describes ICE role. 
    393  */ 
    394 typedef enum pj_ice_role 
     409} pj_ice_sess_cb; 
     410 
     411 
     412/** 
     413 * This enumeration describes the role of the ICE agent. 
     414 */ 
     415typedef enum pj_ice_sess_role 
    395416{ 
    396417    /** 
    397418     * The ICE agent is in controlled role. 
    398419     */ 
    399     PJ_ICE_ROLE_CONTROLLED, 
     420    PJ_ICE_SESS_ROLE_CONTROLLED, 
    400421 
    401422    /** 
    402423     * The ICE agent is in controlling role. 
    403424     */ 
    404     PJ_ICE_ROLE_CONTROLLING 
    405  
    406 } pj_ice_role; 
     425    PJ_ICE_SESS_ROLE_CONTROLLING 
     426 
     427} pj_ice_sess_role; 
    407428 
    408429 
    … …  
    416437 * creating multiple ICE sessions, one for each media stream. 
    417438 */ 
    418 struct pj_ice 
     439struct pj_ice_sess 
    419440{ 
    420441    char                obj_name[PJ_MAX_OBJ_NAME];  /**< Object name.       */ 
    … …  
    423444    void                *user_data;                 /**< App. data.         */ 
    424445    pj_mutex_t          *mutex;                     /**< Mutex.             */ 
    425     pj_ice_role          role;                      /**< ICE role.          */ 
     446    pj_ice_sess_role     role;                      /**< ICE role.          */ 
    426447    pj_bool_t            is_complete;               /**< Complete?          */ 
    427448    pj_status_t          ice_status;                /**< Error status.      */ 
    428     pj_ice_cb            cb;                        /**< Callback.          */ 
     449    pj_ice_sess_cb       cb;                        /**< Callback.          */ 
    429450 
    430451    pj_stun_config       stun_cfg;                  /**< STUN settings.     */ 
    … …  
    440461    /* Components */ 
    441462    unsigned             comp_cnt;                  /**< # of components.   */ 
    442     pj_ice_comp          comp[PJ_ICE_MAX_COMP];     /**< Component array    */ 
     463    pj_ice_sess_comp     comp[PJ_ICE_MAX_COMP];     /**< Component array    */ 
    443464 
    444465    /* Local candidates */ 
    445466    unsigned             lcand_cnt;                 /**< # of local cand.   */ 
    446     pj_ice_cand          lcand[PJ_ICE_MAX_CAND];    /**< Array of cand.     */ 
     467    pj_ice_sess_cand     lcand[PJ_ICE_MAX_CAND];    /**< Array of cand.     */ 
    447468 
    448469    /* Remote candidates */ 
    449470    unsigned             rcand_cnt;                 /**< # of remote cand.  */ 
    450     pj_ice_cand          rcand[PJ_ICE_MAX_CAND];    /**< Array of cand.     */ 
     471    pj_ice_sess_cand     rcand[PJ_ICE_MAX_CAND];    /**< Array of cand.     */ 
    451472 
    452473    /* Checklist */ 
    453     pj_ice_checklist     clist;                     /**< Active checklist   */ 
     474    pj_ice_sess_checklist clist;                    /**< Active checklist   */ 
    454475     
    455476    /* Valid list */ 
    456     pj_ice_checklist    valid_list;                /**< Valid list.        */ 
     477    pj_ice_sess_checklist valid_list;               /**< Valid list.        */ 
    457478}; 
    458479 
    … …  
    462483 * particular candidate type. 
    463484 * 
    464  * @param type      Candidate type. 
    465  * 
    466  * @return          The string representation of the candidate type. 
     485 * @param type          Candidate type. 
     486 * 
     487 * @return              The string representation of the candidate type. 
    467488 */ 
    468489PJ_DECL(const char*) pj_ice_get_cand_type_name(pj_ice_cand_type type); 
     490 
     491 
     492/** 
     493 * This is a utility function to calculate the foundation identification 
     494 * for a candidate. 
     495 * 
     496 * @param pool          Pool to allocate the foundation string. 
     497 * @param foundation    Pointer to receive the foundation string. 
     498 * @param type          Candidate type. 
     499 * @param base_addr     Base address of the candidate. 
     500 */ 
     501PJ_DECL(void) pj_ice_calc_foundation(pj_pool_t *pool, 
     502                                     pj_str_t *foundation, 
     503                                     pj_ice_cand_type type, 
     504                                     const pj_sockaddr *base_addr); 
    469505 
    470506 
    … …  
    474510 * sending an offer or upon receiving one. After the session is created, 
    475511 * application can register candidates to the ICE session by calling 
    476  * #pj_ice_add_cand() function. 
     512 * #pj_ice_sess_add_cand() function. 
    477513 * 
    478514 * @param stun_cfg      The STUN configuration settings, containing among 
    … …  
    493529 * @return              PJ_SUCCESS if ICE session is created successfully. 
    494530 */ 
    495 PJ_DECL(pj_status_t) pj_ice_create(pj_stun_config *stun_cfg, 
    496                                    const char *name, 
    497                                    pj_ice_role role, 
    498                                    unsigned comp_cnt, 
    499                                    const pj_ice_cb *cb, 
    500                                    const pj_str_t *local_ufrag, 
    501                                    const pj_str_t *local_passwd, 
    502                                    pj_ice **p_ice); 
    503  
    504 /** 
    505  * Destroy ICE session. 
     531PJ_DECL(pj_status_t) pj_ice_sess_create(pj_stun_config *stun_cfg, 
     532                                        const char *name, 
     533                                        pj_ice_sess_role role, 
     534                                        unsigned comp_cnt, 
     535                                        const pj_ice_sess_cb *cb, 
     536                                        const pj_str_t *local_ufrag, 
     537                                        const pj_str_t *local_passwd, 
     538                                        pj_ice_sess **p_ice); 
     539 
     540/** 
     541 * Destroy ICE session. This will cancel any connectivity checks currently 
     542 * running, if any, and any other events scheduled by this session, as well 
     543 * as all memory resources. 
    506544 * 
    507545 * @param ice           ICE session instance. 
    … …  
    509547 * @return              PJ_SUCCESS on success. 
    510548 */ 
    511 PJ_DECL(pj_status_t) pj_ice_destroy(pj_ice *ice); 
    512  
    513  
    514 /** 
    515  * Add a candidate to this ICE session.  
     549PJ_DECL(pj_status_t) pj_ice_sess_destroy(pj_ice_sess *ice); 
     550 
     551 
     552/** 
     553 * Add a candidate to this ICE session. Application must add candidates for 
     554 * each components ID before it can start pairing the candidates and  
     555 * performing connectivity checks. 
    516556 * 
    517557 * @param ice           ICE session instance. 
    … …  
    529569 * @return              PJ_SUCCESS if candidate is successfully added. 
    530570 */ 
    531 PJ_DECL(pj_status_t) pj_ice_add_cand(pj_ice *ice, 
    532                                      unsigned comp_id, 
    533                                      pj_ice_cand_type type, 
    534                                      pj_uint16_t local_pref, 
    535                                      const pj_str_t *foundation, 
    536                                      const pj_sockaddr_t *addr, 
    537                                      const pj_sockaddr_t *base_addr, 
    538                                      const pj_sockaddr_t *rel_addr, 
    539                                      int addr_len, 
    540                                      unsigned *p_cand_id); 
     571PJ_DECL(pj_status_t) pj_ice_sess_add_cand(pj_ice_sess *ice, 
     572                                          unsigned comp_id, 
     573                                          pj_ice_cand_type type, 
     574                                          pj_uint16_t local_pref, 
     575                                          const pj_str_t *foundation, 
     576                                          const pj_sockaddr_t *addr, 
     577                                          const pj_sockaddr_t *base_addr, 
     578                                          const pj_sockaddr_t *rel_addr, 
     579                                          int addr_len, 
     580                                          unsigned *p_cand_id); 
    541581 
    542582/** 
    … …  
    554594 * @return              PJ_SUCCESS if a candidate has been selected. 
    555595 */ 
    556 PJ_DECL(pj_status_t) pj_ice_find_default_cand(pj_ice *ice, 
    557                                               unsigned comp_id, 
    558                                               int *p_cand_id); 
     596PJ_DECL(pj_status_t) pj_ice_sess_find_default_cand(pj_ice_sess *ice, 
     597                                                   unsigned comp_id, 
     598                                                   int *p_cand_id); 
    559599 
    560600/** 
    … …  
    565605 * 
    566606 * Note that ICE connectivity check will not start until application calls 
    567  * #pj_ice_start_check(). 
     607 * #pj_ice_sess_start_check(). 
    568608 * 
    569609 * @param ice           ICE session instance. 
    … …  
    579619 * @return              PJ_SUCCESS or the appropriate error code. 
    580620 */ 
    581 PJ_DECL(pj_status_t) pj_ice_create_check_list(pj_ice *ice, 
    582                                               const pj_str_t *rem_ufrag, 
    583                                               const pj_str_t *rem_passwd, 
    584                                               unsigned rem_cand_cnt, 
    585                                               const pj_ice_cand rem_cand[]); 
     621PJ_DECL(pj_status_t)  
     622pj_ice_sess_create_check_list(pj_ice_sess *ice, 
     623                              const pj_str_t *rem_ufrag, 
     624                              const pj_str_t *rem_passwd, 
     625                              unsigned rem_cand_cnt, 
     626                              const pj_ice_sess_cand rem_cand[]); 
    586627 
    587628/** 
    588629 * Start ICE periodic check. This function will return immediately, and 
    589630 * application will be notified about the connectivity check status in 
    590  * #pj_ice_cb callback. 
     631 * #pj_ice_sess_cb callback. 
    591632 * 
    592633 * @param ice           The ICE session instance. 
    … …  
    594635 * @return              PJ_SUCCESS or the appropriate error code. 
    595636 */ 
    596 PJ_DECL(pj_status_t) pj_ice_start_check(pj_ice *ice); 
     637PJ_DECL(pj_status_t) pj_ice_sess_start_check(pj_ice_sess *ice); 
    597638 
    598639 
    … …  
    604645 * component. 
    605646 * 
     647 * This function will in turn call \a on_tx_pkt function in 
     648 * #pj_ice_sess_cb callback to actually send the packet to the wire. 
     649 * 
    606650 * @param ice           The ICE session. 
    607651 * @param comp_id       Component ID. 
    … …  
    611655 * @return              PJ_SUCCESS if data is sent successfully. 
    612656 */ 
    613 PJ_DECL(pj_status_t) pj_ice_send_data(pj_ice *ice, 
    614                                       unsigned comp_id, 
    615                                       const void *data, 
    616                                       pj_size_t data_len); 
     657PJ_DECL(pj_status_t) pj_ice_sess_send_data(pj_ice_sess *ice, 
     658                                           unsigned comp_id, 
     659                                           const void *data, 
     660                                           pj_size_t data_len); 
    617661 
    618662/** 
    … …  
    621665 * higher layer component to give incoming packets to the ICE session. 
    622666 * If the packet is not a STUN packet, this packet will be given back 
    623  * to application via \a on_rx_data() callback in #pj_ice_cb. 
     667 * to application via \a on_rx_data() callback in #pj_ice_sess_cb. 
    624668 * 
    625669 * @param ice           The ICE session. 
    … …  
    633677 * @return              PJ_SUCCESS or the appropriate error code. 
    634678 */ 
    635 PJ_DECL(pj_status_t) pj_ice_on_rx_pkt(pj_ice *ice, 
    636                                       unsigned comp_id, 
    637                                       unsigned cand_id, 
    638                                       void *pkt, 
    639                                       pj_size_t pkt_size, 
    640                                       const pj_sockaddr_t *src_addr, 
    641                                       int src_addr_len); 
     679PJ_DECL(pj_status_t) pj_ice_sess_on_rx_pkt(pj_ice_sess *ice, 
     680                                           unsigned comp_id, 
     681                                           unsigned cand_id, 
     682                                           void *pkt, 
     683                                           pj_size_t pkt_size, 
     684                                           const pj_sockaddr_t *src_addr, 
     685                                           int src_addr_len); 
    642686 
    643687 
Note: See TracChangeset for help on using the changeset viewer.