Wed Sep 3 14:37:06 EDT 2008 Pekka Pessi <first.last@nokia.com>

  * sdp: updated documentation

git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@9503 d0543943-73ff-0310-b7d9-9358b9ac24b2

diff --git a/libs/sofia-sip/.update b/libs/sofia-sip/.update
index 3e7e9c58f91bace72e00490074e371ea111a477c..b81bfa67826d8b4e8a3184829f9ffb9d0619e15d 100644 (file)
--- a/libs/sofia-sip/.update
+++ b/libs/sofia-sip/.update
@@ -1 +1 @@
-Wed Sep  3 14:31:22 EDT 2008
+Wed Sep 10 12:19:39 EDT 2008

diff --git a/libs/sofia-sip/libsofia-sip-ua/sdp/sdp.c b/libs/sofia-sip/libsofia-sip-ua/sdp/sdp.c
index 22ed629d8db9c67376b916f86729e6fc6115155c..2d69e3bbe4eace76e862a1da8a2a72f174d04b99 100644 (file)
--- a/libs/sofia-sip/libsofia-sip-ua/sdp/sdp.c
+++ b/libs/sofia-sip/libsofia-sip-ua/sdp/sdp.c
@@ -174,11 +174,14 @@ static sdp_media_t *media_dup_all(char **pp,
 /**Duplicate an SDP origin description.
  *
  * The function sdp_origin_dup() duplicates (deeply copies) an SDP origin
- * description @a o allocating memory using memory @a home.
+ * description @a o allocating memory using memory @a home.
  *
  * @param h     Memory home
  * @param o     SDP origin description to be duplicated
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_origin_t structure is
  * returned, otherwise NULL is returned.
@@ -190,12 +193,15 @@ sdp_origin_t *sdp_origin_dup(su_home_t *h, sdp_origin_t const *o)
 
 /**Duplicate an SDP connection description.
  *
- * The function sdp_connection_dup() duplicates (deeply copies) an SDP
- * connection description @a c allocating memory using memory @a home.
+ * The function sdp_connection_dup() duplicates (deeply copies) a list of
+ * SDP connection description @a c allocating memory using memory @a home.
  *
  * @param h     Memory home
  * @param c     SDP connection description to be duplicated
  *
+ * @note The duplicated list is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_connection_t structure is
  * returned, otherwise NULL is returned.
@@ -207,12 +213,15 @@ sdp_connection_t *sdp_connection_dup(su_home_t *h, sdp_connection_t const *c)
 
 /**Duplicate an SDP bandwidth description.
  *
- * The function sdp_bandwidth_dup() duplicates (deeply copies) an SDP
- * bandwidth description @a b allocating memory using memory @a home.
+ * The function sdp_bandwidth_dup() duplicates (deeply copies) a list of SDP
+ * bandwidth descriptions @a b allocating memory using memory @a home.
  *
  * @param h     Memory home
  * @param b     SDP bandwidth description to be duplicated
  *
+ * @note The duplicated list is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_bandwidth_t structure is
  * returned, otherwise NULL is returned.
@@ -224,12 +233,15 @@ sdp_bandwidth_t *sdp_bandwidth_dup(su_home_t *h, sdp_bandwidth_t const *b)
 
 /**Duplicate an SDP time description.
  *
- * The function sdp_time_dup() duplicates (deeply copies) an SDP time
- * description @a t allocating memory using memory @a home.
+ * The function sdp_time_dup() duplicates (deeply copies) a list of SDP time
+ * descriptions @a t allocating memory using memory @a home.
  *
  * @param h  Memory home
  * @param t  SDP time description to be duplicated
  *
+ * @note The duplicated list is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_time_t structure is
  * returned, otherwise NULL is returned.
@@ -242,11 +254,14 @@ sdp_time_t *sdp_time_dup(su_home_t *h, sdp_time_t const *t)
 /**Duplicate an SDP repeat description.
  *
  * The function sdp_repeat_dup() duplicates (deeply copies) an SDP repeat
- * description @a r allocating memory using memory @a home.
+ * description @a r allocating memory using memory @a home.
  *
  * @param h  Memory home
  * @param r  SDP repeat description to be duplicated
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_repeat_t structure is
  * returned, otherwise NULL is returned.
@@ -259,11 +274,14 @@ sdp_repeat_t *sdp_repeat_dup(su_home_t *h, sdp_repeat_t const *r)
 /**Duplicate an SDP zone description.
  *
  * The function sdp_zone_dup() duplicates (deeply copies) an SDP zone
- * description @a z allocating memory using memory @a home.
+ * description @a z allocating memory using memory @a home.
  *
  * @param h  Memory home
  * @param z  SDP zone description to be duplicated
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_zone_t structure is
  * returned, otherwise NULL is returned.
@@ -276,11 +294,14 @@ sdp_zone_t *sdp_zone_dup(su_home_t *h, sdp_zone_t const *z)
 /**Duplicate an SDP key description.
  *
  * The function sdp_key_dup() duplicates (deeply copies) an SDP key
- * description @a k allocating memory using memory @a home.
+ * description @a k allocating memory using memory @a home.
  *
  * @param h  Memory home
  * @param k  SDP key description to be duplicated
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_key_t structure is
  * returned, otherwise NULL is returned.
@@ -298,6 +319,9 @@ sdp_key_t *sdp_key_dup(su_home_t *h, sdp_key_t const *k)
  * @param h  Memory home
  * @param a  SDP attribute description to be duplicated
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_attribute_t structure is
  * returned, otherwise NULL is returned.
@@ -315,6 +339,9 @@ sdp_attribute_t *sdp_attribute_dup(su_home_t *h, sdp_attribute_t const *a)
  * @param h  Memory home
  * @param l  SDP list description to be duplicated
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_list_t structure is
  * returned, otherwise NULL is returned.
@@ -332,6 +359,9 @@ sdp_list_t *sdp_list_dup(su_home_t *h, sdp_list_t const *l)
  * @param h  Memory home
  * @param rm SDP rtpmap description to be duplicated
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_rtpmap_t structure is
  * returned, otherwise NULL is returned.
@@ -344,13 +374,16 @@ sdp_rtpmap_t *sdp_rtpmap_dup(su_home_t *h, sdp_rtpmap_t const *rm)
 /**Duplicate an SDP media description.
  *
  * The function sdp_media_dup() duplicates (deeply copies) an SDP media
- * description @a m allocating memory using memory @a home.
+ * description @a m allocating memory using memory @a home.
  *
  * @param h   Memory home
  * @param m   SDP media description to be duplicated
  * @param sdp SDP session description to which the newly allocated
  *            media description is linked
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_media_t structure is
  * returned, otherwise NULL is returned.
@@ -369,13 +402,16 @@ sdp_media_t *sdp_media_dup(su_home_t *h, sdp_media_t const *m,
 /**Duplicate an SDP media description.
  *
  * The function sdp_media_dup_all() duplicates (deeply copies) a list of SDP
- * media descriptions @a m allocating memory using memory @a home.
+ * media descriptions @a m allocating memory using memory @a home.
  *
  * @param h     Memory home
  * @param m     list of SDP media descriptions to be duplicated
  * @param sdp   SDP session description to which the newly allocated
  *              media descriptions are linked
  *
+ * @note The duplicated list is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to a newly allocated list of sdp_media_t
  * structures is returned, otherwise NULL is returned.
@@ -944,11 +980,14 @@ sdp_session_t *session_dup(char **pp, sdp_session_t const *src)
 /**Duplicate an SDP session description.
  *
  * The function sdp_session_dup() duplicates (deeply copies) an SDP
- * session description @a sdp allocating memory using memory @a home.
+ * session description @a sdp allocating memory using memory @a home.
  *
  * @param h   Memory home
  * @param sdp SDP session description to be duplicated
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_session_t structure is
  * returned, otherwise NULL is returned.
@@ -1017,12 +1056,15 @@ typedef sdp_session_t sdp_session_without_media_t;
 /**Duplicate an SDP session description without media descriptions.
  *
  * The function sdp_session_dup() duplicates (deeply copies) an SDP session
- * description @a sdp allocating memory using memory @a home. It does not
+ * description @a sdp allocating memory using memory @a home. It does not
  * copy the media descriptions, however.
  *
  * @param h     memory h
  * @param sdp   SDP session description to be duplicated
  *
+ * @note The duplicated structure is allocated using a single call to
+ * su_alloc() and it can be freed with su_free().
+ *
  * @return 
  * If successful, a pointer to newly allocated sdp_session_t structure is
  * returned, otherwise NULL is returned.

diff --git a/libs/sofia-sip/libsofia-sip-ua/sdp/sofia-sip/sdp.h b/libs/sofia-sip/libsofia-sip-ua/sdp/sofia-sip/sdp.h
index 3f4752a4137f1d08da04d3eb1ccc47a2743347be..657571a0e1fe450dd87695eabaa55fda55f4a28e 100644 (file)
--- a/libs/sofia-sip/libsofia-sip-ua/sdp/sofia-sip/sdp.h
+++ b/libs/sofia-sip/libsofia-sip-ua/sdp/sofia-sip/sdp.h
@@ -229,7 +229,8 @@ typedef enum
   sdp_media_data,                      /**< Bulk data transfer */
   sdp_media_control,                   /**< Additional conference control */
   sdp_media_message,                   /**< Messaging sessions*/
-  sdp_media_image,                     /**< Image browsing sessions for JPIP, and T.38 */
+  sdp_media_image,                     /**< Image browsing sessions,
+                                        *   e.g., JPIP or T.38. */
   sdp_media_red                                /**< Redundancy. @NEW_1_12_4. */
 } sdp_media_e;
 
