* #36737: switch back to svn repo, remove assert in sip_transaction.c
diff --git a/jni/pjproject-android/.svn/pristine/84/84875ad205d6fdfe5efaee07157ca92da0db1119.svn-base b/jni/pjproject-android/.svn/pristine/84/84875ad205d6fdfe5efaee07157ca92da0db1119.svn-base
new file mode 100644
index 0000000..f8ea4d1
--- /dev/null
+++ b/jni/pjproject-android/.svn/pristine/84/84875ad205d6fdfe5efaee07157ca92da0db1119.svn-base
@@ -0,0 +1,762 @@
+/* $Id$ */
+/*
+ * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
+ * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+#ifndef __PJNATH_STUN_SESSION_H__
+#define __PJNATH_STUN_SESSION_H__
+
+/**
+ * @file stun_session.h
+ * @brief STUN session management for client/server.
+ */
+
+#include <pjnath/stun_msg.h>
+#include <pjnath/stun_auth.h>
+#include <pjnath/stun_config.h>
+#include <pjnath/stun_transaction.h>
+#include <pj/list.h>
+#include <pj/lock.h>
+#include <pj/timer.h>
+
+PJ_BEGIN_DECL
+
+
+/* **************************************************************************/
+/**
+ * @addtogroup PJNATH_STUN_SESSION
+ * @{
+ *
+ * This is is a transport-independent object to manage a client or server
+ * STUN session. It has the following features:
+ *
+ * - <b>transport independent</b>:\n
+ * the object does not have it's own socket, but rather it provides
+ * functions and callbacks to send and receive packets. This way the
+ * object can be used by different transport types (e.g. UDP, TCP,
+ * TLS, etc.) as well as better integration to application which
+ * already has its own means to send and receive packets.
+ *
+ * - <b>authentication management</b>:\n
+ * the object manages STUN authentication throughout the lifetime of
+ * the session. For client sessions, once it's given a credential to
+ * authenticate itself with the server, the object will automatically
+ * add authentication info (the MESSAGE-INTEGRITY) to the request as
+ * well as authenticate the response. It will also handle long-term
+ * authentication challenges, including handling of nonce expiration,
+ * and retry the request automatically. For server sessions, it can
+ * be configured to authenticate incoming requests automatically.
+ *
+ * - <b>static or dynamic credential</b>:\n
+ * application may specify static or dynamic credential to be used by
+ * the STUN session. Static credential means a static combination of
+ * username and password (and these cannot change during the session
+ * duration), while dynamic credential provides callback to ask the
+ * application about which username/password to use everytime
+ * authentication is about to be performed.
+ *
+ * - <b>client transaction management</b>:\n
+ * outgoing requests may be sent with a STUN transaction for reliability,
+ * and the object will manage the transaction internally (including
+ * performing retransmissions). Application will be notified about the
+ * result of the request when the response arrives (or the transaction
+ * times out). When the request is challenged with authentication, the
+ * object will retry the request with new authentication info, and
+ * application will be notified about the final result of this request.
+ *
+ * - <b>server transaction management</b>:\n
+ * application may ask response to incoming requests to be cached by
+ * the object, and in this case the object will check for cached
+ * response everytime request is received. The cached response will be
+ * deleted once a timer expires.
+ *
+ * \section using_stun_sess_sec Using the STUN session
+ *
+ * The following steps describes how to use the STUN session:
+ *
+ * - <b>create the object configuration</b>:\n
+ * The #pj_stun_config contains the configuration to create the STUN
+ * session, such as the timer heap to register internal timers and
+ * various STUN timeout values. You can initialize this structure by
+ * calling #pj_stun_config_init()
+ *
+ * - <b>create the STUN session</b>:\n
+ * by calling #pj_stun_session_create(). Among other things, this
+ * function requires the instance of #pj_stun_config and also
+ * #pj_stun_session_cb structure which stores callbacks to send
+ * outgoing packets as well as to notify application about incoming
+ * STUN requests, responses, and indicates and other events.
+ *
+ * - <b>configure credential:</b>\n
+ * if authentication is required for the session, configure the
+ * credential with #pj_stun_session_set_credential()
+ *
+ * - <b>configuring other settings:</b>\n
+ * several APIs are provided to configure the behavior of the STUN
+ * session (for example, to set the SOFTWARE attribute value, controls
+ * the logging behavior, fine tune the mutex locking, etc.). Please see
+ * the API reference for more info.
+ *
+ * - <b>creating outgoing STUN requests or indications:</b>\n
+ * create the STUN message by using #pj_stun_session_create_req() or
+ * #pj_stun_session_create_ind(). This will create a transmit data
+ * buffer containing a blank STUN request or indication. You will then
+ * typically need to add STUN attributes that are relevant to the
+ * request or indication, but note that some default attributes will
+ * be added by the session later when the message is sent (such as
+ * SOFTWARE attribute and attributes related to authentication).
+ * The message is now ready to be sent.
+ *
+ * - <b>sending outgoing message:</b>\n
+ * use #pj_stun_session_send_msg() to send outgoing STUN messages (this
+ * includes STUN requests, indications, and responses). The function has
+ * options whether to retransmit the request (for non reliable transports)
+ * or to cache the response if we're sending response. This function in
+ * turn will call the \a on_send_msg() callback of #pj_stun_session_cb
+ * to request the application to send the packet.
+ *
+ * - <b>handling incoming packet:</b>\n
+ * call #pj_stun_session_on_rx_pkt() everytime the application receives
+ * a STUN packet. This function will decode the packet and process the
+ * packet according to the message, and normally this will cause one
+ * of the callback in the #pj_stun_session_cb to be called to notify
+ * the application about the event.
+ *
+ * - <b>handling incoming requests:</b>\n
+ * incoming requests are notified to application in the \a on_rx_request
+ * callback of the #pj_stun_session_cb. If authentication is enabled in
+ * the session, the application will only receive this callback after
+ * the incoming request has been authenticated (if the authentication
+ * fails, the session would respond automatically with 401 error and
+ * the callback will not be called). Application now must create and
+ * send response for this request.
+ *
+ * - <b>creating and sending response:</b>\n
+ * create the STUN response with #pj_stun_session_create_res(). This will
+ * create a transmit data buffer containing a blank STUN response. You
+ * will then typically need to add STUN attributes that are relevant to
+ * the response, but note that some default attributes will
+ * be added by the session later when the message is sent (such as
+ * SOFTWARE attribute and attributes related to authentication).
+ * The message is now ready to be sent. Use #pj_stun_session_send_msg()
+ * (as explained above) to send the response.
+ *
+ * - <b>convenient way to send response:</b>\n
+ * the #pj_stun_session_respond() is provided as a convenient way to
+ * create and send simple STUN responses, such as error responses.
+ *
+ * - <b>destroying the session:</b>\n
+ * once the session is done, use #pj_stun_session_destroy() to destroy
+ * the session.
+ */
+
+
+/** Forward declaration for pj_stun_tx_data */
+typedef struct pj_stun_tx_data pj_stun_tx_data;
+
+/** Forward declaration for pj_stun_rx_data */
+typedef struct pj_stun_rx_data pj_stun_rx_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
+ * session.
+ */
+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.
+ * @param addr_len Length of destination address.
+ *
+ * @return The callback should return the status of the
+ * 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. 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
+ * the callback.
+ *
+ * @param sess The STUN session.
+ * @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.
+ *
+ * @return The return value of this callback will be
+ * returned back to pj_stun_session_on_rx_pkt()
+ * function.
+ */
+ pj_status_t (*on_rx_request)(pj_stun_session *sess,
+ 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. 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
+ * PJ_SUCCESS, the transaction has timed-out
+ * or other error has occurred, and the response
+ * argument may be NULL.
+ * 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.
+ * Note that when the status is not success, this
+ * argument may contain non-NULL value if the
+ * response contains STUN ERROR-CODE attribute.
+ * @param src_addr The source address where the response was
+ * received, or NULL if the response is NULL.
+ * @param src_addr_len The length of the source address.
+ */
+ 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,
+ unsigned src_addr_len);
+
+
+ /**
+ * 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);
+
+} pj_stun_session_cb;
+
+
+/**
+ * This structure describes incoming request message.
+ */
+struct pj_stun_rx_data
+{
+ /**
+ * The parsed request message.
+ */
+ pj_stun_msg *msg;
+
+ /**
+ * Credential information that is found and used to authenticate
+ * incoming request. Application may use this information when
+ * generating authentication for the outgoing response.
+ */
+ pj_stun_req_cred_info info;
+};
+
+
+/**
+ * This structure describe the outgoing STUN transmit data to carry the
+ * message to be sent.
+ */
+struct pj_stun_tx_data
+{
+ /** PJLIB list interface */
+ PJ_DECL_LIST_MEMBER(struct pj_stun_tx_data);
+
+ pj_pool_t *pool; /**< Pool. */
+ pj_stun_session *sess; /**< The STUN session. */
+ pj_stun_msg *msg; /**< The STUN message. */
+
+ 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. */
+
+ pj_stun_req_cred_info auth_info; /**< Credential info */
+
+ void *pkt; /**< The STUN packet. */
+ unsigned max_len; /**< Length of packet buffer. */
+ pj_size_t pkt_size; /**< The actual length of STUN pkt. */
+
+ unsigned addr_len; /**< Length of destination address. */
+ const pj_sockaddr_t *dst_addr; /**< Destination address. */
+
+ pj_timer_entry res_timer; /**< Response cache timer. */
+};
+
+
+/**
+ * These are the flags to control the message logging in the STUN session.
+ */
+typedef enum pj_stun_sess_msg_log_flag
+{
+ PJ_STUN_SESS_LOG_TX_REQ=1, /**< Log outgoing STUN requests. */
+ PJ_STUN_SESS_LOG_TX_RES=2, /**< Log outgoing STUN responses. */
+ PJ_STUN_SESS_LOG_TX_IND=4, /**< Log outgoing STUN indications. */
+
+ PJ_STUN_SESS_LOG_RX_REQ=8, /**< Log incoming STUN requests. */
+ PJ_STUN_SESS_LOG_RX_RES=16, /**< Log incoming STUN responses */
+ PJ_STUN_SESS_LOG_RX_IND=32 /**< Log incoming STUN indications */
+} pj_stun_sess_msg_log_flag;
+
+
+/**
+ * Create a STUN session.
+ *
+ * @param cfg The STUN endpoint, to be used to register timers etc.
+ * @param name Optional name to be associated with this instance. The
+ * name will be used for example for logging purpose.
+ * @param cb Session callback.
+ * @param fingerprint Enable message fingerprint for outgoing messages.
+ * @param grp_lock Optional group lock to be used by this session.
+ * If NULL, the session will create one itself.
+ * @param p_sess Pointer to receive STUN session instance.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_create(pj_stun_config *cfg,
+ const char *name,
+ const pj_stun_session_cb *cb,
+ pj_bool_t fingerprint,
+ pj_grp_lock_t *grp_lock,
+ pj_stun_session **p_sess);
+
+/**
+ * Destroy the STUN session and all objects created in the context of
+ * this session.
+ *
+ * @param sess The STUN session instance.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error code.
+ * This function will return PJ_EPENDING if the operation
+ * cannot be performed immediately because callbacks are
+ * being called; in this case the session will be destroyed
+ * as soon as the last callback returns.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_destroy(pj_stun_session *sess);
+
+/**
+ * Associated an arbitrary data with this STUN session. The user data may
+ * be retrieved later with pj_stun_session_get_user_data() function.
+ *
+ * @param sess The STUN session instance.
+ * @param user_data The user data.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_set_user_data(pj_stun_session *sess,
+ void *user_data);
+
+/**
+ * Retrieve the user data previously associated to this STUN session with
+ * pj_stun_session_set_user_data().
+ *
+ * @param sess The STUN session instance.
+ *
+ * @return The user data associated with this STUN session.
+ */
+PJ_DECL(void*) pj_stun_session_get_user_data(pj_stun_session *sess);
+
+/**
+ * Get the group lock for this STUN session.
+ *
+ * @param sess The STUN session instance.
+ *
+ * @return The group lock.
+ */
+PJ_DECL(pj_grp_lock_t *) pj_stun_session_get_grp_lock(pj_stun_session *sess);
+
+/**
+ * Set SOFTWARE name to be included in all requests and responses.
+ *
+ * @param sess The STUN session instance.
+ * @param sw Software name string. If this argument is NULL or
+ * empty, the session will not include SOFTWARE attribute
+ * in STUN requests and responses.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_set_software_name(pj_stun_session *sess,
+ const pj_str_t *sw);
+
+/**
+ * Set credential to be used by this session. Once credential is set, all
+ * outgoing messages will include MESSAGE-INTEGRITY, and all incoming
+ * message will be authenticated against this credential.
+ *
+ * To disable authentication after it has been set, call this function
+ * again with NULL as the argument.
+ *
+ * @param sess The STUN session instance.
+ * @param auth_type Type of authentication.
+ * @param cred The credential to be used by this session. If NULL
+ * is specified, authentication will be disabled.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_set_credential(pj_stun_session *sess,
+ pj_stun_auth_type auth_type,
+ const pj_stun_auth_cred *cred);
+/**
+ * Configure message logging. By default all flags are enabled.
+ *
+ * @param sess The STUN session instance.
+ * @param flags Bitmask combination of #pj_stun_sess_msg_log_flag
+ */
+PJ_DECL(void) pj_stun_session_set_log(pj_stun_session *sess,
+ unsigned flags);
+/**
+ * Configure whether the STUN session should utilize FINGERPRINT in
+ * outgoing messages.
+ *
+ * @param sess The STUN session instance.
+ * @param use Boolean for the setting.
+ *
+ * @return The previous configured value of FINGERPRINT
+ * utilization of the sessoin.
+ */
+PJ_DECL(pj_bool_t) pj_stun_session_use_fingerprint(pj_stun_session *sess,
+ pj_bool_t use);
+
+/**
+ * Create a STUN request 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 msg_type The STUN request message type, from pj_stun_method_e or
+ * from pj_stun_msg_type.
+ * @param magic STUN magic, use PJ_STUN_MAGIC.
+ * @param tsx_id Optional transaction ID.
+ * @param p_tdata Pointer to receive STUN transmit data instance containing
+ * the request.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_create_req(pj_stun_session *sess,
+ int msg_type,
+ pj_uint32_t magic,
+ const pj_uint8_t tsx_id[12],
+ pj_stun_tx_data **p_tdata);
+
+/**
+ * Create a STUN Indication 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 msg_type The STUN request message type, from pj_stun_method_e or
+ * from pj_stun_msg_type. This function will add the
+ * indication bit as necessary.
+ * @param p_tdata Pointer to receive STUN transmit data instance containing
+ * the message.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_create_ind(pj_stun_session *sess,
+ int msg_type,
+ 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(). Alternatively application may use
+ * pj_stun_session_respond() to create and send response in one function
+ * call.
+ *
+ * @param sess The STUN session instance.
+ * @param rdata 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_res(pj_stun_session *sess,
+ const pj_stun_rx_data *rdata,
+ 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
+ * fingerprint if necessary. If the message is a request, the session will
+ * also create and manage a STUN client transaction to be used to manage the
+ * retransmission of the request. After the message has been encoded and
+ * transaction is setup, the \a on_send_msg() callback of pj_stun_session_cb
+ * (which is registered when the STUN session is created) will be called
+ * to actually send the message to the wire.
+ *
+ * @param sess The STUN session instance.
+ * @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
+ * be sent.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error code.
+ * This function will return PJNATH_ESTUNDESTROYED if
+ * application has destroyed the session in
+ * \a on_send_msg() callback.
+ */
+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);
+
+/**
+ * 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.
+ * @param 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 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
+ * will not call request callback.
+ * @param dst_addr Destination address of the response (or equal to the
+ * source address of the original request).
+ * @param addr_len Address length.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error code.
+ * This function will return PJNATH_ESTUNDESTROYED if
+ * application has destroyed the session in
+ * \a on_send_msg() callback.
+ */
+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);
+
+/**
+ * Cancel outgoing STUN transaction. This operation is only valid for outgoing
+ * STUN request, to cease retransmission of the request and destroy the
+ * STUN client transaction that is used to send the request.
+ *
+ * @param sess The STUN session instance.
+ * @param tdata The request message previously sent.
+ * @param notify Specify whether \a on_request_complete() callback should
+ * be called.
+ * @param status If \a on_request_complete() callback is to be called,
+ * specify the error status to be given when calling the
+ * callback. This error status MUST NOT be PJ_SUCCESS.
+ *
+ * @return PJ_SUCCESS if transaction is successfully cancelled.
+ * This function will return PJNATH_ESTUNDESTROYED if
+ * application has destroyed the session in
+ * \a on_request_complete() callback.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_cancel_req(pj_stun_session *sess,
+ pj_stun_tx_data *tdata,
+ pj_bool_t notify,
+ pj_status_t status);
+
+/**
+ * Explicitly request retransmission of the request. Normally application
+ * doesn't need to do this, but this functionality is needed by ICE to
+ * speed up connectivity check completion.
+ *
+ * @param sess The STUN session instance.
+ * @param tdata The request message previously sent.
+ * @param mod_count Boolean flag to indicate whether transmission count
+ * needs to be incremented.
+ *
+ * @return PJ_SUCCESS on success, or the appropriate error.
+ * This function will return PJNATH_ESTUNDESTROYED if
+ * application has destroyed the session in \a on_send_msg()
+ * callback.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_retransmit_req(pj_stun_session *sess,
+ pj_stun_tx_data *tdata,
+ pj_bool_t mod_count);
+
+
+/**
+ * Application must call this function to notify the STUN session about
+ * the arrival of STUN packet. The STUN packet MUST have been checked
+ * first with #pj_stun_msg_check() to verify that this is indeed a valid
+ * STUN packet.
+ *
+ * The STUN session will decode the packet into pj_stun_msg, and process
+ * the message accordingly. If the message is a response, it will search
+ * through the outstanding STUN client transactions for a matching
+ * transaction ID and hand over the response to the transaction.
+ *
+ * On successful message processing, application will be notified about
+ * the message via one of the pj_stun_session_cb callback.
+ *
+ * @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_decode_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).
+ * @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.
+ * This function will return PJNATH_ESTUNDESTROYED if
+ * application has destroyed the session in one of the
+ * callback.
+ */
+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,
+ pj_size_t *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 /* __PJNATH_STUN_SESSION_H__ */
+