From 320ebe471866fd5c1ca2406e28aaa1fdce7695ef Mon Sep 17 00:00:00 2001 From: Benny Prijono Date: Thu, 1 Mar 2007 00:08:27 +0000 Subject: More work on STUN session framework git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@1021 74dad513-b988-da41-8d7b-12977e46ad98 --- pjlib-util/include/pjlib-util/stun_msg.h | 16 +-- pjlib-util/include/pjlib-util/stun_session.h | 159 +++++++++++++++++---------- 2 files changed, 112 insertions(+), 63 deletions(-) (limited to 'pjlib-util/include') diff --git a/pjlib-util/include/pjlib-util/stun_msg.h b/pjlib-util/include/pjlib-util/stun_msg.h index 05aa7d67..6d4d5a6b 100644 --- a/pjlib-util/include/pjlib-util/stun_msg.h +++ b/pjlib-util/include/pjlib-util/stun_msg.h @@ -1174,7 +1174,9 @@ PJ_DECL(pj_status_t) pj_stun_msg_add_attr(pj_stun_msg *msg, * If FINGERPRINT attribute is present, this function will calculate * the FINGERPRINT CRC attribute for the message. * - * @param msg The STUN message to be printed. + * @param msg The STUN message to be printed. Upon return, + * some fields in the header (such as message + * length) will be updated. * @param pkt_buf The buffer to be filled with the packet. * @param buf_size Size of the buffer. * @param options Options, which currently must be zero. @@ -1186,7 +1188,7 @@ PJ_DECL(pj_status_t) pj_stun_msg_add_attr(pj_stun_msg *msg, * * @return PJ_SUCCESS on success or the appropriate error code. */ -PJ_DECL(pj_status_t) pj_stun_msg_encode(const pj_stun_msg *msg, +PJ_DECL(pj_status_t) pj_stun_msg_encode(pj_stun_msg *msg, pj_uint8_t *pkt_buf, unsigned buf_size, unsigned options, @@ -1422,8 +1424,8 @@ PJ_DECL(pj_stun_attr_hdr*) pj_stun_msg_find_attr(const pj_stun_msg *msg, * @param attr_type Attribute type, from #pj_stun_attr_type. * @param xor_ed If non-zero, the port and address will be XOR-ed * with magic, to make the XOR-MAPPED-ADDRESS attribute. - * @param addr_len Length of \a addr parameter. * @param addr A pj_sockaddr_in or pj_sockaddr_in6 structure. + * @param addr_len Length of \a addr parameter. * @param p_attr Pointer to receive the attribute. * * @return PJ_SUCCESS on success or the appropriate error code. @@ -1432,8 +1434,8 @@ PJ_DECL(pj_status_t) pj_stun_generic_ip_addr_attr_create(pj_pool_t *pool, int attr_type, pj_bool_t xor_ed, - unsigned addr_len, const pj_sockaddr_t *addr, + unsigned addr_len, pj_stun_generic_ip_addr_attr **p_attr); @@ -1447,8 +1449,8 @@ pj_stun_generic_ip_addr_attr_create(pj_pool_t *pool, * @param attr_type Attribute type, from #pj_stun_attr_type. * @param xor_ed If non-zero, the port and address will be XOR-ed * with magic, to make the XOR-MAPPED-ADDRESS attribute. - * @param addr_len Length of \a addr parameter. * @param addr A pj_sockaddr_in or pj_sockaddr_in6 structure. + * @param addr_len Length of \a addr parameter. * * @return PJ_SUCCESS on success or the appropriate error code. */ @@ -1457,8 +1459,8 @@ pj_stun_msg_add_generic_ip_addr_attr(pj_pool_t *pool, pj_stun_msg *msg, int attr_type, pj_bool_t xor_ed, - unsigned addr_len, - const pj_sockaddr_t *addr); + const pj_sockaddr_t *addr, + unsigned addr_len); /** * Create a STUN generic string attribute. diff --git a/pjlib-util/include/pjlib-util/stun_session.h b/pjlib-util/include/pjlib-util/stun_session.h index 057b35aa..94ea9ff6 100644 --- a/pjlib-util/include/pjlib-util/stun_session.h +++ b/pjlib-util/include/pjlib-util/stun_session.h @@ -24,6 +24,17 @@ #include #include +PJ_BEGIN_DECL + + +/* **************************************************************************/ +/** + * @defgroup PJLIB_UTIL_STUN_SESSION STUN Client/Server Session + * @brief STUN client and server session + * @ingroup PJLIB_UTIL_STUN + * @{ + */ + /** Forward declaration for pj_stun_tx_data */ typedef struct pj_stun_tx_data pj_stun_tx_data; @@ -31,6 +42,7 @@ typedef struct pj_stun_tx_data pj_stun_tx_data; /** Forward declaration for pj_stun_session */ typedef struct pj_stun_session pj_stun_session; + /** * This is the callback to be registered to pj_stun_session, to send * outgoing message and to receive various notifications from the STUN @@ -51,49 +63,40 @@ typedef struct pj_stun_session_cb * @return The callback should return the status of the * packet sending. */ - pj_status_t (*on_send_msg)(pj_stun_tx_data *tdata, + pj_status_t (*on_send_msg)(pj_stun_session *sess, const void *pkt, pj_size_t pkt_size, - unsigned addr_len, - const pj_sockaddr_t *dst_addr); - - /** - * Callback to be called when Binding response is received or the - * transaction has timed out. + const pj_sockaddr_t *dst_addr, + unsigned addr_len); + + /** + * Callback to be called on incoming 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 + * the callback. * * @param sess The STUN session. - * @param status Status of the request. If the value if not - * PJ_SUCCESS, the transaction has timed-out - * or other error has occurred, and the response - * argument may be NULL. - * @param request The original STUN request. - * @param response The response message, on successful transaction. - */ - void (*on_bind_response)(pj_stun_session *sess, - pj_status_t status, - pj_stun_tx_data *request, - const pj_stun_msg *response); - - /** - * Callback to be called when Allocate response is received or the - * transaction has timed out. + * @param pkt Pointer to the original STUN packet. + * @param pkt_len Length of the STUN packet. + * @param msg The parsed STUN request. + * @param src_addr Source address of the packet. + * @param src_addr_len Length of the source address. * - * @param sess The STUN session. - * @param status Status of the request. If the value if not - * PJ_SUCCESS, the transaction has timed-out - * or other error has occurred, and the response - * argument may be NULL. - * @param request The original STUN request. - * @param response The response message, on successful transaction. + * @return The return value of this callback will be + * returned back to pj_stun_session_on_rx_pkt() + * function. */ - void (*on_allocate_response)(pj_stun_session *sess, - pj_status_t status, - pj_stun_tx_data *request, - const pj_stun_msg *response); + pj_status_t (*on_rx_request)(pj_stun_session *sess, + const pj_uint8_t *pkt, + unsigned pkt_len, + const pj_stun_msg *msg, + const pj_sockaddr_t *src_addr, + unsigned src_addr_len); /** - * Callback to be called when Set Active Destination response is received - * or the transaction has timed out. + * Callback to be called when response is received or the transaction + * has timed out. * * @param sess The STUN session. * @param status Status of the request. If the value if not @@ -103,27 +106,22 @@ typedef struct pj_stun_session_cb * @param request The original STUN request. * @param response The response message, on successful transaction. */ - void (*on_set_active_destination_response)(pj_stun_session *sess, - pj_status_t status, - pj_stun_tx_data *request, - const pj_stun_msg *response); + void (*on_request_complete)(pj_stun_session *sess, + pj_status_t status, + pj_stun_tx_data *tdata, + const pj_stun_msg *response); + /** - * Callback to be called when Connect response is received or the - * transaction has timed out. - * - * @param sess The STUN session. - * @param status Status of the request. If the value if not - * PJ_SUCCESS, the transaction has timed-out - * or other error has occurred, and the response - * argument may be NULL. - * @param request The original STUN request. - * @param response The response message, on successful transaction. + * Type of callback to be called on incoming STUN indication. */ - void (*on_connect_response)( pj_stun_session *sess, - pj_status_t status, - pj_stun_tx_data *request, - const pj_stun_msg *response); + pj_status_t (*on_rx_indication)(pj_stun_session *sess, + const pj_uint8_t *pkt, + unsigned pkt_len, + const pj_stun_msg *msg, + const pj_sockaddr_t *src_addr, + unsigned src_addr_len); + } pj_stun_session_cb; @@ -360,6 +358,32 @@ PJ_DECL(pj_status_t) pj_stun_session_create_send_ind(pj_stun_session *sess, PJ_DECL(pj_status_t) pj_stun_session_create_data_ind(pj_stun_session *sess, pj_stun_tx_data **p_tdata); +/** + * Create a STUN response message. After the message has been + * successfully created, application can send the message by calling + * pj_stun_session_send_msg(). + * + * @param sess The STUN session instance. + * @param req The STUN request where the response is to be created. + * @param err_code Error code to be set in the response, if error response + * is to be created, according to pj_stun_status enumeration. + * This argument MUST be zero if successful response is + * to be created. + * @param err_msg Optional pointer for the error message string, when + * creating error response. If the value is NULL and the + * \a err_code is non-zero, then default error message will + * be used. + * @param p_tdata Pointer to receive the response message created. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_stun_session_create_response(pj_stun_session *sess, + const pj_stun_msg *req, + unsigned err_code, + const pj_str_t *err_msg, + pj_stun_tx_data **p_tdata); + + /** * Send STUN message to the specified destination. This function will encode * the pj_stun_msg instance to a packet buffer, and add credential or @@ -372,8 +396,8 @@ PJ_DECL(pj_status_t) pj_stun_session_create_data_ind(pj_stun_session *sess, * * @param sess The STUN session instance. * @param options Optional flags, from pj_stun_session_option. - * @param addr_len Length of destination address. * @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 * be sent. * @@ -381,8 +405,8 @@ PJ_DECL(pj_status_t) pj_stun_session_create_data_ind(pj_stun_session *sess, */ PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess, unsigned options, - unsigned addr_len, const pj_sockaddr_t *dst_addr, + unsigned addr_len, pj_stun_tx_data *tdata); /** @@ -402,6 +426,7 @@ PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess, * @param sess The STUN session instance. * @param packet The packet containing STUN message. * @param pkt_size Size of the packet. + * @param options Options, from pj_stun_options. * @param parsed_len Optional pointer to receive the size of the parsed * STUN message (useful if packet is received via a * stream oriented protocol). @@ -411,9 +436,31 @@ PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess, PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess, const void *packet, pj_size_t pkt_size, - unsigned *parsed_len); + unsigned options, + unsigned *parsed_len, + const pj_sockaddr_t *src_addr, + unsigned src_addr_len); + +/** + * Destroy the transmit data. Call this function only when tdata has been + * created but application doesn't want to send the message (perhaps + * because of other error). + * + * @param sess The STUN session. + * @param tdata The transmit data. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(void) pj_stun_msg_destroy_tdata(pj_stun_session *sess, + pj_stun_tx_data *tdata); + + +/** + * @} + */ +PJ_END_DECL #endif /* __PJLIB_UTIL_STUN_SESSION_H__ */ -- cgit v1.2.3