@@ -334,31 +335,31 @@ sdp_origin_t    *sdp_origin_dup(su_home_t *, sdp_origin_t const *);
 
 /** Duplicate an SDP connection structure. */
 SOFIAPUBFUN
-sdp_connection_t *sdp_connection_dup(su_home_t *home, sdp_connection_t const *);
+sdp_connection_t *sdp_connection_dup(su_home_t *, sdp_connection_t const *);
 
 /** Duplicate an SDP bandwidth structure. */
 SOFIAPUBFUN
-sdp_bandwidth_t  *sdp_bandwidth_dup(su_home_t *home, sdp_bandwidth_t const *);
+sdp_bandwidth_t  *sdp_bandwidth_dup(su_home_t *, sdp_bandwidth_t const *);
 
 /** Duplicate an SDP time structure. */
 SOFIAPUBFUN
-sdp_time_t       *sdp_time_dup(su_home_t *home, sdp_time_t const *);
+sdp_time_t       *sdp_time_dup(su_home_t *, sdp_time_t const *);
 
 /** Duplicate an SDP repeat structure. */
 SOFIAPUBFUN
-sdp_repeat_t     *sdp_repeat_dup(su_home_t *home, sdp_repeat_t const *);
+sdp_repeat_t     *sdp_repeat_dup(su_home_t *, sdp_repeat_t const *);
 
 /** Duplicate an SDP timezone structure. */
 SOFIAPUBFUN
