Ignore:
Timestamp:
Sep 23, 2019 7:25:41 AM (3 years ago)
Author:
ming
Message:

Fixed #2229: Limitations in ICE data sending

File:
1 edited

Legend:

Unmodified
Added
Removed
  • pjproject/trunk/pjnath/include/pjnath/ice_strans.h

    r5562 r6071  
    9999 *    pair. The ICE stream transport may not be able to send data while  
    100100 *    negotiation is in progress.\n\n 
    101  *  - application sends data by using #pj_ice_strans_sendto(). Incoming 
     101 *  - application sends data by using #pj_ice_strans_sendto2(). Incoming 
    102102 *    data will be reported in \a on_rx_data() callback of the 
    103103 *    #pj_ice_strans_cb.\n\n 
     
    114114 */ 
    115115 
     116/* Deprecated API pj_ice_strans_sendto() due to its limitations. See 
     117 * below for more info and refer to 
     118 * https://trac.pjsip.org/repos/ticket/2229 for more details. 
     119 */ 
     120#ifndef DEPRECATED_FOR_TICKET_2229 
     121#  define DEPRECATED_FOR_TICKET_2229    0 
     122#endif 
     123 
    116124/** Forward declaration for ICE stream transport. */ 
    117125typedef struct pj_ice_strans pj_ice_strans; 
     
    160168                          const pj_sockaddr_t *src_addr, 
    161169                          unsigned src_addr_len); 
     170 
     171    /** 
     172     * This callback is optional and will be called to notify the status of 
     173     * async send operations. 
     174     * 
     175     * @param ice_st        The ICE stream transport. 
     176     * @param sent          If value is positive non-zero it indicates the 
     177     *                      number of data sent. When the value is negative, 
     178     *                      it contains the error code which can be retrieved 
     179     *                      by negating the value (i.e. status=-sent). 
     180     */ 
     181    void    (*on_data_sent)(pj_ice_strans *sock, 
     182                            pj_ssize_t sent); 
    162183 
    163184    /** 
     
    416437     */ 
    417438    pj_ice_strans_turn_cfg turn_tp[PJ_ICE_MAX_TURN]; 
     439 
     440    /** 
     441     * Number of send buffers used for pj_ice_strans_sendto2(). If the send 
     442     * buffers are full, pj_ice_strans_sendto()/sendto2() will return 
     443     * PJ_EBUSY. 
     444     * 
     445     * Set this to 0 to disable buffering (then application will have to 
     446     * maintain the buffer passed to pj_ice_strans_sendto()/sendto2() 
     447     * until it has been sent). 
     448     * 
     449     * Default: 4 
     450     */ 
     451    unsigned             num_send_buf; 
     452 
     453    /** 
     454     * Buffer size used for pj_ice_strans_sendto2(). 
     455     * 
     456     * Default: 0 (size determined by the size of the first packet sent). 
     457     */ 
     458    unsigned             send_buf_size; 
    418459 
    419460    /** 
     
    905946 
    906947 
     948#if !DEPRECATED_FOR_TICKET_2229 
    907949/** 
    908950 * Send outgoing packet using this transport.  
     
    917959 * address, as negotiated by ICE. 
    918960 * 
     961 * Limitations: 
     962 * 1. This function cannot inform the app whether the data has been sent, 
     963 *    or currently still pending. 
     964 * 2. In case that the data is still pending, the application has no way 
     965 *    of knowing the status of the send operation (whether it's a success 
     966 *    or failure). 
     967 * Due to these limitations, the API is deprecated and will be removed 
     968 * in the future. 
     969 * 
     970 * Note that application shouldn't mix using pj_ice_strans_sendto() and 
     971 * pj_ice_strans_sendto2() to avoid inconsistent calling of 
     972 * on_data_sent() callback. 
     973 * 
    919974 * @param ice_st        The ICE stream transport. 
    920975 * @param comp_id       Component ID. 
     
    924979 * @param dst_addr_len  Length of destination address. 
    925980 * 
    926  * @return              PJ_SUCCESS if data is sent successfully. 
     981 * @return              PJ_SUCCESS if data has been sent, or will be sent 
     982 *                      later. No callback will be called. 
    927983 */ 
    928984PJ_DECL(pj_status_t) pj_ice_strans_sendto(pj_ice_strans *ice_st, 
     
    932988                                          const pj_sockaddr_t *dst_addr, 
    933989                                          int dst_addr_len); 
     990#endif 
     991 
     992 
     993/** 
     994 * Send outgoing packet using this transport.  
     995 * Application can send data (normally RTP or RTCP packets) at any time 
     996 * by calling this function. This function takes a destination 
     997 * address as one of the arguments, and this destination address should 
     998 * be taken from the default transport address of the component (that is 
     999 * the address in SDP c= and m= lines, or in a=rtcp attribute).  
     1000 * If ICE negotiation is in progress, this function will send the data  
     1001 * to the destination address. Otherwise if ICE negotiation has completed 
     1002 * successfully, this function will send the data to the nominated remote  
     1003 * address, as negotiated by ICE. 
     1004 * 
     1005 * Note that application shouldn't mix using pj_ice_strans_sendto() and 
     1006 * pj_ice_strans_sendto2() to avoid inconsistent calling of 
     1007 * on_data_sent() callback. 
     1008 * 
     1009 * @param ice_st        The ICE stream transport. 
     1010 * @param comp_id       Component ID. 
     1011 * @param data          The data or packet to be sent. 
     1012 * @param data_len      Size of data or packet, in bytes. 
     1013 * @param dst_addr      The destination address. 
     1014 * @param dst_addr_len  Length of destination address. 
     1015 * 
     1016 * @return              PJ_SUCCESS if data has been sent, or 
     1017 *                      PJ_EPENDING if data cannot be sent immediately. In 
     1018 *                      this case the \a on_data_sent() callback will be 
     1019 *                      called when data is actually sent. Any other return 
     1020 *                      value indicates error condition. 
     1021 */ 
     1022PJ_DECL(pj_status_t) pj_ice_strans_sendto2(pj_ice_strans *ice_st, 
     1023                                           unsigned comp_id, 
     1024                                           const void *data, 
     1025                                           pj_size_t data_len, 
     1026                                           const pj_sockaddr_t *dst_addr, 
     1027                                           int dst_addr_len); 
    9341028 
    9351029 
Note: See TracChangeset for help on using the changeset viewer.