clean up some of the mess from the RTP additions and add doxygen comments

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

diff --git a/src/include/switch_rtp.h b/src/include/switch_rtp.h
index 51f9e69779a5ecf14e4ee544be9302068548f6ba..2be7d9116e244730a0bfd20d8d221d8c78f0f95c 100644 (file)
--- a/src/include/switch_rtp.h
+++ b/src/include/switch_rtp.h
@@ -46,18 +46,40 @@ extern "C" {
 #endif
 
 
-
-
+///\defgroup sh State Handlers
+///\ingroup core1
+///\{
 typedef void (*switch_rtp_invalid_handler)(switch_rtp *rtp_session,
                                                                                   switch_socket_t *sock,
                                                                                   void *data,
                                                                                   switch_size_t datalen,
                                                                                   switch_sockaddr_t *from_addr);
 
-
+/*! 
+  \brief Initilize the RTP System
+  \param pool the memory pool to use for long term allocations
+  \note Generally called by the core_init
+*/
 SWITCH_DECLARE(void) switch_rtp_init(switch_memory_pool *pool);
+
+/*! 
+  \brief Request a new port to be used for media
+  \return the new port to use
+*/
 SWITCH_DECLARE(switch_port_t) switch_rtp_request_port(void);
 
+/*! 
+  \brief prepare a new RTP session handle
+  \param rx_ip the local address
+  \param rx_port the local port
+  \param tx_ip the remote address
+  \param tx_port the remote port
+  \param payload the iana payload number
+  \param flags flags to control behaviour
+  \param err a pointer to resolve error messages
+  \param pool a memory pool to use for the session
+  \return the new RTP session or NULL on failure
+*/
 SWITCH_DECLARE(switch_rtp *)switch_rtp_new(char *rx_ip,
                                                   switch_port_t rx_port,
                                                   char *tx_ip,
@@ -66,21 +88,111 @@ SWITCH_DECLARE(switch_rtp *)switch_rtp_new(char *rx_ip,
                                                   switch_rtp_flag_t flags,
                                                   const char **err,
                                                   switch_memory_pool *pool);
+/*! 
+  \brief Kill the socket on an existing RTP session
+  \param rtp_session an RTP session to kill the socket of
+*/
+SWITCH_DECLARE(void) switch_rtp_kill_socket(switch_rtp *rtp_session);
 
-SWITCH_DECLARE(switch_status) switch_rtp_activate_ice(switch_rtp *rtp_session, char *login, char *rlogin);
+/*! 
+  \brief Destroy an RTP session
+  \param rtp_session an RTP session to destroy
+*/
 SWITCH_DECLARE(void) switch_rtp_destroy(switch_rtp **rtp_session);
+
+/*! 
+  \brief Acvite ICE on an RTP session
+  \return SWITCH_STATUS_SUCCESS
+*/
+SWITCH_DECLARE(switch_status) switch_rtp_activate_ice(switch_rtp *rtp_session, char *login, char *rlogin);
+
+/*! 
+  \brief Retrieve the socket from an existing RTP session
+  \param rtp_session the RTP session to retrieve the socket from
+  \return the socket from the RTP session
+*/
 SWITCH_DECLARE(switch_socket_t *)switch_rtp_get_rtp_socket(switch_rtp *rtp_session);
+
+/*! 
+  \brief Activate a given RTP session
+  \param rtp_session the RTP session to activate
+  \return 0
+*/
+SWITCH_DECLARE(uint32_t) switch_rtp_start(switch_rtp *rtp_session);
+
+/*! 
+  \brief Set a callback function to execute when an invalid RTP packet is encountered
+  \param rtp_session the RTP session
+  \param on_invalid the function to set
+  \return 
+*/
 SWITCH_DECLARE(void) switch_rtp_set_invald_handler(switch_rtp *rtp_session, switch_rtp_invalid_handler on_invalid);
+
+/*! 
+  \brief Read data from a given RTP session
+  \param rtp_session the RTP session to read from
+  \param data the data to read
+  \param datalen the length of the data
+  \param payload_type the inia payload of the packet
+  \return the number of bytes read
+*/
 SWITCH_DECLARE(int) switch_rtp_read(switch_rtp *rtp_session, void *data, uint32_t datalen, int *payload_type);
+
+/*! 
+  \brief Read data from a given RTP session without copying
+  \param rtp_session the RTP session to read from
+  \param data a pointer to point directly to the RTP read buffer
+  \return the number of bytes read
+*/
 SWITCH_DECLARE(int) switch_rtp_zerocopy_read(switch_rtp *rtp_session, void **data, int *payload_type);
+
+/*! 
+  \brief Write data to a given RTP session
+  \param rtp_session the RTP session to write to
+  \param data data to write
+  \param datalen the size of the data
+  \param ts then number of bytes to increment the timestamp by
+  \return the number of bytes written
+*/
 SWITCH_DECLARE(int) switch_rtp_write(switch_rtp *rtp_session, void *data, int datalen, uint32_t ts);
+
+/*! 
+  \brief Write data with a specified payload and sequence number to a given RTP session
+  \param rtp_session the RTP session to write to
+  \param data data to write
+  \param datalen the size of the data
+  \param payload the iana payload number
+  \param ts then number of bytes to increment the timestamp by
+  \param mseq the specific sequence number to use
+  \return the number of bytes written
+*/
 SWITCH_DECLARE(int) switch_rtp_write_payload(switch_rtp *rtp_session, void *data, int datalen, uint8_t payload, uint32_t ts, uint16_t mseq);
-SWITCH_DECLARE(uint32_t) switch_rtp_start(switch_rtp *rtp_session);
+
+/*! 
+  \brief Retrieve the SSRC from a given RTP session
+  \param rtp_session the RTP session to retrieve from
+  \return the SSRC
+*/
 SWITCH_DECLARE(uint32_t) switch_rtp_get_ssrc(switch_rtp *rtp_session);
-SWITCH_DECLARE(void) switch_rtp_killread(switch_rtp *rtp_session);
+
+/*! 
+  \brief Associate an arbitrary data pointer with and RTP session
+  \param rtp_session the RTP session to assign the pointer to
+  \param private_data the private data to assign
+*/
 SWITCH_DECLARE(void) switch_rtp_set_private(switch_rtp *rtp_session, void *private_data);
+
+/*! 
+  \brief Retrieve the private data from a given RTP session
+  \param rtp_session the RTP session to retrieve the data from
+  \return the pointer to the private data
+*/
 SWITCH_DECLARE(void *)switch_rtp_get_private(switch_rtp *rtp_session);
 
+/*!
+  \}
+*/
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/src/mod/endpoints/mod_dingaling/mod_dingaling.c b/src/mod/endpoints/mod_dingaling/mod_dingaling.c
index 3725f1aa467bda21932c8c86931bb0d2651171cc..a143c28f571dd50219047a29ac23dafc4feeedde 100644 (file)
--- a/src/mod/endpoints/mod_dingaling/mod_dingaling.c
+++ b/src/mod/endpoints/mod_dingaling/mod_dingaling.c
@@ -496,7 +496,7 @@ static switch_status channel_kill_channel(switch_core_session *session, int sig)
                                ldl_session_terminate(tech_pvt->dlsession);
                        }
                        if (tech_pvt->rtp_session) {
-                               switch_rtp_killread(tech_pvt->rtp_session);
+                               switch_rtp_kill_socket(tech_pvt->rtp_session);
                        }
                        switch_console_printf(SWITCH_CHANNEL_CONSOLE, "%s CHANNEL KILL\n", switch_channel_get_name(channel));
                }

