Continuing work on the new STUN framework, partly implemented the client session

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

2 files changed, 55 insertions, 5 deletions

diff --git a/pjlib-util/include/pjlib-util/stun_msg.h b/pjlib-util/include/pjlib-util/stun_msg.h
index e8a4f1af..f5e697f0 100644
--- a/pjlib-util/include/pjlib-util/stun_msg.h
+++ b/pjlib-util/include/pjlib-util/stun_msg.h
@@ -1190,11 +1190,28 @@ PJ_DECL(pj_status_t) pj_stun_msg_encode(const pj_stun_msg *msg,
 
 
 /**
+ * Dump STUN message to a printable string output.
+ *
+ * @param msg		The STUN message
+ * @param buffer	Buffer where the printable string output will
+ *			be printed on.
+ * @param length	On input, specify the maximum length of the buffer.
+ *			On output, it will be filled up with the actual
+ *			length of the output string.
+ *
+ * @return		The message string output.
+ */
+PJ_DECL(char*) pj_stun_msg_dump(const pj_stun_msg *msg,
+			        char *buffer,
+			        unsigned *length);
+
+
+/**
  * Find STUN attribute in the STUN message, starting from the specified
  * index.
  *
  * @param msg		The STUN message.
- * @param attr_type	The attribute type to be found.
+ * @param attr_type	The attribute type to be found, from pj_stun_attr_type.
  * @param start_index	The start index of the attribute in the message.
  *			Specify zero to start searching from the first
  *			attribute.
@@ -1212,7 +1229,7 @@ PJ_DECL(pj_stun_attr_hdr*) pj_stun_msg_find_attr(const pj_stun_msg *msg,
  * the port and ip_addr parameters are in host byte order.
  *
  * @param pool		The pool to allocate memory from.
- * @param attr_type	Attribute type.
+ * @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.
@@ -1234,6 +1251,7 @@ pj_stun_generic_ip_addr_attr_create(pj_pool_t *pool,
  * Create a STUN generic string attribute.
  *
  * @param pool		The pool to allocate memory from.
+ * @param attr_type	Attribute type, from #pj_stun_attr_type.
  * @param value		The string value to be assigned to the attribute.
  * @param p_attr	Pointer to receive the attribute.
  *
@@ -1315,7 +1333,7 @@ pj_stun_unknown_attr_create(pj_pool_t *pool,
  * Create a blank binary attribute.
  *
  * @param pool		The pool to allocate memory from.
- * @param attr_type	The attribute type.
+ * @param attr_type	The attribute type, from #pj_stun_attr_type.
  * @param p_attr	Pointer to receive the attribute.
  *
  * @return		PJ_SUCCESS on success or the appropriate error code.
diff --git a/pjlib-util/include/pjlib-util/stun_transaction.h b/pjlib-util/include/pjlib-util/stun_transaction.h
index 2cacef36..ee57d11e 100644
--- a/pjlib-util/include/pjlib-util/stun_transaction.h
+++ b/pjlib-util/include/pjlib-util/stun_transaction.h
@@ -73,7 +73,7 @@ typedef struct pj_stun_tsx_cb
      */
     void	(*on_complete)(pj_stun_client_tsx *tsx,
 			       pj_status_t status, 
-			       pj_stun_msg *response);
+			       const pj_stun_msg *response);
 
     /**
      * This callback is called by the STUN transaction when it wants to send
@@ -124,6 +124,16 @@ PJ_DECL(pj_status_t) pj_stun_client_tsx_destroy(pj_stun_client_tsx *tsx);
 
 
 /**
+ * Check if transaction has completed.
+ *
+ * @param tsx		The STUN transaction.
+ *
+ * @return		Non-zero if transaction has completed.
+ */
+PJ_DECL(pj_bool_t) pj_stun_client_tsx_is_complete(pj_stun_client_tsx *tsx);
+
+
+/**
  * Associate an arbitrary data with the STUN transaction. This data
  * can be then retrieved later from the transaction, by using
  * pj_stun_client_tsx_get_data() function.
@@ -186,12 +196,34 @@ PJ_DECL(pj_status_t) pj_stun_client_tsx_send_msg(pj_stun_client_tsx *tsx,
  *
  * @return		PJ_SUCCESS on success or the appropriate error code.
  */
-PJ_DECL(pj_status_t) pj_stun_client_tsx_on_rx_msg(pj_stun_client_tsx *tsx,
+PJ_DECL(pj_status_t) pj_stun_client_tsx_on_rx_pkt(pj_stun_client_tsx *tsx,
 						  const void *packet,
 						  pj_size_t pkt_size,
 						  unsigned *parsed_len);
 
 
+/**
+ * Notify the STUN transaction about the arrival of STUN response.
+ * If the STUN response contains a final error (300 and greater), the
+ * transaction will be terminated and callback will be called. If the
+ * STUN response contains response code 100-299, retransmission
+ * will  cease, but application must still call this function again
+ * with a final response later to allow the transaction to complete.
+ *
+ * @param tsx		The STUN client transaction instance.
+ * @param packet	The incoming packet.
+ * @param pkt_size	Size of the incoming packet.
+ * @param parsed_len	Optional pointer to receive the number of bytes
+ *			that have been parsed from the incoming packet
+ *			for the STUN message. This is useful if the
+ *			STUN transaction is running over stream oriented
+ *			socket such as TCP or TLS.
+ *
+ * @return		PJ_SUCCESS on success or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_stun_client_tsx_on_rx_msg(pj_stun_client_tsx *tsx,
+						  const pj_stun_msg *msg);
+
 
 /**
  * @}