Ignore:
Timestamp:
Feb 23, 2007 1:07:54 AM (17 years ago)
Author:
bennylp
Message:

Ticket #121 and #122: Initial implementation of generic STUN transaction, with Binding request as an example

File:
1 edited

Legend:

Unmodified
Added
Removed

  • pjproject/trunk/pjlib-util/src/pjstun-client/stun_session.h

    r993 r996  
    2626 
    2727 
     28/** Forward declaration for pj_stun_tx_data */ 
    2829typedef struct pj_stun_tx_data pj_stun_tx_data; 
     30 
     31/** Forward declaration for pj_stun_session */ 
    2932typedef struct pj_stun_session pj_stun_session; 
    3033 
     34/** 
     35 * This is the callback to be registered to pj_stun_session, to send 
     36 * outgoing message and to receive various notifications from the STUN 
     37 * session. 
     38 */ 
    3139typedef struct pj_stun_session_cb 
    3240{ 
     41    /** 
     42     * Callback to be called by the STUN session to send outgoing message. 
     43     * 
     44     * @param tdata         The STUN transmit data containing the original 
     45     *                      STUN message 
     46     * @param pkt           Packet to be sent. 
     47     * @param pkt_size      Size of the packet to be sent. 
     48     * @param addr_len      Length of destination address. 
     49     * @param dst_addr      The destination address. 
     50     * 
     51     * @return              The callback should return the status of the 
     52     *                      packet sending. 
     53     */ 
    3354    pj_status_t (*on_send_msg)(pj_stun_tx_data *tdata, 
     55                               const void *pkt, 
     56                               pj_size_t pkt_size, 
    3457                               unsigned addr_len,  
    3558                               const pj_sockaddr_t *dst_addr); 
    3659 
    37     void (*on_bind_response)(void *user_data, pj_status_t status, pj_stun_msg *response); 
    38     void (*on_allocate_response)(void *user_data, pj_status_t status, pj_stun_msg *response); 
    39     void (*on_set_active_destination_response)(void *user_data, pj_status_t status, pj_stun_msg *response); 
    40     void (*on_connect_response)(void *user_data, pj_status_t status, pj_stun_msg *response); 
     60    /** 
     61     * Callback to be called when Binding response is received or the  
     62     * transaction has timed out. 
     63     * 
     64     * @param sess          The STUN session. 
     65     * @param status        Status of the request. If the value if not 
     66     *                      PJ_SUCCESS, the transaction has timed-out 
     67     *                      or other error has occurred, and the response 
     68     *                      argument may be NULL. 
     69     * @param request       The original STUN request. 
     70     * @param response      The response message, on successful transaction. 
     71     */ 
     72    void (*on_bind_response)(pj_stun_session *sess,  
     73                             pj_status_t status,  
     74                             pj_stun_tx_data *request, 
     75                             const pj_stun_msg *response); 
     76 
     77    /** 
     78     * Callback to be called when Allocate response is received or the  
     79     * transaction has timed out. 
     80     * 
     81     * @param sess          The STUN session. 
     82     * @param status        Status of the request. If the value if not 
     83     *                      PJ_SUCCESS, the transaction has timed-out 
     84     *                      or other error has occurred, and the response 
     85     *                      argument may be NULL. 
     86     * @param request       The original STUN request. 
     87     * @param response      The response message, on successful transaction. 
     88     */ 
     89    void (*on_allocate_response)(pj_stun_session *sess,  
     90                                 pj_status_t status,  
     91                                 pj_stun_tx_data *request, 
     92                                 const pj_stun_msg *response); 
     93 
     94    /** 
     95     * Callback to be called when Set Active Destination response is received 
     96     * or the transaction has timed out. 
     97     * 
     98     * @param sess          The STUN session. 
     99     * @param status        Status of the request. If the value if not 
     100     *                      PJ_SUCCESS, the transaction has timed-out 
     101     *                      or other error has occurred, and the response 
     102     *                      argument may be NULL. 
     103     * @param request       The original STUN request. 
     104     * @param response      The response message, on successful transaction. 
     105     */ 
     106    void (*on_set_active_destination_response)(pj_stun_session *sess,  
     107                                               pj_status_t status,  
     108                                               pj_stun_tx_data *request, 
     109                                               const pj_stun_msg *response); 
     110 
     111    /** 
     112     * Callback to be called when Connect response is received or the  
     113     * transaction has timed out. 
     114     * 
     115     * @param sess          The STUN session. 
     116     * @param status        Status of the request. If the value if not 
     117     *                      PJ_SUCCESS, the transaction has timed-out 
     118     *                      or other error has occurred, and the response 
     119     *                      argument may be NULL. 
     120     * @param request       The original STUN request. 
     121     * @param response      The response message, on successful transaction. 
     122     */ 
     123    void (*on_connect_response)( pj_stun_session *sess,  
     124                                 pj_status_t status,  
     125                                 pj_stun_tx_data *request, 
     126                                 const pj_stun_msg *response); 
    41127} pj_stun_session_cb; 
    42128 
    43129 
     130/** 
     131 * This structure describe the outgoing STUN transmit data to carry the 
     132 * message to be sent. 
     133 */ 
    44134struct pj_stun_tx_data 
    45135{ 
    46136    PJ_DECL_LIST_MEMBER(struct pj_stun_tx_data); 
    47137 
    48     pj_pool_t           *pool; 
    49     pj_stun_session     *sess; 
    50     pj_stun_msg         *msg; 
    51     void                *user_data; 
    52  
    53     pj_stun_client_tsx  *client_tsx; 
    54     pj_uint8_t           client_key[12]; 
     138    pj_pool_t           *pool;          /**< Pool.                          */ 
     139    pj_stun_session     *sess;          /**< The STUN session.              */ 
     140    pj_stun_msg         *msg;           /**< The STUN message.              */ 
     141    void                *user_data;     /**< Arbitrary user data.           */ 
     142 
     143    pj_stun_client_tsx  *client_tsx;    /**< Client STUN transaction.       */ 
     144    pj_uint8_t           client_key[12];/**< Client transaction key.        */ 
     145 
     146    void                *pkt;           /**< The STUN packet.               */ 
     147    unsigned             max_len;       /**< Length of packet buffer.       */ 
     148    unsigned             pkt_size;      /**< The actual length of STUN pkt. */ 
     149 
     150    unsigned             addr_len;      /**< Length of destination address. */ 
     151    const pj_sockaddr_t *dst_addr;      /**< Destination address.           */ 
    55152}; 
    56153 
    57154 
     155/** 
     156 * Options that can be specified when creating or sending outgoing STUN 
     157 * messages. These options may be specified as bitmask. 
     158 */ 
     159enum pj_stun_session_option 
     160{ 
     161    /** 
     162     * Add short term credential to the message. This option may not be used 
     163     * together with PJ_STUN_USE_LONG_TERM_CRED option. 
     164     */ 
     165    PJ_STUN_USE_SHORT_TERM_CRED = 1, 
     166 
     167    /** 
     168     * Add long term credential to the message. This option may not be used 
     169     * together with PJ_STUN_USE_SHORT_TERM_CRED option. 
     170     */ 
     171    PJ_STUN_USE_LONG_TERM_CRED  = 2, 
     172 
     173    /** 
     174     * Add STUN fingerprint to the message. 
     175     */ 
     176    PJ_STUN_USE_FINGERPRINT     = 4 
     177}; 
     178 
     179 
     180/** 
     181 * Create a STUN session. 
     182 * 
     183 * @param endpt     The STUN endpoint, to be used to register timers etc. 
     184 * @param name      Optional name to be associated with this instance. The 
     185 *                  name will be used for example for logging purpose. 
     186 * @param cb        Session callback. 
     187 * @param p_sess    Pointer to receive STUN session instance. 
     188 * 
     189 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     190 */ 
    58191PJ_DECL(pj_status_t) pj_stun_session_create(pj_stun_endpoint *endpt, 
    59192                                            const char *name, 
    … …  
    61194                                            pj_stun_session **p_sess); 
    62195 
     196/** 
     197 * Destroy the STUN session. 
     198 * 
     199 * @param sess      The STUN session instance. 
     200 * 
     201 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     202 */ 
    63203PJ_DECL(pj_status_t) pj_stun_session_destroy(pj_stun_session *sess); 
    64204 
     205/** 
     206 * Associated an arbitrary data with this STUN session. The user data may 
     207 * be retrieved later with pj_stun_session_get_user_data() function. 
     208 * 
     209 * @param sess      The STUN session instance. 
     210 * 
     211 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     212 */ 
    65213PJ_DECL(pj_status_t) pj_stun_session_set_user_data(pj_stun_session *sess, 
    66214                                                   void *user_data); 
    67215 
     216/** 
     217 * Retrieve the user data previously associated to this STUN session with 
     218 * pj_stun_session_set_user_data(). 
     219 * 
     220 * @param sess      The STUN session instance. 
     221 * 
     222 * @return          The user data associated with this STUN session. 
     223 */ 
    68224PJ_DECL(void*) pj_stun_session_get_user_data(pj_stun_session *sess); 
    69225 
    70 PJ_DECL(pj_status_t) pj_stun_session_set_credential(pj_stun_session *sess, 
    71                                                     const pj_str_t *realm, 
    72                                                     const pj_str_t *user, 
    73                                                     const pj_str_t *passwd); 
    74  
    75 PJ_DECL(pj_status_t) pj_stun_session_enable_fingerprint(pj_stun_session *sess, 
    76                                                         pj_bool_t enabled); 
    77  
     226/** 
     227 * Save a long term credential to be used by this STUN session when sending 
     228 * outgoing messages. After long term credential is configured, application 
     229 * may specify PJ_STUN_USE_LONG_TERM_CRED option when sending outgoing STUN 
     230 * message to send the long term credential in the message. 
     231 * 
     232 * @param sess      The STUN session instance. 
     233 * @param realm     Realm of the long term credential. 
     234 * @param user      The user name. 
     235 * @param passwd    The pain-text password. 
     236 * 
     237 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     238 */ 
     239PJ_DECL(pj_status_t)  
     240pj_stun_session_set_long_term_credential(pj_stun_session *sess, 
     241                                         const pj_str_t *realm, 
     242                                         const pj_str_t *user, 
     243                                         const pj_str_t *passwd); 
     244 
     245 
     246/** 
     247 * Save a short term credential to be used by this STUN session when sending 
     248 * outgoing messages. After short term credential is configured, application 
     249 * may specify PJ_STUN_USE_SHORT_TERM_CRED option when sending outgoing STUN 
     250 * message to send the short term credential in the message. 
     251 * 
     252 * @param sess      The STUN session instance. 
     253 * @param user      The user name. 
     254 * @param passwd    The pain-text password. 
     255 * 
     256 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     257 */ 
     258PJ_DECL(pj_status_t)  
     259pj_stun_session_set_short_term_credential(pj_stun_session *sess, 
     260                                          const pj_str_t *user, 
     261                                          const pj_str_t *passwd); 
     262 
     263/** 
     264 * Create a STUN Bind request message. After the message has been  
     265 * successfully created, application can send the message by calling  
     266 * pj_stun_session_send_msg(). 
     267 * 
     268 * @param sess      The STUN session instance. 
     269 * @param p_tdata   Pointer to receive STUN transmit data instance containing 
     270 *                  the request. 
     271 * 
     272 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     273 */ 
    78274PJ_DECL(pj_status_t) pj_stun_session_create_bind_req(pj_stun_session *sess, 
    79275                                                     pj_stun_tx_data **p_tdata); 
    80276 
     277/** 
     278 * Create a STUN Allocate request message. After the message has been 
     279 * successfully created, application can send the message by calling   
     280 * pj_stun_session_send_msg(). 
     281 * 
     282 * @param sess      The STUN session instance. 
     283 * @param p_tdata   Pointer to receive STUN transmit data instance containing 
     284 *                  the request. 
     285 * 
     286 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     287 */ 
    81288PJ_DECL(pj_status_t) pj_stun_session_create_allocate_req(pj_stun_session *sess, 
    82289                                                         pj_stun_tx_data **p_tdata); 
    83290 
     291/** 
     292 * Create a STUN Set Active Destination request message. After the message  
     293 * has been successfully created, application can send the message by calling 
     294 * pj_stun_session_send_msg(). 
     295 * 
     296 * @param sess      The STUN session instance. 
     297 * @param p_tdata   Pointer to receive STUN transmit data instance containing 
     298 *                  the request. 
     299 * 
     300 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     301 */ 
    84302PJ_DECL(pj_status_t)  
    85303pj_stun_session_create_set_active_destination_req(pj_stun_session *sess, 
    86304                                                  pj_stun_tx_data **p_tdata); 
    87305 
     306/** 
     307 * Create a STUN Connect request message. After the message has been  
     308 * successfully created, application can send the message by calling  
     309 * pj_stun_session_send_msg(). 
     310 * 
     311 * @param sess      The STUN session instance. 
     312 * @param p_tdata   Pointer to receive STUN transmit data instance containing 
     313 *                  the request. 
     314 * 
     315 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     316 */ 
    88317PJ_DECL(pj_status_t) pj_stun_session_create_connect_req(pj_stun_session *sess, 
    89318                                                        pj_stun_tx_data **p_tdata); 
    90319 
    91 PJ_DECL(pj_status_t)  
     320/** 
     321 * Create a STUN Connection Status Indication message. After the message  
     322 * has been successfully created, application can send the message by calling 
     323 * pj_stun_session_send_msg(). 
     324 * 
     325 * @param sess      The STUN session instance. 
     326 * @param p_tdata   Pointer to receive STUN transmit data instance containing 
     327 *                  the message. 
     328 * 
     329 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     330 */ 
     331PJ_DECL(pj_status_t) 
    92332pj_stun_session_create_connection_status_ind(pj_stun_session *sess, 
    93333                                             pj_stun_tx_data **p_tdata); 
    94334 
     335/** 
     336 * Create a STUN Send Indication message. After the message has been  
     337 * successfully created, application can send the message by calling  
     338 * pj_stun_session_send_msg(). 
     339 * 
     340 * @param sess      The STUN session instance. 
     341 * @param p_tdata   Pointer to receive STUN transmit data instance containing 
     342 *                  the message. 
     343 * 
     344 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     345 */ 
    95346PJ_DECL(pj_status_t) pj_stun_session_create_send_ind(pj_stun_session *sess, 
    96347                                                     pj_stun_tx_data **p_tdata); 
    97348 
     349/** 
     350 * Create a STUN Data Indication message. After the message has been  
     351 * successfully created, application can send the message by calling  
     352 * pj_stun_session_send_msg(). 
     353 * 
     354 * @param sess      The STUN session instance. 
     355 * @param p_tdata   Pointer to receive STUN transmit data instance containing 
     356 *                  the message. 
     357 * 
     358 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     359 */ 
    98360PJ_DECL(pj_status_t) pj_stun_session_create_data_ind(pj_stun_session *sess, 
    99361                                                     pj_stun_tx_data **p_tdata); 
    100362 
     363/** 
     364 * Send STUN message to the specified destination. This function will encode 
     365 * the pj_stun_msg instance to a packet buffer, and add credential or 
     366 * fingerprint if necessary. If the message is a request, the session will 
     367 * also create and manage a STUN client transaction to be used to manage the 
     368 * retransmission of the request. After the message has been encoded and 
     369 * transaction is setup, the \a on_send_msg() callback of pj_stun_session_cb 
     370 * (which is registered when the STUN session is created) will be called 
     371 * to actually send the message to the wire. 
     372 * 
     373 * @param sess      The STUN session instance. 
     374 * @param options   Optional flags, from pj_stun_session_option. 
     375 * @param addr_len  Length of destination address. 
     376 * @param dst_addr  The destination socket address. 
     377 * @param tdata     The STUN transmit data containing the STUN message to 
     378 *                  be sent. 
     379 * 
     380 * @return          PJ_SUCCESS on success, or the appropriate error code. 
     381 */ 
    101382PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess, 
     383                                              unsigned options, 
    102384                                              unsigned addr_len, 
    103                                               const pj_sockaddr_t *server, 
     385                                              const pj_sockaddr_t *dst_addr, 
    104386                                              pj_stun_tx_data *tdata); 
    105387 
     388/** 
     389 * Application must call this function to notify the STUN session about 
     390 * the arrival of STUN packet. The STUN packet MUST have been checked 
     391 * first with #pj_stun_msg_check() to verify that this is indeed a valid 
     392 * STUN packet. 
     393 * 
     394 * The STUN session will decode the packet into pj_stun_msg, and process 
     395 * the message accordingly. If the message is a response, it will search 
     396 * through the outstanding STUN client transactions for a matching 
     397 * transaction ID and hand over the response to the transaction. 
     398 * 
     399 * On successful message processing, application will be notified about 
     400 * the message via one of the pj_stun_session_cb callback. 
     401 * 
     402 * @param sess       The STUN session instance. 
     403 * @param packet     The packet containing STUN message. 
     404 * @param pkt_size   Size of the packet. 
     405 * @param parsed_len Optional pointer to receive the size of the parsed 
     406 *                   STUN message (useful if packet is received via a 
     407 *                   stream oriented protocol). 
     408 * 
     409 * @return           PJ_SUCCESS on success, or the appropriate error code. 
     410 */ 
    106411PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess, 
    107412                                               const void *packet, 
Note: See TracChangeset for help on using the changeset viewer.