[Freeswitch-svn] [commit] r8657 - freeswitch/trunk/src/include

Freeswitch SVN stkn at freeswitch.org
Mon May 26 05:55:21 EDT 2008


Author: stkn
Date: Mon May 26 05:55:20 2008
New Revision: 8657

Modified:
   freeswitch/trunk/src/include/switch_channel.h
   freeswitch/trunk/src/include/switch_core.h
   freeswitch/trunk/src/include/switch_cpp.h
   freeswitch/trunk/src/include/switch_ivr.h
   freeswitch/trunk/src/include/switch_log.h
   freeswitch/trunk/src/include/switch_rtp.h
   freeswitch/trunk/src/include/switch_stun.h
   freeswitch/trunk/src/include/switch_xml.h

Log:
More doxygen updates, stuff that needs work is marked with NEEDDESC

Modified: freeswitch/trunk/src/include/switch_channel.h
==============================================================================
--- freeswitch/trunk/src/include/switch_channel.h	(original)
+++ freeswitch/trunk/src/include/switch_channel.h	Mon May 26 05:55:20 2008
@@ -227,8 +227,6 @@
 /*!
  * Start iterating over the entries in the channel variable list.
  * @param channel the channel to intterate the variales for
- * @param pool The pool to allocate the switch_hash_index_t iterator. If this
- *          pool is NULL, then an internal, non-thread-safe iterator is used.
  * @remark  Use switch_hash_next and switch_hash_this with this function to iterate all the channel variables
  */
 SWITCH_DECLARE(switch_event_header_t *) switch_channel_variable_first(switch_channel_t *channel);

Modified: freeswitch/trunk/src/include/switch_core.h
==============================================================================
--- freeswitch/trunk/src/include/switch_core.h	(original)
+++ freeswitch/trunk/src/include/switch_core.h	Mon May 26 05:55:20 2008
@@ -124,6 +124,7 @@
   \param session the session to add the bug to
   \param callback a callback for events
   \param user_data arbitrary user data
+  \param stop_time absolute time at which the bug is automatically removed
   \param flags flags to choose the stream
   \param new_bug pointer to assign new bug to
   \return SWITCH_STATUS_SUCCESS if the operation was a success
@@ -214,22 +215,29 @@
   \brief Initilize the port allocator
   \param start the starting port
   \param end the ending port
-  \param inc the amount to increment each port
+  \param flags flags to change allocator behaviour (e.g. only even/odd portnumbers)
   \param new_allocator new pointer for the return value
   \return SWITCH_STATUS_SUCCESS if the operation was a success
 */
 SWITCH_DECLARE(switch_status_t) switch_core_port_allocator_new(_In_ switch_port_t start,
-															   _In_ switch_port_t end,
-															   _In_ switch_port_flag_t flags,
-															   _Out_ switch_core_port_allocator_t **new_allocator);
+								   _In_ switch_port_t end,
+								   _In_ switch_port_flag_t flags,
+								   _Out_ switch_core_port_allocator_t **new_allocator);
 
 /*!
   \brief Get a port from the port allocator
   \param alloc the allocator object
-  \param port a pointer to the port
+  \param port_ptr a pointer to the port
   \return SUCCESS
 */
 SWITCH_DECLARE(switch_status_t) switch_core_port_allocator_request_port(_In_ switch_core_port_allocator_t *alloc, _Out_ switch_port_t *port_ptr);
+
+/*!
+  \brief Return unused port to the port allocator
+  \param alloc the allocator object
+  \param port the port
+  \return SUCCESS
+*/
 SWITCH_DECLARE(switch_status_t) switch_core_port_allocator_free_port(_In_ switch_core_port_allocator_t *alloc, _In_ switch_port_t port);
 
 /*!
@@ -724,6 +732,7 @@
 /*! 
   \brief Request an outgoing session spawned from an existing session using a desired endpoing module
   \param session the originating session
+  \param var_event - NEEDDESC -
   \param endpoint_name the name of the module to use for the new session
   \param caller_profile the originator's caller profile
   \param new_session a NULL pointer to aim at the newly created session
@@ -800,24 +809,49 @@
 */
 SWITCH_DECLARE(switch_status_t) switch_core_session_dequeue_private_event(_In_ switch_core_session_t *session, _Out_ switch_event_t **event);
 
