Changeset 929 for pjproject/branches/iceproject/pjlib-util/include/pjlib-util/stun_transaction.h

Timestamp:

Feb 3, 2007 8:31:33 PM (17 years ago)

Author:

bennylp

Message:

ICE branch: initial server prototype

File:

• pjproject/branches/iceproject/pjlib-util/include/pjlib-util/stun_transaction.h (modified) (8 diffs)

pjproject/branches/iceproject/pjlib-util/include/pjlib-util/stun_transaction.h

@@ -1 @@
-/* $Id */
+/* $Id$ */
 /* 
  * Copyright (C) 2003-2005 Benny Prijono <benny@prijono.org>
@@ -38 +38 @@
  * @ingroup PJLIB_UTIL_STUN
  * @{
+ *
+ The @ref PJLIB_UTIL_STUN_TRANSACTION is used to manage outgoing STUN request,
+ for example to retransmit the request and to notify application about the
+ completion of the request.
+
+ The @ref PJLIB_UTIL_STUN_TRANSACTION does not use any networking operations,
+ but instead application must supply the transaction with a callback to
+ be used by the transaction to send outgoing requests. This way the STUN
+ transaction is made more generic and can work with different types of
+ networking codes in application.
+
+
  */
 
@@ -50 +62 @@
 typedef struct pj_stun_tsx_cb
 {
+    /**
+     * This callback is called when the STUN transaction completed.
+     *
+     * @param tsx           The STUN transaction.
+     * @param status        Status of the transaction. Status PJ_SUCCESS
+     *                      means that the request has received a successful
+     *                      response.
+     * @param response      The STUN response, which value may be NULL if
+     *                      \a status is not PJ_SUCCESS.
+     */
     void        (*on_complete)(pj_stun_client_tsx *tsx,
                                pj_status_t status, 
                                pj_stun_msg *response);
+
+    /**
+     * This callback is called by the STUN transaction when it wants to send
+     * outgoing message.
+     *
+     * @param tsx           The STUN transaction instance.
+     * @param stun_pkt      The STUN packet to be sent.
+     * @param pkt_size      Size of the STUN packet.
+     *
+     * @return              If return value of the callback is not PJ_SUCCESS,
+     *                      the transaction will fail.
+     */
     pj_status_t (*on_send_msg)(pj_stun_client_tsx *tsx,
                                const void *stun_pkt,
@@ -62 +96 @@
 
 /**
- * Create a STUN client transaction.
+ * Create an instance of STUN client transaction. The STUN client 
+ * transaction is used to transmit outgoing STUN request and to 
+ * ensure the reliability of the request by periodically retransmitting
+ * the request, if necessary.
+ *
+ * @param endpt         The STUN endpoint, which will be used to retrieve
+ *                      various settings for the transaction.
+ * @param cb            Callback structure, to be used by the transaction
+ *                      to send message and to notify the application about
+ *                      the completion of the transaction.
+ * @param p_tsx         Pointer to receive the transaction instance.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error code.
  */
 PJ_DECL(pj_status_t) pj_stun_client_tsx_create( pj_stun_endpoint *endpt,
@@ -69 +115 @@
 
 /**
- * .
+ * Destroy a STUN client transaction.
+ *
+ * @param tsx           The STUN transaction.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error code.
  */
 PJ_DECL(pj_status_t) pj_stun_client_tsx_destroy(pj_stun_client_tsx *tsx);
@@ -75 +125 @@
 
 /**
- * .
+ * 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.
+ *
+ * @param tsx           The STUN client transaction.
+ * @param data          Application data to be associated with the
+ *                      STUN transaction.
+ *
+ * @return              PJ_SUCCESS on success.
  */
 PJ_DECL(pj_status_t) pj_stun_client_tsx_set_data(pj_stun_client_tsx *tsx,
@@ -82 +140 @@
 
 /**
- * .
+ * Get the user data that was previously associated with the STUN 
+ * transaction.
+ *
+ * @param tsx           The STUN client transaction.
+ *
+ * @return              The user data.
  */
 PJ_DECL(void*) pj_stun_client_tsx_get_data(pj_stun_client_tsx *tsx);
@@ -88 +151 @@
 
 /**
- * .
+ * Start the STUN client transaction by sending STUN request using
+ * this transaction. If reliable transport such as TCP or TLS is used,
+ * the retransmit flag should be set to PJ_FALSE because reliablity
+ * will be assured by the transport layer.
+ *
+ * @param tsx           The STUN client transaction.
+ * @param retransmit    Should this message be retransmitted by the
+ *                      STUN transaction.
+ * @param msg           The STUN message.
+ *
+ * @return              PJ_SUCCESS on success or the appropriate error code.
  */
 PJ_DECL(pj_status_t) pj_stun_client_tsx_send_msg(pj_stun_client_tsx *tsx,
+                                                 pj_bool_t retransmit,
                                                  const pj_stun_msg *msg);
 
 
 /**
- * .
+ * 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,