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

FreeSWITCH SVN mrene at freeswitch.org
Tue Apr 28 13:41:44 PDT 2009


Author: mrene
Date: Tue Apr 28 15:41:44 2009
New Revision: 13181

Log:
switch_core.h doxygen update

Modified:
   freeswitch/trunk/src/include/switch_core.h

Modified: freeswitch/trunk/src/include/switch_core.h
==============================================================================
--- freeswitch/trunk/src/include/switch_core.h	(original)
+++ freeswitch/trunk/src/include/switch_core.h	Tue Apr 28 15:41:44 2009
@@ -412,6 +412,10 @@
 */
 SWITCH_DECLARE(int) switch_core_add_state_handler(_In_ const switch_state_handler_table_t *state_handler);
 
+/*!
+  \brief Remove a global state handler
+  \param state_handler the state handler to remove
+*/
 SWITCH_DECLARE(void) switch_core_remove_state_handler(_In_ const switch_state_handler_table_t *state_handler);
 
 /*! 
@@ -642,7 +646,7 @@
 #endif
 
 /*! 
-  \brief Locate a session based on it's uuiid
+  \brief Locate a session based on it's uuid
   \param uuid_str the unique id of the session you want to find
   \return the session or NULL
   \note if the session was located it will have a read lock obtained which will need to be released with switch_core_session_rwunlock()
@@ -653,7 +657,12 @@
 SWITCH_DECLARE(switch_core_session_t *) switch_core_session_locate(_In_z_ const char *uuid_str);
 #endif
 
-
+/*! 
+  \brief Locate a session based on it's uuid even if the channel is not ready
+  \param uuid_str the unique id of the session you want to find
+  \return the session or NULL
+  \note if the session was located it will have a read lock obtained which will need to be released with switch_core_session_rwunlock()
+*/
 #ifdef SWITCH_DEBUG_RWLOCKS
 #define switch_core_session_locate(uuid_str) switch_core_session_perform_force_locate(uuid_str, __FILE__, __SWITCH_FUNC__, __LINE__)
 #else
@@ -677,14 +686,31 @@
 SWITCH_DECLARE(void) switch_core_dump_variables(_In_ switch_stream_handle_t *stream);
 
 /*! 
-  \brief Hangup All Sessions
+  \brief Hangup all sessions
   \param cause the hangup cause to apply to the hungup channels
 */
 SWITCH_DECLARE(void) switch_core_session_hupall(_In_ switch_call_cause_t cause);
 
+/*! 
+  \brief Hangup all sessions which match a specific channel variable
+  \param var_name The variable name to look for
+  \param var_val The value to look for 
+  \param cause the hangup cause to apply to the hungup channels
+*/
 SWITCH_DECLARE(void) switch_core_session_hupall_matching_var(_In_ const char *var_name, _In_ const char *var_val, _In_ switch_call_cause_t cause);
+/*! 
+  \brief Hangup all sessions that belong to an endpoint
+  \param endpoint_interface The endpoint interface 
+  \param cause the hangup cause to apply to the hungup channels
+*/
 SWITCH_DECLARE(void) switch_core_session_hupall_endpoint(const switch_endpoint_interface_t *endpoint_interface, switch_call_cause_t cause);
 
+/*! 
+  \brief Get the session's partner (the session its bridged to)
+  \param session The session we're searching with 
+  \param partner [out] The session's partner, or NULL if it wasnt found
+  \return SWITCH_STATUS_SUCCESS or SWITCH_STATUS_FALSE if this session isn't bridged
+*/
 SWITCH_DECLARE(switch_status_t) switch_core_session_get_partner(switch_core_session_t *session, switch_core_session_t **partner);
 
 /*! 
@@ -725,14 +751,14 @@
   \brief DE-Queue an message on a given session
   \param session the session to de-queue the message on
   \param message the de-queued message
-  \return the  SWITCH_STATUS_SUCCESS if the message was de-queued
+  \return SWITCH_STATUS_SUCCESS if the message was de-queued
 */
 SWITCH_DECLARE(switch_status_t) switch_core_session_dequeue_message(_In_ switch_core_session_t *session, _Out_ switch_core_session_message_t **message);
 
 /*! 
   \brief Flush a message queue on a given session
   \param session the session to de-queue the message on
-  \return the  SWITCH_STATUS_SUCCESS if the message was de-queued
+  \return SWITCH_STATUS_SUCCESS if the message was de-queued
 */
 SWITCH_DECLARE(switch_status_t) switch_core_session_flush_message(_In_ switch_core_session_t *session);
 
@@ -746,12 +772,35 @@
 
 SWITCH_DECLARE(switch_app_log_t *) switch_core_session_get_app_log(_In_ switch_core_session_t *session);
 
+/*! 
+  \brief Execute an application on a session 
+  \param session the current session
+  \param application_interface the interface of the application to execute
+  \param arg application arguments
+  \warning Has to be called from the session's thread
+  \return the application's return value
+*/
 SWITCH_DECLARE(switch_status_t) switch_core_session_exec(_In_ switch_core_session_t *session,
 														 _In_ const switch_application_interface_t *application_interface, _In_opt_z_ const char *arg);
-
+/*! 
+  \brief Execute an application on a session 
+  \param session the current session
+  \param app the application's name
+  \param arg application arguments
+  \warning Has to be called from the session's thread
+  \return the application's return value
+*/
 SWITCH_DECLARE(switch_status_t) switch_core_session_execute_application(_In_ switch_core_session_t *session,
 																		_In_ const char *app, _In_opt_z_ const char *arg);