+
+/*!
+  \brief Flush the private event queue of a session
+  \param session the session to flush
+  \return SWITCH_STATUS_SUCCESS if the events have been flushed
+*/
 SWITCH_DECLARE(uint32_t) switch_core_session_flush_private_events(switch_core_session_t *session);
 
+
 /*! 
   \brief Read a frame from a session
   \param session the session to read from
   \param frame a NULL pointer to a frame to aim at the newly read frame
-  \param timeout number of milliseconds to wait for data
+  \param flags - NEEDDESC -
   \param stream_id which logical media channel to use
   \return SWITCH_STATUS_SUCCESS a the frame was read
 */
 SWITCH_DECLARE(switch_status_t) switch_core_session_read_frame(_In_ switch_core_session_t *session, switch_frame_t **frame, switch_io_flag_t flags, int stream_id);
 
+/*! 
+  \brief Read a video frame from a session
+  \param session the session to read from
+  \param frame a NULL pointer to a frame to aim at the newly read frame
+  \param flags - NEEDDESC -
+  \param stream_id which logical media channel to use
+  \return SWITCH_STATUS_SUCCESS a if the frame was read
+*/
 SWITCH_DECLARE(switch_status_t) switch_core_session_read_video_frame(_In_ switch_core_session_t *session, switch_frame_t **frame, switch_io_flag_t flags, int stream_id);
+
+/*! 
+  \brief Write a video frame to a session
+  \param session the session to write to
+  \param frame a pointer to a frame to write
+  \param flags - NEEDDESC -
+  \param stream_id which logical media channel to use
+  \return SWITCH_STATUS_SUCCESS a if the frame was written
+*/
 SWITCH_DECLARE(switch_status_t) switch_core_session_write_video_frame(_In_ switch_core_session_t *session, switch_frame_t *frame, switch_io_flag_t flags, int stream_id);
 
 /*! 
   \brief Reset the buffers and resampler on a session
   \param session the session to reset
+  \param flush_dtmf flush all queued dtmf events too
 */
 SWITCH_DECLARE(void) switch_core_session_reset(_In_ switch_core_session_t *session, switch_bool_t flush_dtmf);
 
@@ -825,7 +859,7 @@
   \brief Write a frame to a session
   \param session the session to write to
   \param frame the frame to write
-  \param timeout number of milliseconds to wait for data
+  \param flags - NEEDDESC -
   \param stream_id which logical media channel to use
   \return SWITCH_STATUS_SUCCESS a the frame was written
 */
@@ -834,7 +868,7 @@
 
 SWITCH_DECLARE(switch_status_t) switch_core_session_perform_kill_channel(_In_ switch_core_session_t *session,
 																		 const char *file, const char *func, int line, switch_signal_t sig);
-/*! 
+/*!
   \brief Send a signal to a channel
   \param session session to send signal to
   \param sig signal to send

Modified: freeswitch/trunk/src/include/switch_cpp.h
==============================================================================
--- freeswitch/trunk/src/include/switch_cpp.h	(original)
+++ freeswitch/trunk/src/include/switch_cpp.h	Mon May 26 05:55:20 2008
@@ -197,9 +197,9 @@
 	SWITCH_DECLARE(void) sayPhrase(const char *phrase_name, const char *phrase_data = "", const char *phrase_lang = NULL);
 
 	/** \brief Record to a file
-	 * \param filename 
+	 * \param file_name 
 	 * \param <[max_len]> maximum length of the recording in seconds
-     * \param <[silence_threshold]> energy level audio must fall below 
+	 * \param <[silence_threshold]> energy level audio must fall below 
 	 *        to be considered silence (500 is a good starting point).
 	 * \param <[silence_secs]> seconds of silence to interrupt the record.
 	 */
