Moved stun_session from client to library

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@1008 74dad513-b988-da41-8d7b-12977e46ad98

2 files changed, 420 insertions, 0 deletions

diff --git a/pjlib-util/include/pjlib-util.h b/pjlib-util/include/pjlib-util.h
index 2b3326b4..7c8e2ad4 100644
--- a/pjlib-util/include/pjlib-util.h
+++ b/pjlib-util/include/pjlib-util.h
@@ -52,6 +52,7 @@
 #include <pjlib-util/stun_endpoint.h>
 #include <pjlib-util/stun_msg.h>
 #include <pjlib-util/stun_server.h>
+#include <pjlib-util/stun_session.h>
 #include <pjlib-util/stun_transaction.h>
 
 /* Old STUN */
diff --git a/pjlib-util/include/pjlib-util/stun_session.h b/pjlib-util/include/pjlib-util/stun_session.h
new file mode 100644
index 00000000..057b35aa
--- /dev/null
+++ b/pjlib-util/include/pjlib-util/stun_session.h
@@ -0,0 +1,419 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2003-2005 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 __PJLIB_UTIL_STUN_SESSION_H__
+#define __PJLIB_UTIL_STUN_SESSION_H__
+
+#include <pjlib-util/stun_msg.h>
+#include <pjlib-util/stun_endpoint.h>
+#include <pjlib-util/stun_transaction.h>
+#include <pj/list.h>
+
+
+/** Forward declaration for pj_stun_tx_data */
+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
+ * session.
+ */
+typedef struct pj_stun_session_cb
+{
+    /**
+     * Callback to be called by the STUN session to send outgoing message.
+     *
+     * @param tdata	    The STUN transmit data containing the original
+     *			    STUN message
+     * @param pkt	    Packet to be sent.
+     * @param pkt_size	    Size of the packet to be sent.
+     * @param addr_len	    Length of destination address.
+     * @param dst_addr	    The destination address.
+     *
+     * @return		    The callback should return the status of the
+     *			    packet sending.
+     */
+    pj_status_t (*on_send_msg)(pj_stun_tx_data *tdata,
+			       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.
+     *
+     * @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 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_allocate_response)(pj_stun_session *sess, 
+				 pj_status_t status, 
+				 pj_stun_tx_data *request,
+				 const pj_stun_msg *response);
+
+    /**
+     * Callback to be called when Set Active Destination 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.
+     */
+    void (*on_set_active_destination_response)(pj_stun_session *sess, 
+					       pj_status_t status, 
+					       pj_stun_tx_data *request,
+					       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.
+     */
+    void (*on_connect_response)( pj_stun_session *sess, 
+				 pj_status_t status, 
+				 pj_stun_tx_data *request,
+				 const pj_stun_msg *response);
+} pj_stun_session_cb;
+
+
+/**
+ * This structure describe the outgoing STUN transmit data to carry the
+ * message to be sent.
+ */
+struct pj_stun_tx_data
+{
+    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		*user_data;	/**< Arbitrary user data.	    */
+
+    pj_stun_client_tsx	*client_tsx;	/**< Client STUN transaction.	    */
+    pj_uint8_t		 client_key[12];/**< Client transaction key.	    */
+
+    void		*pkt;		/**< The STUN packet.		    */
+    unsigned		 max_len;	/**< Length of packet buffer.	    */
+    unsigned		 pkt_size;	/**< The actual length of STUN pkt. */
+
+    unsigned		 addr_len;	/**< Length of destination address. */
+    const pj_sockaddr_t	*dst_addr;	/**< Destination address.	    */
+};
+
+
+/**
+ * Options that can be specified when creating or sending outgoing STUN
+ * messages. These options may be specified as bitmask.
+ */
+enum pj_stun_session_option
+{
+    /**
+     * Add short term credential to the message. This option may not be used
+     * together with PJ_STUN_USE_LONG_TERM_CRED option.
+     */
+    PJ_STUN_USE_SHORT_TERM_CRED	= 1,
+
+    /**
+     * Add long term credential to the message. This option may not be used
+     * together with PJ_STUN_USE_SHORT_TERM_CRED option.
+     */
+    PJ_STUN_USE_LONG_TERM_CRED	= 2,
+
+    /**
+     * Add STUN fingerprint to the message.
+     */
+    PJ_STUN_USE_FINGERPRINT	= 4
+};
+
+
+/**
+ * Create a STUN session.
+ *
+ * @param endpt	    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 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_endpoint *endpt,
+					    const char *name,
+					    const pj_stun_session_cb *cb,
+					    pj_stun_session **p_sess);
+
+/**
+ * Destroy the STUN session.
+ *
+ * @param sess	    The STUN session instance.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+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.
+ *
+ * @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);
+
+/**
+ * Save a long term credential to be used by this STUN session when sending
+ * outgoing messages. After long term credential is configured, application
+ * may specify PJ_STUN_USE_LONG_TERM_CRED option when sending outgoing STUN
+ * message to send the long term credential in the message.
+ *
+ * @param sess	    The STUN session instance.
+ * @param realm	    Realm of the long term credential.
+ * @param user	    The user name.
+ * @param passwd    The pain-text password.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) 
+pj_stun_session_set_long_term_credential(pj_stun_session *sess,
+					 const pj_str_t *realm,
+					 const pj_str_t *user,
+					 const pj_str_t *passwd);
+
+
+/**
+ * Save a short term credential to be used by this STUN session when sending
+ * outgoing messages. After short term credential is configured, application
+ * may specify PJ_STUN_USE_SHORT_TERM_CRED option when sending outgoing STUN
+ * message to send the short term credential in the message.
+ *
+ * @param sess	    The STUN session instance.
+ * @param user	    The user name.
+ * @param passwd    The pain-text password.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) 
+pj_stun_session_set_short_term_credential(pj_stun_session *sess,
+					  const pj_str_t *user,
+					  const pj_str_t *passwd);
+
+/**
+ * Create a STUN Bind 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 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_bind_req(pj_stun_session *sess,
+						     pj_stun_tx_data **p_tdata);
+
+/**
+ * Create a STUN Allocate 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 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_allocate_req(pj_stun_session *sess,
+							 pj_stun_tx_data **p_tdata);
+
+/**
+ * Create a STUN Set Active Destination 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 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_set_active_destination_req(pj_stun_session *sess,
+						  pj_stun_tx_data **p_tdata);
+
+/**
+ * Create a STUN Connect 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 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_connect_req(pj_stun_session *sess,
+							pj_stun_tx_data **p_tdata);
+
+/**
+ * Create a STUN Connection Status 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 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_connection_status_ind(pj_stun_session *sess,
+					     pj_stun_tx_data **p_tdata);
+
+/**
+ * Create a STUN Send 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 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_send_ind(pj_stun_session *sess,
+						     pj_stun_tx_data **p_tdata);
+
+/**
+ * Create a STUN Data 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 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_data_ind(pj_stun_session *sess,
+						     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 options   Optional flags, from pj_stun_session_option.
+ * @param addr_len  Length of destination address.
+ * @param dst_addr  The destination socket address.
+ * @param tdata	    The STUN transmit data containing the STUN message to
+ *		    be sent.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+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,
+					      pj_stun_tx_data *tdata);
+
+/**
+ * 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 parsed_len Optional pointer to receive the size of the parsed
+ *		     STUN message (useful if packet is received via a
+ *		     stream oriented protocol).
+ *
+ * @return	     PJ_SUCCESS on success, or the appropriate error code.
+ */
+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);
+
+
+
+#endif	/* __PJLIB_UTIL_STUN_SESSION_H__ */
+