Fixed doxygen comments everywhere

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

4 files changed, 118 insertions, 8 deletions

diff --git a/pjmedia/docs/doxygen.cfg b/pjmedia/docs/doxygen.cfg
index 50f8f201..e2fa0889 100644
--- a/pjmedia/docs/doxygen.cfg
+++ b/pjmedia/docs/doxygen.cfg
@@ -843,8 +843,15 @@ INCLUDE_FILE_PATTERNS  =
 

 PREDEFINED             = PJ_DECL(x)=x PJ_DEF(x)=x PJ_IDECL(x)=x \

 			 PJ_IDEF(x)=x PJ_INLINE(x)=x \

-			 PJ_BEGIN_DECL= PJ_END_DECL= \

-			 PJMEDIA_HAS_MP3_WRITER=1

+			 PJ_DECL_DATA(x)=x \

+			 PJ_DECL_NO_RETURN(x)=x \

+			 PJ_NO_RETURN=x \

+			 PJ_HAS_HIGH_RES_TIMER=1 \

+			 PJ_LOG_MAX_LEVEL=4 \

+			 PJ_HAS_SEMAPHORE=1 \

+			 PJ_HAS_EVENT_OBJ=1 \

+			 PJ_HAS_TCP=1 \

+			 PJMEDIA_HAS_SRTP=1

 

 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 

 # this tag can be used to specify a list of macro names that should be expanded. 

diff --git a/pjmedia/include/pjmedia/transport.h b/pjmedia/include/pjmedia/transport.h
index e9fbb1f3..14b84e7d 100644
--- a/pjmedia/include/pjmedia/transport.h
+++ b/pjmedia/include/pjmedia/transport.h
@@ -56,6 +56,12 @@
  * so it should not need to call the function pointer inside 
  * #pjmedia_transport_op directly.
  *
+ * The connection between \ref PJMED_STRM and media transport is shown in
+ * the diagram below:
+
+   \image html media-transport.PNG
+
+
  * \section PJMEDIA_TRANSPORT_H_USING Using the Media Transport
  *
  * The media transport's life-cycle normally follows the following stages.
@@ -135,6 +141,39 @@
  *    all resources used by the transport, such as sockets and memory.
  *
  *
+ * \section PJMEDIA_TRANSPORT_H_EXT Media Transport Extended API
+ 
+   Apart from the basic interface above, the media transport provides some
+   more APIs:
+
+    - pjmedia_transport_media_create()
+   \n
+      This API is provided to allow the media transport to add more information
+      in the SDP offer, before the offer is sent to remote. Additionally, for 
+      answerer side, this callback allows the media transport to reject the 
+      offer before this offer is processed by the SDP negotiator. 
+
+    - pjmedia_transport_media_start()
+    \n
+      This API should be called after offer and answer are negotiated, and 
+      both SDPs are available, and before the media is started. For answerer
+      side, this callback will be called before the answer is sent to remote,
+      to allow media transport to put additional info in the SDP. For 
+      offerer side, this callback will be called after SDP answer is 
+      received. In this callback, the media transport has the final chance 
+      to negotiate/validate the offer and answer before media is really 
+      started (and answer is sent, for answerer side). 
+
+    - pjmedia_transport_media_stop()
+    \n
+      This API should be called when the media is stopped, to allow the media
+      transport to release its resources. 
+
+    - pjmedia_transport_simulate_lost()
+    \n
+      This API can be used to instruct media transport to simulate packet lost
+      on a particular direction.
+
  * \section PJMEDIA_TRANSPORT_H_IMPL Implementing Media Transport
  *
  * To implement a new type of media transport, one needs to "subclass" the
@@ -168,7 +207,7 @@ PJ_BEGIN_DECL
 
 #include <pjmedia/sdp.h>
 
-/*
+/**
  * Forward declaration for media transport.
  */
 typedef struct pjmedia_transport pjmedia_transport;
