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@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