@defgroup switch_buffer Buffer Routines
@ingroup core1
The purpose of this module is to make a plain buffering interface that can be used for read/write buffers
throughout the application. The first implementation was done to provide the functionality and the interface
and I think it can be optimized under the hood as we go using bucket brigades and/or ring buffering techniques.
@{
\enum switch_channel_state_t
\brief Channel States (these are the defaults, CS_SOFT_EXECUTE, CS_EXCHANGE_MEDIA, and CS_CONSUME_MEDIA are often overridden by specific apps)
\brief Abstraction of an module endpoint interface
This is the glue between the abstract idea of a “channel” and what is really going on under the
hood. Each endpoint module fills out one of these tables and makes it available when a channel
is created of it’s paticular type.
\brief add a state handler table to a given channel
\param channel channel on which to add the state handler table
\param state_handler table of state handler functions
\return the index number/priority of the table negative value indicates failure
\brief Allocate a new channel
\param channel NULL pointer to allocate channel to
\param pool memory_pool to use for allocation
\return SWITCH_STATUS_SUCCESS if successful
\brief Clears given flag(s) on a given channel’s bridge partner
\param channel channel to derive the partner channel to clear flag(s) from
\param flag the flag to clear
\return true if the flag was cleared
\brief clear a state handler table from a given channel
\param channel channel from which to clear the state handler table
\param state_handler table of state handler functions
\brief Retrieve DTMF digits from a given channel
\param channel channel to retrieve digits from
\param dtmf digit
\return number of bytes read into the buffer
\brief Add information about a given channel to an event object
\param channel channel to add information about
\param event event to add information to
\brief Expand varaibles in a string based on the variables in a paticular channel
\param channel channel to expand the variables from
\param in the original string
\return the original string if no expansion takes place otherwise a new string that must be freed
\note it’s necessary to test if the return val is the same as the input and free the string if it is not.
\brief Retrieve private from a given channel
\param channel channel to retrieve data from
\param key unique keyname to retrieve your private data
\return void pointer to channel’s private data
\brief Retrieve an state handler tablefrom a given channel at given index level
\param channel channel from which to retrieve the state handler table
\param index the index of the state handler table (start from 0)
\return given channel’s state handler table at given index or NULL if requested index does not exist.
\brief View the timetable of a channel
\param channel channel to retrieve timetable from
\return a pointer to the channel’s timetable (created, answered, etc..)
\brief Retrieve a variable from a given channel to a pre-allocated buffer without using a memory pool.
\param channel channel to retrieve variable from
\param varname the name of the variable
\param buf a pre allocated buffer to put the value to
\param buflen size of the buffer
\return SWITCH_STATUS_SUCCESS if the value was copied to the buffer and it is not NULL, SWITCH_STATUS_FALSE otherwise.
\brief Retrieve a variable from a given channel
\param channel channel to retrieve variable from
\param varname the name of the variable
\return the value of the requested variable
\brief Retrieve a copy of a variable from a given channel. switch_safe_free() call will be required.
\param channel channel to retrieve variable from
\param varname the name of the variable
\return a strdup copy the value of the requested variable without using a memory pool.
\brief Connect a newly allocated channel to a session object and setup it’s initial state
\param channel the channel to initilize
\param session the session to connect the channel to
\param state the initial state of the channel
\param flags the initial channel flags
\brief Fire A presence event for the channel
\param channel the channel to initilize
\param rpid the rpid if for the icon to use
\param status the status message
\param id presence id
\brief Set given flag(s) on a given channel’s bridge partner
\param channel channel to derive the partner channel to set flag on
\param flag to set
\return true if the flag was set
\brief Assign a name to a given channel
\param channel channel to assign name to
\param name name to assign
\return SWITCH_STATUS_SUCCESS if name was assigned
\brief Takes presence_data_cols as a parameter or as a channel variable and copies them to channel profile variables
\param channel the channel on which to set the channel profile variables
\param presence_data_cols is a colon separated list of channel variables to copy to channel profile variables
\brief Set private data on channel
\param channel channel on which to set data
\param key unique keyname to associate your private data to
\param private_info void pointer to private data
\return SWITCH_STATUS_SUCCESS if data was set
\remarks set NULL to delete your private data
\brief Set a variable on a given channel
\param channel channel to set variable on
\param varname the name of the variable
\param value the value of the variable
\returns SWITCH_STATUS_SUCCESS if successful
\brief Set given flag(s) on a given channel to be applied on the next state change
\param channel channel on which to set flag(s)
\param flag flag to set
\brief Start iterating over the entries in the channel variable list.
\param channel the channel to iterate the variables for
\remark This function locks the profile mutex, use switch_channel_variable_last to unlock
\brief Add a media bug to the session
\param session the session to add the bug to
\param function user defined module/function/reason identifying this bug
\param target user defined identification of the target of the bug
\param callback a callback for events
\param user_data arbitrary user data
\param stop_time absolute time at which the bug is automatically removed (or 0)
\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
\brief Flush the read/write buffers for all media bugs on the session
\param session the session to flush the read/write buffers for all media bugs on the session
\brief Read a frame from the bug
\param bug the bug to read from
\param frame the frame to write the data to
\return SWITCH_STATUS_SUCCESS if the operation was a success
\brief Remove a media bug from the session
\param session the session to remove the bug from
\param bug bug to remove
\return SWITCH_STATUS_SUCCESS if the operation was a success
\brief Remove all media bugs from the session
\param session the session to remove the bugs from
\return SWITCH_STATUS_SUCCESS if the operation was a success
\brief Remove media bug callback
\param bug bug to remove
\param callback callback to remove
\return SWITCH_STATUS_SUCCESS if the operation was a success
\brief Test for the existance of a flag on an media bug
\param bug the object to test
\param flag the or’d list of flags to test
\return true value if the object has the flags defined
\brief Add a logical stream to a session
\param session the session to add the stream to
\param private_info an optional pointer to private data for the new stream
\return the stream id of the new stream
\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
\brief DE-Queue an event on a given session
\param session the session to de-queue the message on
\param event the de-queued event
\param force force the dequeue
\return the SWITCH_STATUS_SUCCESS if the event was de-queued
\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 SWITCH_STATUS_SUCCESS if the message was de-queued
\brief DE-Queue a private event on a given session
\param session the session to de-queue the message on
\param event the de-queued event
\return the SWITCH_STATUS_SUCCESS if the event was de-queued
\brief Queue an event on another session using its uuid
\param uuid_str the unique id of the session you want to send a message to
\param event the event to send
\return the status returned by the message handler
\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
\brief Execute an application on a session
\param session the current session
\param app the application’s name
\param arg application arguments
\param flags pointer to a flags variable to set the applications flags to
\return the application’s return value
\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
\brief Flush a message queue on a given session
\param session the session to de-queue the message on
\return SWITCH_STATUS_SUCCESS if the message was de-queued
\brief Retrieve a pointer to the channel object associated with a given session
\param session the session to retrieve from
\return a pointer to the channel object
\brief Retrieve the unique external identifier from a session
\param session the session to retrieve the uuid from
\return a string representing the uuid
\brief Retrieve the memory pool from a session
\param session the session to retrieve the pool from
\return the session’s pool
\note to be used sparingly
\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
\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
\brief Hangup all sessions which match specific channel variable(s)
\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
\brief Launch a thread designed to exist within the scope of a given session
\param session a session to allocate the thread from
\param func a function to execute in the thread
\param obj an arguement
\brief Send a message to another session using it’s uuid
\param uuid_str the unique id of the session you want to send a message to
\param message the switch_core_session_message_t object to send
\return the status returned by the message handler
\brief Request an outgoing session spawned from an existing session using a desired endpoing module
\param session the originating session
\param var_event switch_event_t containing paramaters
\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
\param pool optional existing memory pool to donate to the session
\param flags flags to use
\return the cause code of the attempted call
\brief pass an indication message on a session
\param session the session to pass the message across
\param indication the indication message to pass
\return SWITCH_STATUS_SUCCESS if the message was passed
\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
\brief Receive a message on a given session
\param session the session to receive the message from
\param message the message to recieve
\return the status returned by the message handler
\brief Queue an event on a given session
\param session the session to queue the message on
\param event the event to queue
\return the status returned by the message handler
\brief Queue an indication message on a session
\param session the session to queue the message to
\param indication the indication message to queue
\return SWITCH_STATUS_SUCCESS if the message was queued
\brief Queue a message on a session
\param session the session to queue the message to
\param message the message to queue
\return SWITCH_STATUS_SUCCESS if the message was queued
\brief Queue a private event on a given session
\param session the session to queue the message on
\param event the event to queue
\param priority event has high priority
\return the status returned by the message handler
\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 flags I/O flags to modify behavior (i.e. non blocking)
\param stream_id which logical media channel to use
\return SWITCH_STATUS_SUCCESS a the frame was read
\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 I/O flags to modify behavior (i.e. non blocking)
\param stream_id which logical media channel to use
\return SWITCH_STATUS_SUCCESS a if the frame was read
\brief Send an event to a session translating it to it’s native message format
\param session the session to receive the event
\param event the event to receive
\return the status returned by the handler
\brief RECV DTMF on a session
\param session session to recv DTMF from
\param dtmf string to recv from the session
\return SWITCH_STATUS_SUCCESS if the dtmf is ok to queue
\brief Allocate and return a new session from the core based on a given endpoint module name
\param endpoint_name the name of the endpoint module
\param pool the pool to use
\return the newly created session
\defgroup sessm Session Creation / Management
\ingroup core1
{
*!
\brief Allocate and return a new session from the core
\param endpoint_interface the endpoint interface the session is to be based on
\param pool the pool to use for the allocation (a new one will be used if NULL)
\return the newly created session
*/
\brief Send DTMF to a session
\param session session to send DTMF to
\param dtmf dtmf to send to the session
\return SWITCH_STATUS_SUCCESS if the dtmf was written
\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
\brief Add private user data to a session
\param session the session to add used data to
\param private_info the used data to add
\return SWITCH_STATUS_SUCCESS if data is added
\brief Assign the read codec to a given session
\param session session to add the codec to
\param codec the codec to add
\return SWITCH_STATUS_SUCCESS if successful
\brief Assign the original read codec to a given session. This is the read codec used by an endpoint.
\param session session to add the codec to
\param codec the codec to add
\return SWITCH_STATUS_SUCCESS if successful
\brief Assign the video_read codec to a given session
\param session session to add the codec to
\param codec the codec to add
\return SWITCH_STATUS_SUCCESS if successful
\brief Assign the video_write codec to a given session
\param session session to add the codec to
\param codec the codec to add
\return SWITCH_STATUS_SUCCESS if successful
\brief Assign the write codec to a given session
\param session session to add the codec to
\param codec the codec to add
\return SWITCH_STATUS_SUCCESS if successful
\brief printf-style style printing routine. The data is output to a string allocated from the session
\param session a session to use for allocation
\param fmt The format of the string
\param … The arguments to use while printing the data
\return The new string
\brief Launch the session thread (state machine) on a given session
\param session the session to activate the state machine on
\return SWITCH_STATUS_SUCCESS if the thread was launched
\brief Reset the buffers and resampler on a session, fail if can not lock codec mutexes
\param session the session to reset
\param flush_dtmf flush all queued dtmf events too
\return SWITCH_STATUS_SUCCESS if the session was reset
\brief Write a frame to a session
\param session the session to write to
\param frame the frame to write
\param flags I/O flags to modify behavior (i.e. non blocking)
\param stream_id which logical media channel to use
\return SWITCH_STATUS_SUCCESS a the frame was written
\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 I/O flags to modify behavior (i.e. non blocking)
\param stream_id which logical media channel to use
\return SWITCH_STATUS_SUCCESS a if the frame was written
\brief Add a body to an event
\param event the event to add to body to
\param fmt optional body of the event (varargs see standard sprintf family)
\return SWITCH_STATUS_SUCCESS if the body was added to the event
\note the body parameter can be shadowed by the switch_event_reserve_subclass_detailed function
\brief Add a header to an event
\param event the event to add the header to
\param stack the stack sense (stack it on the top or on the bottom)
\param header_name the name of the header to add
\param fmt the value of the header (varargs see standard sprintf family)
\return SWITCH_STATUS_SUCCESS if the header was added
\brief Add a string header to an event
\param event the event to add the header to
\param stack the stack sense (stack it on the top or on the bottom)
\param header_name the name of the header to add
\param data the value of the header
\return SWITCH_STATUS_SUCCESS if the header was added
\brief Render a string representation of an event suitable for printing or network transport
\param event the event to render
\param str a string pointer to point at the allocated data
\param encode url encode the headers
\return SWITCH_STATUS_SUCCESS if the operation was successful
\note you must free the resulting string when you are finished with it
\brief Bind an event callback to a specific event
\param id an identifier token of the binder
\param event the event enumeration to bind to
\param subclass_name the event subclass to bind to in the case if SWITCH_EVENT_CUSTOM
\param callback the callback functon to bind
\param user_data optional user specific data to pass whenever the callback is invoked
\return SWITCH_STATUS_SUCCESS if the event was binded
\brief Bind an event callback to a specific event
\param id an identifier token of the binder
\param event the event enumeration to bind to
\param subclass_name the event subclass to bind to in the case if SWITCH_EVENT_CUSTOM
\param callback the callback functon to bind
\param user_data optional user specific data to pass whenever the callback is invoked
\param node bind handle to later remove the binding.
\return SWITCH_STATUS_SUCCESS if the event was binded
\brief Create an event
\param event a NULL pointer on which to create the event
\param event_id the event id enumeration of the desired event
\param subclass_name the subclass name for custom event (only valid when event_id is SWITCH_EVENT_CUSTOM)
\return SWITCH_STATUS_SUCCESS on success
\brief Deliver an event to all of the registered event listeners
\param event the event to send (will be nulled)
\note normaly use switch_event_fire for delivering events (only use this when you wish to deliver the event blocking on your thread)
\brief Duplicate an event
\param event a NULL pointer on which to duplicate the event
\param todup an event to duplicate
\return SWITCH_STATUS_SUCCESS if the event was duplicated
\brief Fire an event with full arguement list
\param file the calling file
\param func the calling function
\param line the calling line number
\param event the event to send (will be nulled on success)
\param user_data optional private data to pass to the event handlers
\return
\brief Retrieve a header value from an event
\param event the event to read the header from
\param header_name the name of the header to read
\return the value of the requested header
\brief Parses a list of xml elements into an event
\param xml First element of the xml list to parse
\param keyname Name of the key attribute
\param keyvalue Name of the value attribute
\param event [out] event (if *event is NOT NULL, the headers will be appended to the existing event)
\brief Start the eventing system
\param pool the memory pool to use for the event system (creates a new one if NULL)
\return SWITCH_STATUS_SUCCESS when complete
\brief Reserve a subclass name for private use with a custom event
\param owner the owner of the event name
\param subclass_name the name to reserve
\return SWITCH_STATUS_SUCCESS if the name was reserved
\note There is nothing to enforce this but I recommend using module::event_name for the subclass names
\brief Render a XML representation of an event suitable for printing or network transport
\param event the event to render
\param fmt optional body of the event (varargs see standard sprintf family)
\return the xml object if the operation was successful
\note the body supplied by this function will supersede an existing body the event may have
\brief Write log data to the logging engine w/ optional JSON metadata
\param channel the log channel to write to
\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 meta log metadata - consumed by this function
\param fmt desired format
\param … variable args
\note there are channel macros to supply the first 4 parameters (SWITCH_CHANNEL_LOG, SWITCH_CHANNEL_LOG_CLEAN, …)
\see switch_types.h
\brief Write log data to the logging engine w/ optional JSON metadata
\param channel the log channel to write to
\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 meta log metadata - consumed by this function
\param fmt desired format
\param ap variable args
\note there are channel macros to supply the first 4 parameters (SWITCH_CHANNEL_LOG, SWITCH_CHANNEL_LOG_CLEAN, …)
\see switch_types.h
\brief Convert a log node to JSON object. Destroy JSON object when finished.
\param node the node
\param log_level the log level
\param json_format the output format definition
\param char_vars optional channel variables to add to logs
\brief Write log data to the logging engine
\param channel the log channel to write to
\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
\note there are channel macros to supply the first 4 parameters (SWITCH_CHANNEL_LOG, SWITCH_CHANNEL_LOG_CLEAN, …)
\see switch_types.h
\brief Write log data to the logging engine
\param channel the log channel to write to
\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 ap variable args
\note there are channel macros to supply the first 4 parameters (SWITCH_CHANNEL_LOG, SWITCH_CHANNEL_LOG_CLEAN, …)
\see switch_types.h
\brief Abstraction of an module endpoint interface
This is the glue between the abstract idea of a “channel” and what is really going on under the
hood. Each endpoint module fills out one of these tables and makes it available when a channel
is created of it’s paticular type.