Ignore:
Timestamp:
Feb 3, 2007 8:31:33 PM (15 years ago)
Author:
bennylp
Message:

ICE branch: initial server prototype

File:
1 edited

Legend:

Unmodified
Added
Removed
  • pjproject/branches/iceproject/pjlib-util/include/pjlib-util/stun_transaction.h

    r913 r929  
    1 /* $Id */ 
     1/* $Id$ */ 
    22/*  
    33 * Copyright (C) 2003-2005 Benny Prijono <benny@prijono.org> 
     
    3838 * @ingroup PJLIB_UTIL_STUN 
    3939 * @{ 
     40 * 
     41 The @ref PJLIB_UTIL_STUN_TRANSACTION is used to manage outgoing STUN request, 
     42 for example to retransmit the request and to notify application about the 
     43 completion of the request. 
     44 
     45 The @ref PJLIB_UTIL_STUN_TRANSACTION does not use any networking operations, 
     46 but instead application must supply the transaction with a callback to 
     47 be used by the transaction to send outgoing requests. This way the STUN 
     48 transaction is made more generic and can work with different types of 
     49 networking codes in application. 
     50 
     51 
    4052 */ 
    4153 
     
    5062typedef struct pj_stun_tsx_cb 
    5163{ 
     64    /** 
     65     * This callback is called when the STUN transaction completed. 
     66     * 
     67     * @param tsx           The STUN transaction. 
     68     * @param status        Status of the transaction. Status PJ_SUCCESS 
     69     *                      means that the request has received a successful 
     70     *                      response. 
     71     * @param response      The STUN response, which value may be NULL if 
     72     *                      \a status is not PJ_SUCCESS. 
     73     */ 
    5274    void        (*on_complete)(pj_stun_client_tsx *tsx, 
    5375                               pj_status_t status,  
    5476                               pj_stun_msg *response); 
     77 
     78    /** 
     79     * This callback is called by the STUN transaction when it wants to send 
     80     * outgoing message. 
     81     * 
     82     * @param tsx           The STUN transaction instance. 
     83     * @param stun_pkt      The STUN packet to be sent. 
     84     * @param pkt_size      Size of the STUN packet. 
     85     * 
     86     * @return              If return value of the callback is not PJ_SUCCESS, 
     87     *                      the transaction will fail. 
     88     */ 
    5589    pj_status_t (*on_send_msg)(pj_stun_client_tsx *tsx, 
    5690                               const void *stun_pkt, 
     
    6296 
    6397/** 
    64  * Create a STUN client transaction. 
     98 * Create an instance of STUN client transaction. The STUN client  
     99 * transaction is used to transmit outgoing STUN request and to  
     100 * ensure the reliability of the request by periodically retransmitting 
     101 * the request, if necessary. 
     102 * 
     103 * @param endpt         The STUN endpoint, which will be used to retrieve 
     104 *                      various settings for the transaction. 
     105 * @param cb            Callback structure, to be used by the transaction 
     106 *                      to send message and to notify the application about 
     107 *                      the completion of the transaction. 
     108 * @param p_tsx         Pointer to receive the transaction instance. 
     109 * 
     110 * @return              PJ_SUCCESS on success, or the appropriate error code. 
    65111 */ 
    66112PJ_DECL(pj_status_t) pj_stun_client_tsx_create( pj_stun_endpoint *endpt, 
     
    69115 
    70116/** 
    71  * . 
     117 * Destroy a STUN client transaction. 
     118 * 
     119 * @param tsx           The STUN transaction. 
     120 * 
     121 * @return              PJ_SUCCESS on success, or the appropriate error code. 
    72122 */ 
    73123PJ_DECL(pj_status_t) pj_stun_client_tsx_destroy(pj_stun_client_tsx *tsx); 
     
    75125 
    76126/** 
    77  * . 
     127 * Associate an arbitrary data with the STUN transaction. This data 
     128 * can be then retrieved later from the transaction, by using 
     129 * pj_stun_client_tsx_get_data() function. 
     130 * 
     131 * @param tsx           The STUN client transaction. 
     132 * @param data          Application data to be associated with the 
     133 *                      STUN transaction. 
     134 * 
     135 * @return              PJ_SUCCESS on success. 
    78136 */ 
    79137PJ_DECL(pj_status_t) pj_stun_client_tsx_set_data(pj_stun_client_tsx *tsx, 
     
    82140 
    83141/** 
    84  * . 
     142 * Get the user data that was previously associated with the STUN  
     143 * transaction. 
     144 * 
     145 * @param tsx           The STUN client transaction. 
     146 * 
     147 * @return              The user data. 
    85148 */ 
    86149PJ_DECL(void*) pj_stun_client_tsx_get_data(pj_stun_client_tsx *tsx); 
     
    88151 
    89152/** 
    90  * . 
     153 * Start the STUN client transaction by sending STUN request using 
     154 * this transaction. If reliable transport such as TCP or TLS is used, 
     155 * the retransmit flag should be set to PJ_FALSE because reliablity 
     156 * will be assured by the transport layer. 
     157 * 
     158 * @param tsx           The STUN client transaction. 
     159 * @param retransmit    Should this message be retransmitted by the 
     160 *                      STUN transaction. 
     161 * @param msg           The STUN message. 
     162 * 
     163 * @return              PJ_SUCCESS on success or the appropriate error code. 
    91164 */ 
    92165PJ_DECL(pj_status_t) pj_stun_client_tsx_send_msg(pj_stun_client_tsx *tsx, 
     166                                                 pj_bool_t retransmit, 
    93167                                                 const pj_stun_msg *msg); 
    94168 
    95169 
    96170/** 
    97  * . 
     171 * Notify the STUN transaction about the arrival of STUN response. 
     172 * If the STUN response contains a final error (300 and greater), the 
     173 * transaction will be terminated and callback will be called. If the 
     174 * STUN response contains response code 100-299, retransmission 
     175 * will  cease, but application must still call this function again 
     176 * with a final response later to allow the transaction to complete. 
     177 * 
     178 * @param tsx           The STUN client transaction instance. 
     179 * @param packet        The incoming packet. 
     180 * @param pkt_size      Size of the incoming packet. 
     181 * @param parsed_len    Optional pointer to receive the number of bytes 
     182 *                      that have been parsed from the incoming packet 
     183 *                      for the STUN message. This is useful if the 
     184 *                      STUN transaction is running over stream oriented 
     185 *                      socket such as TCP or TLS. 
     186 * 
     187 * @return              PJ_SUCCESS on success or the appropriate error code. 
    98188 */ 
    99189PJ_DECL(pj_status_t) pj_stun_client_tsx_on_rx_msg(pj_stun_client_tsx *tsx, 
Note: See TracChangeset for help on using the changeset viewer.