Changeset 549

Timestamp:

03/12/01 23:35:24 (12 years ago)

Author:

bfenner

Message:

A few more doc fixups, reordering the generated page and

adding documentation for a few simple functions.

Location:

common/trunk

Files:

• doc/tmpl/rtp.sgml (modified) (9 diffs)
• doc/uclmmbase-sections.txt (modified) (2 diffs)
• src/rtp.c (modified) (11 diffs)
• src/rtp.h (modified) (1 diff)

common/trunk/doc/tmpl/rtp.sgml

@@ -31 +31 @@
 
 <!-- ##### MACRO RTP_VERSION ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO RTP_PACKET_HEADER_SIZE ##### -->
 <para>
 
@@ -62 +55 @@
 @rtcp_bw: 
 @callback: 
-@user_data: 
+@userdata: 
 @Returns: 
 
@@ -78 +71 @@
 @rtcp_bw: 
 @callback: 
-@user_data: 
+@userdata: 
 @Returns: 
 
@@ -84 +77 @@
 <!-- ##### TYPEDEF rtp_packet ##### -->
 <para>
-
-</para>
+The struct begins with pointers to the data in the packet as
+it came off the wire. The packet is read in such that the
+header maps onto the latter part of this struct, and the
+fields in this first part of the struct point into it. The
+entire packet can be freed by freeing this struct, without
+having to free the csrc, data and extn blocks separately.
+WARNING: Don't change the size of the first portion of the
+struct without changing RTP_PACKET_HEADER_SIZE to match.
+</para>
+
+
+<!-- ##### MACRO RTP_PACKET_HEADER_SIZE ##### -->
+<para>
+This macro MUST resolve to the offset of the first packet
+field in the #rtp_packet struct, including all padding.
+If you change rtp_packet, make sure to change this too.
+</para>
+
 
 
@@ -99 +108 @@
 </para>
 
+
+<!-- ##### ENUM rtcp_sdes_type ##### -->
+<para>
+
+</para>
+
+@RTCP_SDES_END: 
+@RTCP_SDES_CNAME: 
+@RTCP_SDES_NAME: 
+@RTCP_SDES_EMAIL: 
+@RTCP_SDES_PHONE: 
+@RTCP_SDES_LOC: 
+@RTCP_SDES_TOOL: 
+@RTCP_SDES_NOTE: 
+@RTCP_SDES_PRIV: 
 
 <!-- ##### TYPEDEF rtcp_sdes_item ##### -->
@@ -133 +157 @@
 @RX_RTP: An RTP data packet was received.
 The ssrc field contains the RTP data packet's SSRC.
-The data field points to the RTP data packet (full header?)
-The callback must free the data packet when it's done with it.
+The data field points to a #rtp_packet containing the RTP data packet.
+The callback must free the rtp_packet when it's done with it.
 @RX_SR: An RTCP SR packet was received.
 The ssrc field contains the SR packet's SSRC.
@@ -188 +212 @@
 
 
+<!-- ##### FUNCTION rtp_send_bye ##### -->
+<para>
+
+</para>
+
+@session: 
+
+
+<!-- ##### FUNCTION rtp_done ##### -->
+<para>
+
+</para>
+
+@session: 
+
+
 <!-- ##### ENUM rtp_option ##### -->
 <para>
@@ -196 +236 @@
 @RTP_OPT_WEAK_VALIDATION: 
 @RTP_OPT_FILTER_MY_PACKETS: 
-
-<!-- ##### ENUM rtcp_sdes_type ##### -->
-<para>
-
-</para>
-
-@RTCP_SDES_END: 
-@RTCP_SDES_CNAME: 
-@RTCP_SDES_NAME: 
-@RTCP_SDES_EMAIL: 
-@RTCP_SDES_PHONE: 
-@RTCP_SDES_LOC: 
-@RTCP_SDES_TOOL: 
-@RTCP_SDES_NOTE: 
-@RTCP_SDES_PRIV: 
-
-<!-- ##### FUNCTION rtp_send_bye ##### -->
-<para>
-
-</para>
-
-@session: 
-
-
-<!-- ##### FUNCTION rtp_done ##### -->
-<para>
-
-</para>
-
-@session: 
-
 
 <!-- ##### FUNCTION rtp_set_option ##### -->
@@ -288 +297 @@
 @rtp_ts: 
 @appcallback: 
-<!-- # Unused Parameters # -->
-@callback: 
 
 

common/trunk/doc/uclmmbase-sections.txt

@@ -341 +341 @@
 <INCLUDE>rtp.h</INCLUDE>
 RTP_VERSION
-RTP_PACKET_HEADER_SIZE
 RTP_MAX_PACKET_LEN
 rtp_init
 rtp_init_if
 rtp_packet
+RTP_PACKET_HEADER_SIZE
 rtcp_sr
 rtcp_rr
+rtcp_sdes_type
 rtcp_sdes_item
 rtcp_app
@@ -354 +355 @@
 rtp_event
 rtp_callback
-rtp_option
-rtcp_sdes_type
 rtp_send_bye
 rtp_done
+rtp_option
 rtp_set_option
 rtp_get_option

common/trunk/src/rtp.c

@@ -900 +900 @@
  * allocated to RTCP.
  * @callback: See section on #rtp_callback.
- * @user_data: Opaque data passed to the callback function.
+ * @userdata: Opaque data associated with the session.  See
+ * rtp_get_userdata().
  *
  * See rtp_init_if(); calling rtp_init() is just like calling
@@ -932 +933 @@
  * allocated to RTCP.
  * @callback: See section on #rtp_callback.
