diff options
Diffstat (limited to 'pjnath/include/pjnath/stun_session.h')
| -rw-r--r-- | pjnath/include/pjnath/stun_session.h | 91 |
1 files changed, 84 insertions, 7 deletions
diff --git a/pjnath/include/pjnath/stun_session.h b/pjnath/include/pjnath/stun_session.h index 187064ed..821e765b 100644 --- a/pjnath/include/pjnath/stun_session.h +++ b/pjnath/include/pjnath/stun_session.h @@ -64,6 +64,15 @@ typedef struct pj_stun_session_cb * Callback to be called by the STUN session to send outgoing message. * * @param sess The STUN session. + * @param token The token associated with this outgoing message + * and was set by the application. This token was + * set by application in pj_stun_session_send_msg() + * for outgoing messages that are initiated by the + * application, or in pj_stun_session_on_rx_pkt() + * if this message is a response that was internally + * generated by the STUN session (for example, an + * 401/Unauthorized response). Application may use + * this facility for any purposes. * @param pkt Packet to be sent. * @param pkt_size Size of the packet to be sent. * @param dst_addr The destination address. @@ -73,13 +82,17 @@ typedef struct pj_stun_session_cb * packet sending. */ pj_status_t (*on_send_msg)(pj_stun_session *sess, + void *token, const void *pkt, pj_size_t pkt_size, const pj_sockaddr_t *dst_addr, unsigned addr_len); /** - * Callback to be called on incoming STUN request message. In the + * Callback to be called on incoming STUN request message. This function + * is called when application calls pj_stun_session_on_rx_pkt() and when + * the STUN session has detected that the incoming STUN message is a + * STUN request message. In the * callback processing, application MUST create a response by calling * pj_stun_session_create_response() function and send the response * with pj_stun_session_send_msg() function, before returning from @@ -89,6 +102,8 @@ typedef struct pj_stun_session_cb * @param pkt Pointer to the original STUN packet. * @param pkt_len Length of the STUN packet. * @param rdata Data containing incoming request message. + * @param token The token that was set by the application when + * calling pj_stun_session_on_rx_pkt() function. * @param src_addr Source address of the packet. * @param src_addr_len Length of the source address. * @@ -100,12 +115,17 @@ typedef struct pj_stun_session_cb const pj_uint8_t *pkt, unsigned pkt_len, const pj_stun_rx_data *rdata, + void *token, const pj_sockaddr_t *src_addr, unsigned src_addr_len); /** * Callback to be called when response is received or the transaction - * has timed out. + * has timed out. This callback is called either when application calls + * pj_stun_session_on_rx_pkt() with the packet containing a STUN + * response for the client transaction, or when the internal timer of + * the STUN client transaction has timed-out before a STUN response is + * received. * * @param sess The STUN session. * @param status Status of the request. If the value if not @@ -115,6 +135,10 @@ typedef struct pj_stun_session_cb * Note that when the status is not success, the * response may contain non-NULL value if the * response contains STUN ERROR-CODE attribute. + * @param token The token that was set by the application when + * calling pj_stun_session_send_msg() function. + * Please not that this token IS NOT the token + * that was given in pj_stun_session_on_rx_pkt(). * @param tdata The original STUN request. * @param response The response message, on successful transaction, * or otherwise MAY BE NULL if status is not success. @@ -127,6 +151,7 @@ typedef struct pj_stun_session_cb */ void (*on_request_complete)(pj_stun_session *sess, pj_status_t status, + void *token, pj_stun_tx_data *tdata, const pj_stun_msg *response, const pj_sockaddr_t *src_addr, @@ -134,12 +159,29 @@ typedef struct pj_stun_session_cb /** - * Type of callback to be called on incoming STUN indication. + * Callback to be called on incoming STUN request message. This function + * is called when application calls pj_stun_session_on_rx_pkt() and when + * the STUN session has detected that the incoming STUN message is a + * STUN indication message. + * + * @param sess The STUN session. + * @param pkt Pointer to the original STUN packet. + * @param pkt_len Length of the STUN packet. + * @param msg The parsed STUN indication. + * @param token The token that was set by the application when + * calling pj_stun_session_on_rx_pkt() function. + * @param src_addr Source address of the packet. + * @param src_addr_len Length of the source address. + * + * @return The return value of this callback will be + * returned back to pj_stun_session_on_rx_pkt() + * function. */ pj_status_t (*on_rx_indication)(pj_stun_session *sess, const pj_uint8_t *pkt, unsigned pkt_len, const pj_stun_msg *msg, + void *token, const pj_sockaddr_t *src_addr, unsigned src_addr_len); @@ -177,9 +219,10 @@ struct pj_stun_tx_data pj_stun_session *sess; /**< The STUN session. */ pj_stun_msg *msg; /**< The STUN message. */ - void *user_data; /**< Arbitrary application data. */ + void *token; /**< The token. */ pj_stun_client_tsx *client_tsx; /**< Client STUN transaction. */ + pj_bool_t retransmit; /**< Retransmit request? */ pj_uint32_t msg_magic; /**< Message magic. */ pj_uint8_t msg_key[12]; /**< Message/transaction key. */ @@ -368,7 +411,21 @@ PJ_DECL(pj_status_t) pj_stun_session_create_res(pj_stun_session *sess, * to actually send the message to the wire. * * @param sess The STUN session instance. - * @param cache_res If PJ_TRUE then response will be cached. + * @param token Optional token which will be given back to application in + * \a on_send_msg() callback and \a on_request_complete() + * callback, if the message is a STUN request message. + * Internally this function will put the token in the + * \a token field of pj_stun_tx_data, hence it will + * overwrite any value that the application puts there. + * @param cache_res If the message is a response message for an incoming + * request, specify PJ_TRUE to instruct the STUN session + * to cache this response for subsequent incoming request + * retransmission. Otherwise this parameter will be ignored + * for non-response message. + * @param retransmit If the message is a request message, specify whether the + * request should be retransmitted. Normally application will + * specify TRUE if the underlying transport is UDP and FALSE + * if the underlying transport is TCP or TLS. * @param dst_addr The destination socket address. * @param addr_len Length of destination address. * @param tdata The STUN transmit data containing the STUN message to @@ -377,13 +434,18 @@ PJ_DECL(pj_status_t) pj_stun_session_create_res(pj_stun_session *sess, * @return PJ_SUCCESS on success, or the appropriate error code. */ PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess, + void *token, pj_bool_t cache_res, + pj_bool_t retransmit, const pj_sockaddr_t *dst_addr, unsigned addr_len, pj_stun_tx_data *tdata); /** - * Create and send STUN response message. + * This is a utility function to create and send response for an incoming + * STUN request. Internally this function calls pj_stun_session_create_res() + * and pj_stun_session_send_msg(). It is provided here as a matter of + * convenience. * * @param sess The STUN session instance. * @param rdata The STUN request message to be responded. @@ -395,6 +457,12 @@ PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess, * creating error response. If the value is NULL and the * \a err_code is non-zero, then default error message will * be used. + * @param token Optional token which will be given back to application in + * \a on_send_msg() callback and \a on_request_complete() + * callback, if the message is a STUN request message. + * Internally this function will put the token in the + * \a token field of pj_stun_tx_data, hence it will + * overwrite any value that the application puts there. * @param cache Specify whether session should cache this response for * future request retransmission. If TRUE, subsequent request * retransmission will be handled by the session and it @@ -409,6 +477,7 @@ PJ_DECL(pj_status_t) pj_stun_session_respond(pj_stun_session *sess, const pj_stun_rx_data *rdata, unsigned code, const char *err_msg, + void *token, pj_bool_t cache, const pj_sockaddr_t *dst_addr, unsigned addr_len); @@ -468,7 +537,14 @@ PJ_DECL(pj_status_t) pj_stun_session_retransmit_req(pj_stun_session *sess, * @param parsed_len Optional pointer to receive the size of the parsed * STUN message (useful if packet is received via a * stream oriented protocol). - * @param src_addr The source address of the packet. + * @param token Optional token which will be given back to application + * in the \a on_rx_request(), \a on_rx_indication() and + * \a on_send_msg() callbacks. The token can be used to + * associate processing or incoming request or indication + * with some context. + * @param src_addr The source address of the packet, which will also + * be given back to application callbacks, along with + * source address length. * @param src_addr_len Length of the source address. * * @return PJ_SUCCESS on success, or the appropriate error code. @@ -477,6 +553,7 @@ PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess, const void *packet, pj_size_t pkt_size, unsigned options, + void *token, unsigned *parsed_len, const pj_sockaddr_t *src_addr, unsigned src_addr_len); |