-sdp_zone_t       *sdp_zone_dup(su_home_t *home, sdp_zone_t const *);
+sdp_zone_t       *sdp_zone_dup(su_home_t *, sdp_zone_t const *);
 
 /** Duplicate an SDP key structure. */
 SOFIAPUBFUN
-sdp_key_t        *sdp_key_dup(su_home_t *home, sdp_key_t const *);
+sdp_key_t        *sdp_key_dup(su_home_t *, sdp_key_t const *);
 
 /** Duplicate an SDP attribute structure. */
 SOFIAPUBFUN
-sdp_attribute_t  *sdp_attribute_dup(su_home_t *home, sdp_attribute_t const *);
+sdp_attribute_t  *sdp_attribute_dup(su_home_t *, sdp_attribute_t const *);
 
 /** Duplicate an SDP media description structure. */
 SOFIAPUBFUN
@@ -372,11 +373,11 @@ sdp_media_t *sdp_media_dup_all(su_home_t *, sdp_media_t const *,
 
 /** Duplicate a list structure. */
 SOFIAPUBFUN
-sdp_list_t       *sdp_list_dup(su_home_t *home, sdp_list_t const *);
+sdp_list_t       *sdp_list_dup(su_home_t *, sdp_list_t const *);
 
 /** Duplicate an rtpmap structure. */
 SOFIAPUBFUN
-sdp_rtpmap_t     *sdp_rtpmap_dup(su_home_t *home, sdp_rtpmap_t const *);
+sdp_rtpmap_t     *sdp_rtpmap_dup(su_home_t *, sdp_rtpmap_t const *);
 
 /** Compare two session descriptions. */
 SOFIAPUBFUN int sdp_session_cmp(sdp_session_t const *a,
@@ -450,13 +451,13 @@ SOFIAPUBFUN sdp_attribute_t *sdp_attribute_by_mode(su_home_t *,
 
 /** Find a mapped attribute. */
 SOFIAPUBFUN 
-sdp_attribute_t *sdp_attribute_mapped_find(sdp_attribute_t const *a, 
-                                          char const *name, 
+sdp_attribute_t *sdp_attribute_mapped_find(sdp_attribute_t const *a,
+                                          char const *name,
                                           int pt, char **return_result);
 
 /** Append a attribute to a list of attributes. */
 SOFIAPUBFUN void sdp_attribute_append(sdp_attribute_t **list, 
-                         sdp_attribute_t const *a);
+                                     sdp_attribute_t const *a);
 
 /** Replace a attribute within a list of attributes. */
 SOFIAPUBFUN int sdp_attribute_replace(sdp_attribute_t **list, 
@@ -546,8 +547,9 @@ SOFIAPUBFUN su_home_t *sdp_parser_home(sdp_parser_t *);
 typedef struct sdp_printer_s sdp_printer_t;
 typedef sdp_printer_t *sdp_printer;
 
-SOFIAPUBFUN sdp_printer_t *sdp_print(su_home_t *, sdp_session_t const *session, 
-                                    char msgbuf[], isize_t maxmsgsize, int flags);
+SOFIAPUBFUN sdp_printer_t *sdp_print(su_home_t *, sdp_session_t const *,
+                                    char msgbuf[], isize_t maxmsgsize,
+                                    int flags);
 SOFIAPUBFUN char const *sdp_printing_error(sdp_printer_t *p);
 SOFIAPUBFUN char const *sdp_message(sdp_printer_t *p);
 SOFIAPUBFUN isize_t sdp_message_size(sdp_printer_t *p);