-
+/*! 
+  \brief Run a dialplan and execute an extension
+  \param session the current session
+  \param exten the interface of the application to execute
+  \param arg application arguments
+  \note It does not change the channel back to CS_ROUTING, it manually calls the dialplan and executes the applications
+  \warning Has to be called from the session's thread
+  \return the application's return value
+*/
 SWITCH_DECLARE(switch_status_t) switch_core_session_execute_exten(_In_ switch_core_session_t *session,
 																  _In_z_ const char *exten,
 																  _In_opt_z_ const char *dialplan, _In_opt_z_ const char *context);
@@ -980,10 +1029,16 @@
 /*! 
   \brief Send DTMF to a session
   \param session session to send DTMF to
-  \param dtmf string to send to the session
+  \param dtmf dtmf to send to the session
   \return SWITCH_STATUS_SUCCESS if the dtmf was written
 */
 SWITCH_DECLARE(switch_status_t) switch_core_session_send_dtmf(_In_ switch_core_session_t *session, const switch_dtmf_t *dtmf);
+/*! 
+  \brief Send DTMF to a session
+  \param session session to send DTMF to
+  \param dtmf_string string to send to the session
+  \return SWITCH_STATUS_SUCCESS if the dtmf was written
+*/
 SWITCH_DECLARE(switch_status_t) switch_core_session_send_dtmf_string(switch_core_session_t *session, const char *dtmf_string);
 
 /*! 
@@ -1076,8 +1131,28 @@
 */
 SWITCH_DECLARE(void *) switch_core_hash_find_locked(_In_ switch_hash_t *hash, _In_z_ const char *key, _In_ switch_mutex_t *mutex);
 
+/*!
+ \brief Gets the first element of a hashtable
+ \param depricate_me [deprecated] NULL
+ \param hash the hashtable to use
+ \return The element, or NULL if it wasn't found 
+*/
 SWITCH_DECLARE(switch_hash_index_t *) switch_hash_first(char *depricate_me, _In_ switch_hash_t *hash);
+
+/*!
+ \brief Gets the next element of a hashtable
+ \param hi The current element
+ \return The next element, or NULL if there are no more
+*/
 SWITCH_DECLARE(switch_hash_index_t *) switch_hash_next(_In_ switch_hash_index_t *hi);
+
+/*!
+ \brief Gets the key and value of the current hash element
+ \param hi The current element 
+ \param key [out] the key
+ \param klen [out] the key's size
+ \param val [out] the value 
+*/
 SWITCH_DECLARE(void) switch_hash_this(_In_ switch_hash_index_t *hi, _Out_opt_ptrdiff_cap_(klen)
 									  const void **key, _Out_opt_ switch_ssize_t *klen, _Out_ void **val);
 
@@ -1729,12 +1804,18 @@
 SWITCH_DECLARE(void) switch_core_set_globals(void);
 
 /*!
-  \brief indicate if 2 sessions are the same type
+  \brief Checks if 2 sessions are using the same endpoint module
   \param a the first session
   \param b the second session
   \return TRUE or FALSE
 */
 SWITCH_DECLARE(uint8_t) switch_core_session_compare(switch_core_session_t *a, switch_core_session_t *b);
+/*!
+  \brief Checks if a session is using a specific endpoint 
+  \param session the session
+  \param endpoint_interface interface of the endpoint to check
+  \return TRUE or FALSE
+*/
 SWITCH_DECLARE(uint8_t) switch_core_session_check_interface(switch_core_session_t *session, const switch_endpoint_interface_t *endpoint_interface);
 SWITCH_DECLARE(switch_hash_index_t *) switch_core_mime_index(void);
 SWITCH_DECLARE(const char *) switch_core_mime_ext2type(const char *ext);
@@ -1742,6 +1823,10 @@
 
 SWITCH_DECLARE(switch_loadable_module_interface_t *) switch_loadable_module_create_module_interface(switch_memory_pool_t *pool, const char *name);
 SWITCH_DECLARE(void *) switch_loadable_module_create_interface(switch_loadable_module_interface_t *mod, switch_module_interface_name_t iname);
+/*! 
+ \brief Get the current epoch time in microseconds
+ \return the current epoch time in microseconds
+*/
 SWITCH_DECLARE(switch_time_t) switch_micro_time_now(void);
 SWITCH_DECLARE(void) switch_core_memory_reclaim(void);
 SWITCH_DECLARE(void) switch_core_memory_reclaim_events(void);
@@ -1749,6 +1834,11 @@
 SWITCH_DECLARE(void) switch_core_memory_reclaim_all(void);
 SWITCH_DECLARE(void) switch_core_setrlimits(void);
 SWITCH_DECLARE(void) switch_time_sync(void);
+/*! 
+ \brief Get the current epoch time
+ \param [out] (optional) The current epoch time 
+ \return The current epoch time 
+*/
 SWITCH_DECLARE(time_t) switch_epoch_time_now(time_t *t);
 SWITCH_DECLARE(switch_status_t) switch_strftime_tz(const char *tz, const char *format, char *date, size_t len, switch_time_t thetime);
 SWITCH_DECLARE(switch_status_t) switch_time_exp_tz_name(const char *tz, switch_time_exp_t *tm, switch_time_t thetime);



More information about the Freeswitch-svn mailing list