@@ -214,12 +214,13 @@
 
 	/** \brief Originate a call to a destination
 	 *
-	 * \param a_leg_sessoin - the session where the call is originating from 
-     *                        and also the session in which _this_ session was 
-     *                        created
+	 * \param a_leg_session - the session where the call is originating from 
+	 *                        and also the session in which _this_ session was 
+	 *                        created
 	 * \param dest - a string representing destination, eg, sofia/mydomain.com/foo at bar.com
+	 * \param timeout - time to wait for call to be answered
 	 * \return an int status code indicating success or failure
-     *
+	 *
 	 */
 	SWITCH_DECLARE(int) originate(CoreSession *a_leg_session, 
 				  char *dest, 
@@ -227,12 +228,12 @@
 
 
 	/** \brief set a DTMF callback function
-     * 
-     * The DTMF callback function will be set and persist
-     * for the life of the session, and be called when a dtmf
-     * is pressed by user during streamfile(), collectDigits(), and 
-     * certain other methods are executing.
-     *
+	 * 
+	 * The DTMF callback function will be set and persist
+	 * for the life of the session, and be called when a dtmf
+	 * is pressed by user during streamfile(), collectDigits(), and 
+	 * certain other methods are executing.
+	 *
 	 */
 	SWITCH_DECLARE(void) setDTMFCallback(void *cbfunc, char *funcargs);
 
@@ -240,14 +241,14 @@
 	SWITCH_DECLARE(void) set_tts_parms(char *tts_name, char *voice_name);
 
 	/**
-     * For timeout milliseconds, call the dtmf function set previously
+	 * For timeout milliseconds, call the dtmf function set previously
 	 * by setDTMFCallback whenever a dtmf or event is received
 	 */
 	SWITCH_DECLARE(int) collectDigits(int timeout);
 
 	/** 
-     * Collect up to maxdigits digits worth of digits
-     * and store them in dtmf_buf.  In the case of mod_python, the 
+	 * Collect up to maxdigits digits worth of digits
+	 * and store them in dtmf_buf.  In the case of mod_python, the 
 	 * dtmf_buf parameter is configured to act as a _return_ value,
 	 * (see mod_python.i).  This does NOT call any callbacks upon
 	 * receiving dtmf digits.  For that, use collectDigits.
@@ -268,12 +269,12 @@
 	
 	/** \brief Play a file into channel and collect dtmfs
 	 * 
-     * See API docs in switch_ivr.h: switch_play_and_get_digits(..)
-     *
-     * NOTE: this does not call any dtmf callbacks set by 
-     *       setDTMFCallback(..) as it uses its own internal callback
-     *       handler.
-     */
+	 * See API docs in switch_ivr.h: switch_play_and_get_digits(..)
+	 *
+	 * NOTE: this does not call any dtmf callbacks set by 
+	 *       setDTMFCallback(..) as it uses its own internal callback
+	 *       handler.
+	 */
 	SWITCH_DECLARE(char *) playAndGetDigits(int min_digits, 
 						 int max_digits, 
 						 int max_tries, 
@@ -287,7 +288,7 @@
 	 *
 	 * \param file - the path to the .wav/.mp3 to be played
 	 * \param starting_sample_count - the index of the sample to 
-     *                                start playing from
+	 *                                start playing from
 	 * \return an int status code indicating success or failure
 	 *
 	 */

Modified: freeswitch/trunk/src/include/switch_ivr.h
==============================================================================
--- freeswitch/trunk/src/include/switch_ivr.h	(original)
+++ freeswitch/trunk/src/include/switch_ivr.h	Mon May 26 05:55:20 2008
@@ -207,15 +207,41 @@
   \brief Record a session to disk
   \param session the session to record
   \param file the path to the file
+  \param limit stop recording after this amount of time (in ms, 0 = never stop)
   \param fh file handle to use (NULL for builtin one)
   \return SWITCH_STATUS_SUCCESS if all is well
 */
 SWITCH_DECLARE(switch_status_t) switch_ivr_record_session(switch_core_session_t *session, char *file, uint32_t limit, switch_file_handle_t *fh);
+
+/*!
+  \brief Eavesdrop on a another session
+  \param session our session
+  \param uuid the uuid of the session to spy on
+  \param require_group - NEEDDESC -
+  \param flags - NEEDDESC -
+  \return SWITCH_STATUS_SUCESS if all is well
+*/
 SWITCH_DECLARE(switch_status_t) switch_ivr_eavesdrop_session(switch_core_session_t *session, 
 															 const char *uuid, 
 															 const char *require_group, 
 															 switch_eavesdrop_flag_t flags);
+
+/*!
+  \brief - NEEDDESC -
+  \param session the session to displace
+  \param file
+  \param limit
+  \param flags
+  \return SWITCH_STATUS_SUCCESS if all is well
+*/
 SWITCH_DECLARE(switch_status_t) switch_ivr_displace_session(switch_core_session_t *session, const char *file, uint32_t limit, const char *flags);
+
+/*!
+  \brief Stop displacing a session
+  \param session the session
+  \param file - NEEDDESC -
+  \return SWITCH_STATUS_SUCCESS if all is well
+*/
 SWITCH_DECLARE(switch_status_t) switch_ivr_stop_displace_session(switch_core_session_t *session, const char *file);
 
 /*!
@@ -244,6 +270,7 @@
 /*!
   \brief Start generating DTMF inband
   \param session the session to generate on
+  \param read_stream - NEEDDESC -
   \return SWITCH_STATUS_SUCCESS if all is well
 */
 SWITCH_DECLARE(switch_status_t) switch_ivr_inband_dtmf_generate_session(switch_core_session_t *session, switch_bool_t read_stream);
@@ -256,7 +283,7 @@
 SWITCH_DECLARE(switch_status_t) switch_ivr_stop_inband_dtmf_generate_session(switch_core_session_t *session);
 
 /*!
-  \brief XXX DESCRIBE ME
+  \brief - NEEDDESC -
   \param session the session to act on
   \return SWITCH_STATUS_SUCCESS if all is well - maybe more XXX FIXME
 */
@@ -464,6 +491,7 @@
   \brief Signal the session with a protocol specific hold message.
   \param uuid the uuid of the session to hold
   \param message optional message
+  \param moh play music-on-hold
   \return SWITCH_STATUS_SUCCESS if all is well
 */
 SWITCH_DECLARE(switch_status_t) switch_ivr_hold_uuid(const char *uuid, const char *message, switch_bool_t moh);
@@ -479,6 +507,7 @@
   \brief Signal the session with a protocol specific hold message.
   \param session the session to hold
   \param message optional message
+  \param moh play music-on-hold
   \return SWITCH_STATUS_SUCCESS if all is well
 */
 SWITCH_DECLARE(switch_status_t) switch_ivr_hold(switch_core_session_t *session, const char *message, switch_bool_t moh);
@@ -638,8 +667,13 @@
  *\param name A pointer to the name of this menu.
  *\param greeting_sound Optional pointer to a main sound (press 1 for this 2 for that).
  *\param short_greeting_sound Optional pointer to a shorter main sound for subsequent loops.
- *\param exit_sound Optional pointer to a sound to play upon exiting the menu.
  *\param invalid_sound Optional pointer to a sound to play after invalid input.
+ *\param exit_sound Optional pointer to a sound to play upon exiting the menu.
+ *\param confirm_macro - NEEDDESC -
+ *\param confirm_key   - NEEDDESC -
+ *\param confirm_attempts - NEEDDESC -
+ *\param inter_timeout - NEEDDESC -
+ *\param digit_len     - NEEDDESC -
  *\param timeout A number of milliseconds to pause before looping.
  *\param max_failures Maximum number of failures to withstand before hangingup This resets everytime you enter the menu.
  *\param pool memory pool (NULL to create one).

Modified: freeswitch/trunk/src/include/switch_log.h
==============================================================================
--- freeswitch/trunk/src/include/switch_log.h	(original)
+++ freeswitch/trunk/src/include/switch_log.h	Mon May 26 05:55:20 2008
@@ -89,6 +89,7 @@
   \param file the current file
   \param func the current function
   \param line the current line
+  \param userdata ununsed
   \param level the current log level
   \param fmt desired format
   \param ... variable args

Modified: freeswitch/trunk/src/include/switch_rtp.h
==============================================================================
--- freeswitch/trunk/src/include/switch_rtp.h	(original)
+++ freeswitch/trunk/src/include/switch_rtp.h	Mon May 26 05:55:20 2008
@@ -293,6 +293,7 @@
   \param datalen a pointer to the datalen
   \param payload_type the IANA payload of the packet
   \param flags flags
+  \param io_flags i/o flags
   \return the number of bytes read
 */
 SWITCH_DECLARE(switch_status_t) switch_rtp_read(switch_rtp_t *rtp_session, void *data, uint32_t * datalen,
@@ -301,10 +302,17 @@
 /*! 
   \brief Queue RFC2833 DTMF data into an RTP Session
   \param rtp_session the rtp session to use
-  \param digits the digit string to queue
-  \param duration the duration of the dtmf
+  \param dtmf the dtmf digits to queue
+  \return SWITCH_STATUS_SUCCESS on success
 */
 SWITCH_DECLARE(switch_status_t) switch_rtp_queue_rfc2833(switch_rtp_t *rtp_session, const switch_dtmf_t *dtmf);
+
+/*! 
+  \brief Queue RFC2833 DTMF data into an RTP Session - NEEDDESC -
+  \param rtp_session the rtp session to use
+  \param dtmf the dtmf digits to queue
+  \return SWITCH_STATUS_SUCCESS on success
+*/
 SWITCH_DECLARE(switch_status_t) switch_rtp_queue_rfc2833_in(switch_rtp_t *rtp_session, const switch_dtmf_t *dtmf);
 
 /*!
@@ -329,6 +337,7 @@
   \param datalen a pointer to the datalen
   \param payload_type the IANA payload of the packet
   \param flags flags
+  \param io_flags i/o flags
   \return the number of bytes read
 */
 SWITCH_DECLARE(switch_status_t) switch_rtp_zerocopy_read(switch_rtp_t *rtp_session,
@@ -338,9 +347,10 @@
   \brief Read data from a given RTP session without copying
   \param rtp_session the RTP session to read from
   \param frame a frame to populate with information
+  \param io_flags i/o flags
   \return the number of bytes read
 */
-SWITCH_DECLARE(switch_status_t) switch_rtp_zerocopy_read_frame(switch_rtp_t *rtp_session, switch_frame_t *frame, switch_io_flag_t io_flagsm);
+SWITCH_DECLARE(switch_status_t) switch_rtp_zerocopy_read_frame(switch_rtp_t *rtp_session, switch_frame_t *frame, switch_io_flag_t io_flags);
 
 /*!
   \brief Enable VAD on an RTP Session
@@ -376,7 +386,6 @@
   \param m set mark bit or not
   \param payload the IANA payload number
   \param ts then number of bytes to increment the timestamp by
-  \param ssrc the ssrc
   \param flags frame flags
   \return the number of bytes written
 */

Modified: freeswitch/trunk/src/include/switch_stun.h
==============================================================================
--- freeswitch/trunk/src/include/switch_stun.h	(original)
+++ freeswitch/trunk/src/include/switch_stun.h	Mon May 26 05:55:20 2008
@@ -226,6 +226,7 @@
 /*!
   \brief Increment an attribute pointer to the next attribute in it's packet
   \param attribute the pointer to increment
+  \param end pointer to the end of the buffer
   \return true or false depending on if there are any more attributes
 */
 #define switch_stun_packet_next_attribute(attribute, end) (attribute && (attribute = (switch_stun_packet_attribute_t *) (attribute->value +  switch_stun_attribute_padded_length(attribute))) && ((void *)attribute < end) && attribute->length && ((void *)(attribute +  switch_stun_attribute_padded_length(attribute)) < end))

Modified: freeswitch/trunk/src/include/switch_xml.h
==============================================================================
--- freeswitch/trunk/src/include/switch_xml.h	(original)
+++ freeswitch/trunk/src/include/switch_xml.h	Mon May 26 05:55:20 2008
@@ -189,8 +189,17 @@
 ///\brief Converts an switch_xml structure back to xml. Returns a string of xml data that
 ///\ must be freed.
 ///\param xml the xml node
+///\param prn_header add <?xml version..> header too
 ///\return the xml text string
 SWITCH_DECLARE(char *) switch_xml_toxml(switch_xml_t xml, switch_bool_t prn_header);
+
+///\brief Converts an switch_xml structure back to xml using the buffer passed in the parameters.
+///\param xml the xml node
+///\param buf buffer to use
+///\param buflen size of buffer
+///\param offset offset to start at
+///\param prn_header add <?xml version..> header too
+///\return the xml text string
 SWITCH_DECLARE(char *) switch_xml_toxml_buf(switch_xml_t xml, char *buf, switch_size_t buflen, switch_size_t offset, switch_bool_t prn_header);
 
 ///\brief returns a NULL terminated array of processing instructions for the given



More information about the Freeswitch-svn mailing list