Changeset 1748 for pjproject/trunk/pjmedia/include/pjmedia/transport.h

Timestamp:

Jan 25, 2008 4:06:33 PM (16 years ago)

Author:

bennylp

Message:

Fixed doxygen comments everywhere

File:

• pjproject/trunk/pjmedia/include/pjmedia/transport.h (modified) (7 diffs)

pjproject/trunk/pjmedia/include/pjmedia/transport.h

@@ -57 +57 @@
  * #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
  *
@@ -136 +142 @@
  *
  *
+ * \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
  *
@@ -169 +208 @@
 #include <pjmedia/sdp.h>
 
-/*
+/**
  * Forward declaration for media transport.
  */
@@ -459 +498 @@
  * 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.
@@ -466 +511 @@
  * @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.
@@ -481 +527 @@
 /**
  * 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.
@@ -504 +559 @@
 /**
  * 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.