Changeset 549

Show
Ignore:
Timestamp:
03/12/01 23:35:24 (13 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:
4 modified

Legend:

Unmodified
Added
Removed
  • common/trunk/doc/tmpl/rtp.sgml

    r548 r549  
    3131 
    3232<!-- ##### MACRO RTP_VERSION ##### --> 
    33 <para> 
    34  
    35 </para> 
    36  
    37  
    38  
    39 <!-- ##### MACRO RTP_PACKET_HEADER_SIZE ##### --> 
    4033<para> 
    4134 
     
    6255@rtcp_bw:  
    6356@callback:  
    64 @user_data:  
     57@userdata:  
    6558@Returns:  
    6659 
     
    7871@rtcp_bw:  
    7972@callback:  
    80 @user_data:  
     73@userdata:  
    8174@Returns:  
    8275 
     
    8477<!-- ##### TYPEDEF rtp_packet ##### --> 
    8578<para> 
    86  
    87 </para> 
     79The struct begins with pointers to the data in the packet as 
     80it came off the wire. The packet is read in such that the 
     81header maps onto the latter part of this struct, and the 
     82fields in this first part of the struct point into it. The 
     83entire packet can be freed by freeing this struct, without 
     84having to free the csrc, data and extn blocks separately. 
     85WARNING: Don't change the size of the first portion of the 
     86struct without changing RTP_PACKET_HEADER_SIZE to match. 
     87</para> 
     88 
     89 
     90<!-- ##### MACRO RTP_PACKET_HEADER_SIZE ##### --> 
     91<para> 
     92This macro MUST resolve to the offset of the first packet 
     93field in the #rtp_packet struct, including all padding. 
     94If you change rtp_packet, make sure to change this too. 
     95</para> 
     96 
    8897 
    8998 
     
    99108</para> 
    100109 
     110 
     111<!-- ##### ENUM rtcp_sdes_type ##### --> 
     112<para> 
     113 
     114</para> 
     115 
     116@RTCP_SDES_END:  
     117@RTCP_SDES_CNAME:  
     118@RTCP_SDES_NAME:  
     119@RTCP_SDES_EMAIL:  
     120@RTCP_SDES_PHONE:  
     121@RTCP_SDES_LOC:  
     122@RTCP_SDES_TOOL:  
     123@RTCP_SDES_NOTE:  
     124@RTCP_SDES_PRIV:  
    101125 
    102126<!-- ##### TYPEDEF rtcp_sdes_item ##### --> 
     
    133157@RX_RTP: An RTP data packet was received. 
    134158The ssrc field contains the RTP data packet's SSRC. 
    135 The data field points to the RTP data packet (full header?) 
    136 The callback must free the data packet when it's done with it. 
     159The data field points to a #rtp_packet containing the RTP data packet. 
     160The callback must free the rtp_packet when it's done with it. 
    137161@RX_SR: An RTCP SR packet was received. 
    138162The ssrc field contains the SR packet's SSRC. 
     
    188212 
    189213 
     214<!-- ##### FUNCTION rtp_send_bye ##### --> 
     215<para> 
     216 
     217</para> 
     218 
     219@session:  
     220 
     221 
     222<!-- ##### FUNCTION rtp_done ##### --> 
     223<para> 
     224 
     225</para> 
     226 
     227@session:  
     228 
     229 
    190230<!-- ##### ENUM rtp_option ##### --> 
    191231<para> 
     
    196236@RTP_OPT_WEAK_VALIDATION:  
    197237@RTP_OPT_FILTER_MY_PACKETS:  
    198  
    199 <!-- ##### ENUM rtcp_sdes_type ##### --> 
    200 <para> 
    201  
    202 </para> 
    203  
    204 @RTCP_SDES_END:  
    205 @RTCP_SDES_CNAME:  
    206 @RTCP_SDES_NAME:  
    207 @RTCP_SDES_EMAIL:  
    208 @RTCP_SDES_PHONE:  
    209 @RTCP_SDES_LOC:  
    210 @RTCP_SDES_TOOL:  
    211 @RTCP_SDES_NOTE:  
    212 @RTCP_SDES_PRIV:  
    213  
    214 <!-- ##### FUNCTION rtp_send_bye ##### --> 
    215 <para> 
    216  
    217 </para> 
    218  
    219 @session:  
    220  
    221  
    222 <!-- ##### FUNCTION rtp_done ##### --> 
    223 <para> 
    224  
    225 </para> 
    226  
    227 @session:  
    228  
    229238 
    230239<!-- ##### FUNCTION rtp_set_option ##### --> 
     
    288297@rtp_ts:  
    289298@appcallback:  
    290 <!-- # Unused Parameters # --> 
    291 @callback:  
    292299 
    293300 
  • common/trunk/doc/uclmmbase-sections.txt

    r547 r549  
    341341<INCLUDE>rtp.h</INCLUDE> 
    342342RTP_VERSION 
    343 RTP_PACKET_HEADER_SIZE 
    344343RTP_MAX_PACKET_LEN 
    345344rtp_init 
    346345rtp_init_if 
    347346rtp_packet 
     347RTP_PACKET_HEADER_SIZE 
    348348rtcp_sr 
    349349rtcp_rr 
     350rtcp_sdes_type 
    350351rtcp_sdes_item 
    351352rtcp_app 
     
    354355rtp_event 
    355356rtp_callback 
    356 rtp_option 
    357 rtcp_sdes_type 
    358357rtp_send_bye 
    359358rtp_done 
     359rtp_option 
    360360rtp_set_option 
    361361rtp_get_option 
  • common/trunk/src/rtp.c

    r548 r549  
    900900 * allocated to RTCP. 
    901901 * @callback: See section on #rtp_callback. 
    902  * @user_data: Opaque data passed to the callback function. 
     902 * @userdata: Opaque data associated with the session.  See 
     903 * rtp_get_userdata(). 
    903904 * 
    904905 * See rtp_init_if(); calling rtp_init() is just like calling 
     
    932933 * allocated to RTCP. 
    933934 * @callback: See section on #rtp_callback. 
    934  * @user_data: Opaque data passed to the callback function. 
     935 * @userdata: Opaque data associated with the session.  See 
     936 * rtp_get_userdata(). 
    935937 * 
    936938 * Creates and initializes an RTP session. 
     
    10651067} 
    10661068 
     1069/** 
     1070 * rtp_set_option: 
     1071 * @session: The RTP session. 
     1072 * @optname: The option name, see #rtp_option. 
     1073 * @optval: The value to set. 
     1074 * 
     1075 * Sets the value of a session option.  See #rtp_option for 
     1076 * documentation on the options and their legal values. 
     1077 * 
     1078 * Returns: TRUE on success, else FALSE. 
     1079 */ 
    10671080int rtp_set_option(struct rtp *session, rtp_option optname, int optval) 
    10681081{ 
     
    10861099} 
    10871100 
     1101/** 
     1102 * rtp_get_option: 
     1103 * @session: The RTP session. 
     1104 * @optname: The option name, see #rtp_option. 
     1105 * @optval: The return value. 
     1106 * 
     1107 * Retrieves the value of a session option.  See #rtp_option for 
     1108 * documentation on the options and their legal values. 
     1109 * 
     1110 * Returns: TRUE and the value of the option in optval on success, else FALSE. 
     1111 */ 
    10881112int rtp_get_option(struct rtp *session, rtp_option optname, int *optval) 
    10891113{ 
     
    11061130} 
    11071131 
     1132/** 
     1133 * rtp_get_userdata: 
     1134 * @session: The RTP session. 
     1135 * 
     1136 * This function returns the userdata pointer that was passed to the 
     1137 * rtp_init() or rtp_init_if() function when creating this session. 
     1138 * XXX (Note that gtkdoc thinks that it returns void, not void*, so 
     1139 * ignores the "Returns:" block here) 
     1140 * Returns: The userdata pointer that was passed to the rtp_init() or 
     1141 * rtp_init_if() function when creating this session. 
     1142 */ 
    11081143void *rtp_get_userdata(struct rtp *session) 
    11091144{ 
     
    25122547 * @session: the RTP session to finish 
    25132548 * 
    2514  * Frees state associated with given RTP session 
     2549 * Frees state associated with given RTP session.  Does not send 
     2550 * any packets (e.g. BYE). 
    25152551 */ 
    25162552void rtp_done(struct rtp *session) 
     
    25462582} 
    25472583 
     2584/** 
     2585 * rtp_set_encryption_key: 
     2586 * @session: The RTP session. 
     2587 * @passphrase: The user-provided "pass phrase" to map to an encryption key. 
     2588 * 
     2589 * Converts the user supplied key into a form suitable for use with RTP 
     2590 * and install it as the active key. Passing in NULL as the passphrase 
     2591 * disables encryption. The passphrase is converted into a DES key as 
     2592 * specified in RFC1890, that is: 
     2593 *  
     2594 *   - convert to canonical form 
     2595 *  
     2596 *   - derive an MD5 hash of the canonical form 
     2597 *  
     2598 *   - take the first 56 bits of the MD5 hash 
     2599 *  
     2600 *   - add parity bits to form a 64 bit key 
     2601 *  
     2602 * Note that versions of rat prior to 4.1.2 do not convert the passphrase 
     2603 * to canonical form before taking the MD5 hash, and so will 
     2604 * not be compatible for keys which are non-invarient under this step. 
     2605 * 
     2606 * Returns: TRUE on success, FALSE on failure. 
     2607 */ 
    25482608int rtp_set_encryption_key(struct rtp* session, const char *passphrase) 
    25492609{ 
    2550         /* Convert the user supplied key into a form suitable for use with RTP */ 
    2551         /* and install it as the active key. Passing in NULL as the passphrase */ 
    2552         /* disables encryption. The passphrase is converted into a DES key as  */ 
    2553         /* specified in RFC1890, that is:                                      */ 
    2554         /*   - convert to canonical form                                       */ 
    2555         /*   - derive an MD5 hash of the canonical form                        */ 
    2556         /*   - take the first 56 bits of the MD5 hash                          */ 
    2557         /*   - add parity bits to form a 64 bit key                            */ 
    2558         /* Note that versions of rat prior to 4.1.2 do not convert the pass-   */ 
    2559         /* phrase to canonical form before taking the MD5 hash, and so will    */ 
    2560         /* not be compatible for keys which are non-invarient under this step. */ 
    25612610        char    *canonical_passphrase; 
    25622611        u_char   hash[16]; 
     
    26222671} 
    26232672 
     2673/** 
     2674 * rtp_get_addr: 
     2675 * @session: The RTP Session. 
     2676 * 
     2677 * Returns: The session's destination address, as set when creating the 
     2678 * session with rtp_init() or rtp_init_if(). 
     2679 */ 
    26242680char *rtp_get_addr(struct rtp *session) 
    26252681{ 
     
    26282684} 
    26292685 
     2686/** 
     2687 * rtp_get_rx_port: 
     2688 * @session: The RTP Session. 
     2689 * 
     2690 * Returns: The UDP port to which this session is bound, as set when 
     2691 * creating the session with rtp_init() or rtp_init_if(). 
     2692 */ 
    26302693uint16_t rtp_get_rx_port(struct rtp *session) 
    26312694{ 
     
    26342697} 
    26352698 
     2699/** 
     2700 * rtp_get_tx_port: 
     2701 * @session: The RTP Session. 
     2702 * 
     2703 * Returns: The UDP port to which RTP packets are transmitted, as set 
     2704 * when creating the session with rtp_init() or rtp_init_if(). 
     2705 */ 
    26362706uint16_t rtp_get_tx_port(struct rtp *session) 
    26372707{ 
     
    26402710} 
    26412711 
     2712/** 
     2713 * rtp_get_ttl: 
     2714 * @session: The RTP Session. 
     2715 * 
     2716 * Returns: The session's TTL, as set when creating the session with 
     2717 * rtp_init() or rtp_init_if(). 
     2718 */ 
    26422719int rtp_get_ttl(struct rtp *session) 
    26432720{ 
  • common/trunk/src/rtp.h

    r547 r549  
    190190                          int ttl, double rtcp_bw,  
    191191                          rtp_callback callback, 
    192                           void *user_data); 
     192                          void *userdata); 
    193193rtp_t           rtp_init_if(const char *addr, char *iface,  
    194194                             uint16_t rx_port, uint16_t tx_port,  
    195195                             int ttl, double rtcp_bw,  
    196196                             rtp_callback callback, 
    197                              void *user_data); 
     197                             void *userdata); 
    198198 
    199199void             rtp_send_bye(struct rtp *session);