@@ -458,6 +497,12 @@ PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp(pjmedia_transport *tp,
  * Generate local SDP parts that are related to the specified media transport.
  * Remote SDP might be needed as reference when application is in deciding
  * side of negotiation (callee side), otherwise it should be NULL.
+ *
+ * This API is provided to allow the media transport to add more information
+ * in the SDP offer, before the offer is sent to remote. Additionally, for 
+ * answerer side, this callback allows the media transport to reject the 
+ * offer before this offer is processed by the SDP negotiator. 
+ *
  * This is just a simple wrapper which calls <tt>media_create()</tt> member 
  * of the transport.
  *
@@ -465,6 +510,7 @@ PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp(pjmedia_transport *tp,
  * @param pool		The memory pool.
  * @param sdp_local	Local SDP.
  * @param sdp_remote	Remote SDP.
+ * @param media_index	Media index in SDP.
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
  */
@@ -480,6 +526,15 @@ PJ_INLINE(pj_status_t) pjmedia_transport_media_create(pjmedia_transport *tp,
 
 /**
  * Start the transport with regards to SDP negotiation result. 
+ * This API should be called after offer and answer are negotiated, and 
+ * both SDPs are available, and before the media is started. For answerer
+ * side, this callback will be called before the answer is sent to remote,
+ * to allow media transport to put additional info in the SDP. For 
+ * offerer side, this callback will be called after SDP answer is 
+ * received. In this callback, the media transport has the final chance 
+ * to negotiate/validate the offer and answer before media is really 
+ * started (and answer is sent, for answerer side). 
+ *
  * This is just a simple wrapper which calls <tt>media_start()</tt> member 
  * of the transport.
  *
@@ -503,6 +558,9 @@ PJ_INLINE(pj_status_t) pjmedia_transport_media_start(pjmedia_transport *tp,
 
 /**
  * Stop the transport. 
+ * This API should be called when the media is stopped, to allow the media
+ * transport to release its resources. 
+ *
  * This is just a simple wrapper which calls <tt>media_stop()</tt> member 
  * of the transport.
  *
diff --git a/pjmedia/include/pjmedia/transport_srtp.h b/pjmedia/include/pjmedia/transport_srtp.h
index f7ea291d..d6ccc2e1 100644
--- a/pjmedia/include/pjmedia/transport_srtp.h
+++ b/pjmedia/include/pjmedia/transport_srtp.h
@@ -21,12 +21,52 @@
 
 /**
  * @file srtp.h
- * @brief transport SRTP encapsulates secure media transport.
+ * @brief Secure RTP (SRTP) transport.
  */
 
 #include <pjmedia/transport.h>
 
 
+/**
+ * @defgroup PJMEDIA_TRANSPORT_SRTP Secure RTP (SRTP) Transport Adapter
+ * @ingroup PJMEDIA_TRANSPORT
+ * @brief Media transport adapter to add SRTP feature to existing transports
+ * @{
+ *
+ * This module implements SRTP as described by RFC 3711, using RFC 4568 as
+ * key exchange method. It implements \ref PJMEDIA_TRANSPORT_H to integrate
+ * with the rest of PJMEDIA framework.
+ *
+ * As we know, media transport is separated from the stream object (which 
+ * does the encoding/decoding of PCM frames, (de)packetization of RTP/RTCP 
+ * packets, and de-jitter buffering). The connection between stream and media
+ * transport is established when the stream is created (we need to specify 
+ * media transport during stream creation), and the interconnection can be 
+ * depicted from the diagram below:
+ *
+   \image html media-transport.PNG
+
+ * I think the diagram above is self-explanatory.
+ *
+ * SRTP functionality is implemented as some kind of "adapter", which is 
+ * plugged between the stream and the actual media transport that does 
+ * sending/receiving RTP/RTCP packets. When SRTP is used, the interconnection
+ * between stream and transport is like the diagram below:
+ *
+    \image html media-srtp-transport.PNG
+
+ * So to stream, the SRTP transport behaves as if it is a media transport 
+ * (because it is a media transport), and to the media transport it behaves
+ * as if it is a stream. The SRTP object then forwards RTP packets back and
+ * forth between stream and the actual transport, encrypting/decrypting 
+ * the RTP/RTCP packets as necessary.
+ * 
+ * The neat thing about this design is the SRTP "adapter" then can be used 
+ * to encrypt any kind of media transports. We currently have UDP and ICE 
+ * media transports that can benefit SRTP, and we could add SRTP to any 
+ * media transports that will be added in the future. 
+ */
+
 PJ_BEGIN_DECL
 
 
@@ -55,7 +95,7 @@ typedef struct pjmedia_srtp_crypto
     /** Crypto name.   */
     pj_str_t	name;
 
-    /* Flags, bitmask from #pjmedia_srtp_crypto_option */
+    /** Flags, bitmask from #pjmedia_srtp_crypto_option */
     unsigned	flags;
 
 } pjmedia_srtp_crypto;
@@ -168,7 +208,7 @@ PJ_DECL(pj_status_t) pjmedia_transport_srtp_create(
  * @return	    PJ_SUCCESS on success.
  */
 PJ_DECL(pj_status_t) pjmedia_transport_srtp_start(
-					    pjmedia_transport *tp,
+					    pjmedia_transport *srtp,
 					    const pjmedia_srtp_crypto *tx,
 					    const pjmedia_srtp_crypto *rx);
 
@@ -181,7 +221,7 @@ PJ_DECL(pj_status_t) pjmedia_transport_srtp_start(
  *
  * @see #pjmedia_transport_srtp_start() 
  */
-PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *tp);
+PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *srtp);
 
 
 /**
@@ -192,9 +232,13 @@ PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *tp);
  * @return		    member media transport.
  */
 PJ_DECL(pjmedia_transport*) pjmedia_transport_srtp_get_member(
-						    pjmedia_transport *tp);
+						    pjmedia_transport *srtp);
 
 
 PJ_END_DECL
 
+/**
+ * @}
+ */
+
 #endif /* __PJMEDIA_TRANSPORT_SRTP_H__ */
diff --git a/pjmedia/src/pjmedia/transport_udp.c b/pjmedia/src/pjmedia/transport_udp.c
index a9a4df70..3caea680 100644
--- a/pjmedia/src/pjmedia/transport_udp.c
+++ b/pjmedia/src/pjmedia/transport_udp.c
@@ -748,6 +748,7 @@ static pj_status_t transport_media_create(pjmedia_transport *tp,
     PJ_UNUSED_ARG(pool);
     PJ_UNUSED_ARG(sdp_local);
     PJ_UNUSED_ARG(sdp_remote);
+    PJ_UNUSED_ARG(media_index);
 
     return PJ_SUCCESS;
 }