- * @user_data: Opaque data passed to the callback function.
+ * @userdata: Opaque data associated with the session.  See
+ * rtp_get_userdata().
  *
  * Creates and initializes an RTP session.
@@ -1065 +1067 @@
 }
 
+/**
+ * rtp_set_option:
+ * @session: The RTP session.
+ * @optname: The option name, see #rtp_option.
+ * @optval: The value to set.
+ *
+ * Sets the value of a session option.  See #rtp_option for
+ * documentation on the options and their legal values.
+ *
+ * Returns: TRUE on success, else FALSE.
+ */
 int rtp_set_option(struct rtp *session, rtp_option optname, int optval)
 {
@@ -1086 +1099 @@
 }
 
+/**
+ * rtp_get_option:
+ * @session: The RTP session.
+ * @optname: The option name, see #rtp_option.
+ * @optval: The return value.
+ *
+ * Retrieves the value of a session option.  See #rtp_option for
+ * documentation on the options and their legal values.
+ *
+ * Returns: TRUE and the value of the option in optval on success, else FALSE.
+ */
 int rtp_get_option(struct rtp *session, rtp_option optname, int *optval)
 {
@@ -1106 +1130 @@
 }
 
+/**
+ * rtp_get_userdata:
+ * @session: The RTP session.
+ *
+ * This function returns the userdata pointer that was passed to the
+ * rtp_init() or rtp_init_if() function when creating this session.
+ * XXX (Note that gtkdoc thinks that it returns void, not void*, so
+ * ignores the "Returns:" block here)
+ * Returns: The userdata pointer that was passed to the rtp_init() or
+ * rtp_init_if() function when creating this session.
+ */
 void *rtp_get_userdata(struct rtp *session)
 {
@@ -2512 +2547 @@
  * @session: the RTP session to finish
  *
- * Frees state associated with given RTP session
+ * Frees state associated with given RTP session.  Does not send
+ * any packets (e.g. BYE).
  */
 void rtp_done(struct rtp *session)
@@ -2546 +2582 @@
 }
 
+/**
+ * rtp_set_encryption_key:
+ * @session: The RTP session.
+ * @passphrase: The user-provided "pass phrase" to map to an encryption key.
+ *
+ * Converts the user supplied key into a form suitable for use with RTP
+ * and install it as the active key. Passing in NULL as the passphrase
+ * disables encryption. The passphrase is converted into a DES key as
+ * specified in RFC1890, that is:
+ * 
+ *   - convert to canonical form
+ * 
+ *   - derive an MD5 hash of the canonical form
+ * 
+ *   - take the first 56 bits of the MD5 hash
+ * 
+ *   - add parity bits to form a 64 bit key
+ * 
+ * Note that versions of rat prior to 4.1.2 do not convert the passphrase
+ * to canonical form before taking the MD5 hash, and so will
+ * not be compatible for keys which are non-invarient under this step.
+ *
+ * Returns: TRUE on success, FALSE on failure.
+ */
 int rtp_set_encryption_key(struct rtp* session, const char *passphrase)
 {
-        /* Convert the user supplied key into a form suitable for use with RTP */
-        /* and install it as the active key. Passing in NULL as the passphrase */
-        /* disables encryption. The passphrase is converted into a DES key as  */
-        /* specified in RFC1890, that is:                                      */
-        /*   - convert to canonical form                                       */
-        /*   - derive an MD5 hash of the canonical form                        */
-        /*   - take the first 56 bits of the MD5 hash                          */
-        /*   - add parity bits to form a 64 bit key                            */
-        /* Note that versions of rat prior to 4.1.2 do not convert the pass-   */
-        /* phrase to canonical form before taking the MD5 hash, and so will    */
-        /* not be compatible for keys which are non-invarient under this step. */
         char    *canonical_passphrase;
         u_char   hash[16];
@@ -2622 +2671 @@
 }
 
+/**
+ * rtp_get_addr:
+ * @session: The RTP Session.
+ *
+ * Returns: The session's destination address, as set when creating the
+ * session with rtp_init() or rtp_init_if().
+ */
 char *rtp_get_addr(struct rtp *session)
 {
@@ -2628 +2684 @@
 }
 
+/**
+ * rtp_get_rx_port:
+ * @session: The RTP Session.
+ *
+ * Returns: The UDP port to which this session is bound, as set when
+ * creating the session with rtp_init() or rtp_init_if().
+ */
 uint16_t rtp_get_rx_port(struct rtp *session)
 {
@@ -2634 +2697 @@
 }
 
+/**
+ * rtp_get_tx_port:
+ * @session: The RTP Session.
+ *
+ * Returns: The UDP port to which RTP packets are transmitted, as set
+ * when creating the session with rtp_init() or rtp_init_if().
+ */
 uint16_t rtp_get_tx_port(struct rtp *session)
 {
@@ -2640 +2710 @@
 }
 
+/**
+ * rtp_get_ttl:
+ * @session: The RTP Session.
+ *
+ * Returns: The session's TTL, as set when creating the session with
+ * rtp_init() or rtp_init_if().
+ */
 int rtp_get_ttl(struct rtp *session)
 {

common/trunk/src/rtp.h

@@ -190 +190 @@
                           int ttl, double rtcp_bw, 
                           rtp_callback callback,
-                          void *user_data);
+                          void *userdata);
 rtp_t           rtp_init_if(const char *addr, char *iface, 
                              uint16_t rx_port, uint16_t tx_port, 
                              int ttl, double rtcp_bw, 
                              rtp_callback callback,
-                             void *user_data);
+                             void *userdata);
 
 void             rtp_send_bye(struct rtp *session);