diff --git a/src/mod/endpoints/mod_exosip/mod_exosip.c b/src/mod/endpoints/mod_exosip/mod_exosip.c
index b5c5c2819749bb0805d61adfea7dd0b8a9a29315..c36ec661c68a7a130722817ec343083736f0173f 100644 (file)
--- a/src/mod/endpoints/mod_exosip/mod_exosip.c
+++ b/src/mod/endpoints/mod_exosip/mod_exosip.c
@@ -820,7 +820,7 @@ static switch_status exosip_kill_channel(switch_core_session *session, int sig)
        switch_set_flag(tech_pvt, TFLAG_BYE);
 
        if (tech_pvt->rtp_session) {
-               switch_rtp_killread(tech_pvt->rtp_session);
+               switch_rtp_kill_socket(tech_pvt->rtp_session);
        }
 
        return SWITCH_STATUS_SUCCESS;

diff --git a/src/switch_rtp.c b/src/switch_rtp.c
index 9cf1260186e6ddae75f9898f5592609af52f25cb..2bfcb7084f4b75e4438c751f04e30869246f6c4a 100644 (file)
--- a/src/switch_rtp.c
+++ b/src/switch_rtp.c
@@ -307,7 +307,7 @@ SWITCH_DECLARE(switch_status) switch_rtp_activate_ice(switch_rtp *rtp_session, c
        return SWITCH_STATUS_SUCCESS;
 }
 
-SWITCH_DECLARE(void) switch_rtp_killread(switch_rtp *rtp_session)
+SWITCH_DECLARE(void) switch_rtp_kill_socket(switch_rtp *rtp_session)
 {
        apr_socket_shutdown(rtp_session->sock, APR_SHUTDOWN_READWRITE);
        switch_clear_flag(rtp_session, SWITCH_RTP_FLAG_IO);
@@ -316,7 +316,7 @@ SWITCH_DECLARE(void) switch_rtp_killread(switch_rtp *rtp_session)
 
 SWITCH_DECLARE(void) switch_rtp_destroy(switch_rtp **rtp_session)
 {
-       switch_rtp_killread(*rtp_session);
+       switch_rtp_kill_socket(*rtp_session);
        switch_socket_close((*rtp_session)->sock);
        *rtp_session = NULL;
        return;