@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.
@{
\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 Execute a registered API command
\param cmd the name of the API command to execute
\param arg the optional arguement to the command
\param session an optional session
\param stream stream for output
\return the status returned by the API call
Uses an atomic operation to add the uint32 value to the value at the
specified location of memory.
@param mem The location of the value to add to.
@param val The uint32 value to add to the value at the memory location.
Some architectures require atomic operations internal structures to be
initialized before use.
@param pool The memory pool to use when initializing the structures.
Uses an atomic operation to set a uint32 value at a specified location of
memory.
@param mem The location of memory to set.
@param val The uint32 value to set at the memory location.
\brief Allocate a new switch_buffer
\param pool Pool to allocate the buffer from
\param buffer returned pointer to the new buffer
\param max_len length required by the buffer
\return status
\brief Allocate a new dynamic switch_buffer
\param buffer returned pointer to the new buffer
\param blocksize length to realloc by as data is added
\param start_len ammount of memory to reserve initially
\param max_len length the buffer is allowed to grow to
\return status
\brief Read data from a switch_buffer_t up to the ammount of datalen if it is available, without removing read data from buffer.
\param buffer any buffer of type switch_buffer_t
\param data pointer to the read data to be returned
\param datalen amount of data to be returned
\return int ammount of data actually read
\brief Read data from a switch_buffer_t up to the ammount of datalen if it is available. Remove read data from buffer.
\param buffer any buffer of type switch_buffer_t
\param data pointer to the read data to be returned
\param datalen amount of data to be returned
\return int ammount of data actually read
\brief Read data endlessly from a switch_buffer_t
\param buffer any buffer of type switch_buffer_t
\param data pointer to the read data to be returned
\param datalen amount of data to be returned
\return int ammount of data actually read
\note Once you have read all the data from the buffer it will loop around.
\brief Remove data from the buffer
\param buffer any buffer of type switch_buffer_t
\param datalen amount of data to be removed
\return int size of buffer, or 0 if unable to toss that much data
\brief Write data into a switch_buffer_t up to the length of datalen
\param buffer any buffer of type switch_buffer_t
\param data pointer to the data to be written or 0 to fill in with datalen zeros
\param datalen amount of data to be written
\return int amount of buffer used after the write, or 0 if no space available
\brief build a URI string from components
\param uri output string
\param size maximum size of output string (including trailing null)
\param scheme URI scheme
\param user user part or null if none
\param sa host address
\param flags logical OR-ed combination of flags from \ref switch_uri_flags
\return number of characters printed (not including the trailing null)
\brief Executes the sql and returns the result as a string
\param [in] dbh The handle
\param [in] sql - sql to run
\param [out] str - buffer for result
\param [in] len - length of str buffer
\param [out] err - Error if it exists
\brief Executes the sql and uses callback for row-by-row processing
\param [in] dbh The handle
\param [in] sql - sql to run
\param [in] callback - function pointer to callback
\param [in] pdata - data to pass to callback
\param [out] err - Error if it exists
\brief Executes the sql and uses callback for row-by-row processing
\param [in] dbh The handle
\param [in] sql - sql to run
\param [in] callback - function pointer to callback
\param [in] err_callback - function pointer to callback when error occurs
\param [in] pdata - data to pass to callback
\param [out] err - Error if it exists
\brief Returns the handle to the pool, handle is NOT available to
other threads until the allocating thread actually terminates.
\param [in] The handle
\brief Add an application (instruction) to the given extension
\param session session associated with the extension (bound by scope)
\param caller_extension extension to add the application to
\param application_name the name of the application
\param extra_data optional argument to the application
\brief Add an application (instruction) to the given extension
\param session session associated with the extension (bound by scope)
\param caller_extension extension to add the application to
\param application_name the name of the application
\param fmt optional argument to the application (printf format string)
\brief Create a new extension with desired parameters
\param session session associated with the extension (bound by scope)
\param extension_name extension name
\param extension_number extension number
\return a new extension object allocated from the session’s memory pool
\brief Get the value of a field in a caller profile based on it’s name
\param caller_profile The caller profile
\param name the name
\note this function is meant for situations where the name paramater is the contents of the variable
\brief Add headers to an existing event in regards to a specific profile
\param caller_profile the desired profile
\param prefix a prefix string to all of the field names (for uniqueness)
\param event the event to add the information to
\brief Create a new caller profile object
\param pool memory pool to use
\param username tne username of the caller
\param dialplan name of the dialplan module in use
\param caller_id_name caller ID name
\param caller_id_number caller ID number
\param network_addr network address
\param ani ANI information
\param aniii ANI II information
\param rdnis RDNIS
\param source the source
\param context a logical context
\param destination_number destination number
\return a new profile object allocated from the session’s memory pool
\brief Change the volume of a signed linear audio frame
\param data the audio data
\param samples the number of 2 byte samples
\param vol the volume factor -4 -> 4
\brief Change the volume of a signed linear audio frame with more granularity
\param data the audio data
\param samples the number of 2 byte samples
\param vol the volume factor -12 -> 12
\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 Convert an array of chars to an array of floats
\param c the char buffer
\param f the float buffer
\param len the length of the buffers
\return the size of the converted buffer
\brief Return the RFC2833 event based on an key character
\param key the charecter to encode
\return the event id for the specified character or -1 on an invalid input
\brief Retrieve next name/value pair from configuration file
\param cfg (switch_config_t *) config handle to use
\param var pointer to aim at the new variable name
\param val pointer to aim at the new value
\brief Open a configuration file
\param cfg (switch_config_t *) config handle to use
\param file_path path to the file
\return 1 (true) on success 0 (false) on failure
\defgroup sh State Handlers
\ingroup core1
{
*!
\brief Add a global state handler
\param state_handler a state handler to add
\return the current index/priority of this handler
*/
\brief Disable a grammar from an asr handle
\param ah the handle to disable the grammar from
\param name the name of the grammar to disable
\return SWITCH_STATUS_SUCCESS
\brief Enable a grammar from an asr handle
\param ah the handle to enable the grammar from
\param name the name of the grammar to enable
\return SWITCH_STATUS_SUCCESS
\brief Feed audio data to an asr handle
\param ah the handle to feed data to
\param data a pointer to the data
\param len the size in bytes of the data
\param flags flags to influence behaviour
\return SWITCH_STATUS_SUCCESS
\brief Feed DTMF to an asr handle
\param ah the handle to feed data to
\param dtmf a string of DTMF digits
\param flags flags to influence behaviour
\return SWITCH_STATUS_SUCCESS
\brief Get result headers from an asr handle
\param ah the handle to get results from
\param headers a pointer to dynamically allocate an switch_event_t result to
\param flags flags to influence behaviour
\return SWITCH_STATUS_SUCCESS
\brief Get results from an asr handle
\param ah the handle to get results from
\param xmlstr a pointer to dynamically allocate an xml result string to
\param flags flags to influence behaviour
\return SWITCH_STATUS_SUCCESS
\brief Load a grammar to an asr handle
\param ah the handle to load to
\param grammar the grammar text, file path, or URI
\param name the grammar name
\return SWITCH_STATUS_SUCCESS
\brief Open an asr handle
\param ah the asr handle to open
\param module_name the name of the asr module
\param codec the preferred codec
\param rate the preferred rate
\param dest the destination address
\param flags flags to influence behaviour
\param pool the pool to use (NULL for new pool)
\return SWITCH_STATUS_SUCCESS if the asr handle was opened
\brief Unload a grammar from an asr handle
\param ah the handle to unload the grammar from
\param name the name of the grammar to unload
\return SWITCH_STATUS_SUCCESS
\brief send control data using a codec handle
\param codec the codec handle to use
\param cmd the command to send
\param ctype the type of the arguement
\param cmd_data a void pointer to the data matching the passed type
\param atype the type of the extra arguement
\param cmd_arg a void pointer to the data matching the passed type
\param rtype the type of the response if any
\param ret_data a void pointer to a pointer of return data
\return SWITCH_STATUS_SUCCESS if the command was received
\brief Decode data using a codec handle
\param codec the codec handle to use
\param other_codec the codec handle of the last codec used
\param encoded_data the buffer to read the encoded data from
\param encoded_data_len the size of the encoded_data buffer
\param encoded_rate the rate of the encoded data
\param decoded_data the raw data buffer
\param decoded_data_len then length of the raw buffer
\param decoded_rate the new rate of the decoded data
\param flag flags to exchange
\return SWITCH_STATUS_SUCCESS if the data was decoded
\note decoded_data_len will be rewritten to the in-use size of decoded_data
\brief Decode video data using a codec handle
\param codec the codec handle to use
\param frame the frame to be decoded
\param img the new image in I420 format, allocated by the codec
\param flag flags to exchange
\return SWITCH_STATUS_SUCCESS if the data was decoded, and a non-NULL img
\brief Encode data using a codec handle
\param codec the codec handle to use
\param other_codec the codec handle of the last codec used
\param decoded_data the raw data
\param decoded_data_len then length of the raw buffer
\param decoded_rate the rate of the decoded data
\param encoded_data the buffer to write the encoded data to
\param encoded_data_len the size of the encoded_data buffer
\param encoded_rate the new rate of the encoded data
\param flag flags to exchange
\return SWITCH_STATUS_SUCCESS if the data was encoded
\note encoded_data_len will be rewritten to the in-use size of encoded_data
\defgroup misc Misc
\ingroup core1
{
*!
\brief Retrieve a FILE stream of a given text channel name
\param channel text channel enumeration
\return a FILE stream
*/
In the SQL strings input to switch_core_db_prepare(),
one or more literals can be replace by parameters “?” or “:AAA” or
“$VVV” where AAA is an identifer and VVV is a variable name according
to the syntax rules of the TCL programming language.
The value of these parameters (also called “host parameter names”) can
be set using the routines listed below.
In the SQL strings input to switch_core_db_prepare(),
one or more literals can be replace by parameters “?” or “:AAA” or
“$VVV” where AAA is an identifer and VVV is a variable name according
to the syntax rules of the TCL programming language.
The value of these parameters (also called “host parameter names”) can
be set using the routines listed below.
In the SQL strings input to switch_core_db_prepare(),
one or more literals can be replace by parameters “?” or “:AAA” or
“$VVV” where AAA is an identifer and VVV is a variable name according
to the syntax rules of the TCL programming language.
The value of these parameters (also called “host parameter names”) can
be set using the routines listed below.
In the SQL strings input to switch_core_db_prepare(),
one or more literals can be replace by parameters “?” or “:AAA” or
“$VVV” where AAA is an identifer and VVV is a variable name according
to the syntax rules of the TCL programming language.
The value of these parameters (also called “host parameter names”) can
be set using the routines listed below.
Return the number of columns in the result set returned by the compiled
SQL statement. This routine returns 0 if pStmt is an SQL statement
that does not return data (for example an UPDATE).
The first parameter is a compiled SQL statement. This function returns
the column heading for the Nth column of that statement, where N is the
second function parameter. The string returned is UTF-8.
^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
even empty strings, are always zero-terminated. ^The return
value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
Return a pointer to a UTF-8 encoded string describing in english the
error condition for the most recent switch_core_db_* API call. The returned
string is always terminated by an 0x00 byte.
This function is called to delete a compiled
SQL statement obtained by a previous call to switch_core_db_prepare().
If the statement was executed successfully, or
not executed at all, then SWITCH_CORE_DB_OK is returned. If execution of the
statement failed then an error code is returned.
This next routine is really just a wrapper around switch_core_db_exec().
Instead of invoking a user-supplied callback for each row of the
result, this routine remembers each row of the result in memory
obtained from malloc(), then returns all of the result after the
query has finished.
Each entry in a table has a unique integer key. (The key is
the value of the INTEGER PRIMARY KEY column if there is such a column,
otherwise the key is generated at random. The unique key is always
available as the ROWID, OID, or ROWID column.) The following routine
returns the integer key of the most recent insert in the database.
Open the database file “filename”. The “filename” is UTF-8
encoded. A switch_core_db_t* handle is returned in *Db, even
if an error occurs. If the database is opened (or created) successfully,
then SWITCH_CORE_DB_OK is returned. Otherwise an error code is returned. The
switch_core_db_errmsg() routine can be used to obtain
an English language description of the error.
}
\defgroup db Database Functions
\ingroup core1
{
*!
\brief Open a core db (SQLite) file
\param filename the path to the db file to open
\return the db handle
*/
\brief Execute a sql stmt until it is accepted
\param db the db handle
\param sql the sql to execute
\param retries the number of retries to use
\return SWITCH_STATUS_SUCCESS if successful
The switch_core_db_reset() function is called to reset a compiled SQL
statement obtained by a previous call to switch_core_db_prepare()
back to it’s initial state, ready to be re-executed.
Any SQL statement variables that had values bound to them using
the switch_core_db_bind_*() API retain their values.
After an SQL query has been compiled with a call to either
switch_core_db_prepare(), then this function must be
called one or more times to execute the statement.
\brief perform a test query then perform a reactive query if the first one fails
\param db the db handle
\param test_sql the test sql
\param drop_sql the drop sql
\param reactive_sql the reactive sql
\brief Obtain the next name/value pair in the current record
\param dh a directory handle to use
\param var a pointer to pointer of the name to fill in
\param val a pointer to pointer of the value to fill in
\return SWITCH_STATUS_SUCCESS if an item exists
\defgroup dir Directory Service Functions
\ingroup core1
{
*!
\brief Open a directory handle
\param dh a directory handle to use
\param module_name the directory module to use
\param source the source of the db (ip, hostname, path etc)
\param dsn the username or designation of the lookup
\param passwd the password
\param pool the pool to use (NULL for new pool)
\return SWITCH_STATUS_SUCCESS if the handle is opened
*/
\brief Query a directory handle
\param dh a directory handle to use
\param base the base to query against
\param query a string of filters or query data
\return SWITCH_STATUS_SUCCESS if the query is successful
\brief get metadata of the desired string
\param fh the file handle to get data from
\param col the enum of the col name
\param string pointer to the string to fetch
\return SWITCH_STATUS_SUCCESS with cur_pos adjusted to new position
\brief Duplicates a file handle using another pool
\param oldfh the file handle to duplicate
\param newfh pointer to assign new file handle to
\param pool the pool to use (NULL for new pool)
\return SWITCH_STATUS_SUCCESS if the file handle was duplicated
\brief Pre close an open file handle, then can get file size etc., no more wirte to the file
\param fh the file handle to close
\return SWITCH_STATUS_SUCCESS if the file handle was pre closed
\brief Read media from a file handle
\param fh the file handle to read from (must be initilized by you memset all 0 for read, fill in channels and rate for write)
\param data the buffer to read the data to
\param len the max size of the buffer
\return SWITCH_STATUS_SUCCESS with len adjusted to the bytes read if successful
\brief Seek a position in a file
\param fh the file handle to seek
\param cur_pos the current position in the file
\param samples the amount of samples to seek from the beginning of the file
\param whence the indicator (see traditional seek)
\return SWITCH_STATUS_SUCCESS with cur_pos adjusted to new position
\brief Set metadata to the desired string
\param fh the file handle to set data to
\param col the enum of the col name
\param string the string to add
\return SWITCH_STATUS_SUCCESS with cur_pos adjusted to new position
\brief Write media to a file handle
\param fh the file handle to write to
\param data the buffer to write
\param len the amount of data to write from the buffer
\return SWITCH_STATUS_SUCCESS with len adjusted to the bytes written if successful
\brief Write media to a file handle
\param fh the file handle to write to
\param data the buffer to write
\param len the amount of data to write from the buffer
\return SWITCH_STATUS_SUCCESS with len adjusted to the bytes written if successful
\brief Delete data from a hash based on desired key
\param hash the hash to delete from
\param key the key from which to delete the data
\return The value stored if the data is deleted otherwise NULL
\brief Delete data from a hash based on desired key
\param hash the hash to delete from
\param key the key from which to delete the data
\param mutex optional mutex to lock
\return a pointer to the deleted data
\brief Delete data from a hash based on callback function
\param hash the hash to delete from
\param callback the function to call which returns SWITCH_TRUE to delete, SWITCH_FALSE to preserve
\return SWITCH_STATUS_SUCCESS if any data is deleted
\brief Delete data from a hash based on desired key
\param hash the hash to delete from
\param key the key from which to delete the data
\param mutex optional rwlock to wrlock
\return a pointer to the deleted data
\brief Retrieve data from a given hash
\param hash the hash to retrieve from
\param key the key to retrieve
\return a pointer to the data held in the key
\brief Retrieve data from a given hash
\param hash the hash to retrieve from
\param key the key to retrieve
\param mutex optional mutex to lock
\return a pointer to the data held in the key
\brief Retrieve data from a given hash
\param hash the hash to retrieve from
\param key the key to retrieve
\param mutex optional rwlock to rdlock
\return a pointer to the data held in the key
\brief Gets the first element of a hashtable
\param deprecate_me [deprecated] NULL
\param hash the hashtable to use
\return The element, or NULL if it wasn’t found
\defgroup hashf Hash Functions
\ingroup core1
{
*!
\brief Initialize a hash table
\param hash a NULL pointer to a hash table to aim at the new hash
\param pool the pool to use for the new hash
\return SWITCH_STATUS_SUCCESS if the hash is created
*/
\brief Allocate memory and insert into a hash
\param hash the hash to add data to
\param key the name of the key to add the data to
\param size the size in bytes to allocate
\return pointer to the allocated memory
\note the string key must be a constant or a dynamic string
\brief Insert data into a hash and set flags so the value is automatically freed on delete
\param hash the hash to add data to
\param key the name of the key to add the data to
\param data the data to add
\return SWITCH_STATUS_SUCCESS if the data is added
\note the string key must be a constant or a dynamic string
\brief Insert data into a hash
\param hash the hash to add data to
\param key the name of the key to add the data to
\param data the data to add
\return SWITCH_STATUS_SUCCESS if the data is added
\note the string key must be a constant or a dynamic string
\brief Insert strdup(str) into a hash and set flags so the value is automatically freed on delete
\param hash the hash to add str to
\param key the name of the key to add the str to
\param str string to strdup and add
\return SWITCH_STATUS_SUCCESS if the data is added
\note the string key must be a constant or a dynamic string
\brief Insert strdup(str) into a hash
\param hash the hash to add str to
\param key the name of the key to add the str to
\param str string to strdup and add
\return SWITCH_STATUS_SUCCESS if the data is added
\note the string key must be a constant or a dynamic string
\brief Insert data into a hash
\param hash the hash to add data to
\param key the name of the key to add the data to
\param data the data to add
\param mutex optional mutex to lock
\return SWITCH_STATUS_SUCCESS if the data is added
\note the string key must be a constant or a dynamic string
\brief Insert data into a hash with an auto-generated key based on the data pointer
\param hash the hash to add data to
\param data unique pointer to add
\return SWITCH_STATUS_SUCCESS if the data is added
\brief Retrieve data from a given hash
\param hash the hash to retrieve from
\param key the key to retrieve
\param mutex optional rwlock to wrlock
\return a pointer to the data held in the key
\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
\defgroup ss Startup/Shutdown
\ingroup core1
{
*!
\brief Initilize the core
\param console optional FILE stream for output
\param flags core flags
\param err a pointer to set any errors to
\note to be called at application startup
*/
\brief Initilize the core and load modules
\param console optional FILE stream for output
\param flags core flags
\param err a pointer to set any errors to
\note to be called at application startup instead of switch_core_init. Includes module loading.
\brief Execute a management operation.
\param relative_oid the relative oid of the operation.
\param action the action to perform.
\param data input/output string.
\param datalen size in bytes of data.
\return SUCCESS on sucess.
\brief Breakdown a number of milliseconds into various time spec
\param total_ms a number of milliseconds
\param duration an object to store the results
\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 Initilize the port allocator
\param start the starting port
\param end the ending 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
\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 Conditionally add a global variable to the core
\param varname the name of the variable
\param value the value of the variable
\param val2 the value of the variable to verify against
\ If the global did not exist and val2==“”, add global with value, return true
\ If the global exists with the value of val2, replace it, return true
\ If the global exists with a value other than val2, return false
\brief Add a global variable to the core
\param varname the name of the variable
\param value the value of the variable
\ If \p value is NULL, then \p varname is deleted.
\brief Close an open speech handle
\param sh the speech handle to close
\param flags flags in/out for fine tuning
\return SWITCH_STATUS_SUCCESS if the file handle was closed
\brief Feed text to the TTS module
\param sh the speech handle to feed
\param text the buffer to write
\param flags flags in/out for fine tuning
\return SWITCH_STATUS_SUCCESS with len adjusted to the bytes written if successful
\defgroup speech ASR/TTS Functions
\ingroup core1
{
*!
\brief Open a speech handle
\param sh a speech handle to use
\param module_name the speech module to use
\param voice_name the desired voice name
\param rate the sampling rate
\param interval the sampling interval
\param flags tts flags
\param pool the pool to use (NULL for new pool)
\return SWITCH_STATUS_SUCCESS if the handle is opened
*/
\brief Read rendered audio from the TTS module
\param sh the speech handle to read
\param data the buffer to read to
\param datalen the max size / written size of the data
\param rate the rate of the read audio
\param flags flags in/out for fine tuning
\return SWITCH_STATUS_SUCCESS with len adjusted to the bytes written if successful
\brief printf-style style printing routine. The data is output to a string allocated from the pool
\param pool a pool 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 Check if the current step has been exceeded
\param timer the timer to wait on
\param step increment timer if a tick was detected
\return the newest sample count
\defgroup timer Timer Functions
\ingroup core1
{
*!
\brief Request a timer handle using given time module
\param timer a timer object to allocate to
\param timer_name the name of the timer module to use
\param interval desired interval
\param samples the number of samples to increment on each cycle
\param pool the memory pool to use for allocation
\return
*/
\brief Create a pointer to the file name in a given file path eliminating the directory name
\return the pointer to the next character after the final / or \ characters
Create a new directory on the file system.
@param path the path for the directory to be created. (use / on all systems)
@param perm Permissions for the new direcoty.
@param pool the pool to use.
Creates a new directory on the file system, but behaves like
‘mkdir -p’. Creates intermediate directories as required. No error
will be reported if PATH already exists.
@param path the path for the directory to be created. (use / on all systems)
@param perm Permissions for the new direcoty.
@param pool the pool to use.
\brief Escape a string by prefixing a list of characters with an escape character
\param pool a memory pool to use
\param in the string
\param delim the list of characters to escape
\param esc the escape character
\return the escaped string
\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
Open the specified file.
@param newf The opened file descriptor.
@param fname The full path to the file (using / on all systems)
@param flag Or’ed value of:
Create an anonymous pipe.
@param in The file descriptor to use as input to the pipe.
@param out The file descriptor to use as output from the pipe.
@param pool The pool to operate on.
Get the timeout value for a pipe or manipulate the blocking state.
@param thepipe The pipe we are getting a timeout for.
@param timeout The current timeout value in microseconds.
Set the timeout value for a pipe or manipulate the blocking state.
@param thepipe The pipe we are setting a timeout on.
@param timeout The timeout value in microseconds. Values < 0 mean wait
forever, 0 means do not wait at all.
Read data from the specified file.
@param thefile The file descriptor to read from.
@param buf The buffer to store the data to.
@param nbytes On entry, the number of bytes to read; on exit, the number
of bytes read.
Delete the specified file.
@param path The full path to the file (using / on all systems)
@param pool The pool to use.
@remark If the file is open, it won’t be removed until all
instances are closed.
Write data to the specified file.
@param thefile The file descriptor to write to.
@param buf The buffer which contains the data.
@param nbytes On entry, the number of bytes to write; on exit, the number
of bytes written.
\brief find primary ip of the specified interface
\param buf the buffer to write the ip address found into
\param len the length of the buf
\param mask the CIDR found (AF_INET only)
\param ifname interface name to check
\param family the address family to return (AF_INET or AF_INET6)
\return SWITCH_STATUS_SUCCESSS for success, otherwise failure
\brief find local ip of the box
\param buf the buffer to write the ip address found into
\param len the length of the buf
\param mask the CIDR found (AF_INET only)
\param family the address family to return (AF_INET or AF_INET6)
\return SWITCH_STATUS_SUCCESSS for success, otherwise failure
\brief Convert an array of floats to an array of chars
\param f an array of floats
\param c an array of chars
\param len the length of the buffers
\return the size of the converted buffer
\brief Convert an array of floats to an array of shorts
\param f the float buffer
\param s the short buffer
\param len the length of the buffers
\return the size of the converted buffer
parse http headers in a buffer
return status of success or not
\param[in] buffer the buffer start from the very begining of the http request, e.g. ’GET ’
\param[in] datalen the buffer length
\param[out] the http request pointer or null, need destroy later if got non-NULL pointer
\return SWITCH_STATUS_SUCCESS | SWITCH_STATUS_FALSE
\brief Write an image file, supported formats png,jpg,bmp,tga,hdr
\param[in] img The image descriptor
\param[in] file_name The file_name to write
\param[in] quality Only used in jpg, 1 ~ 100
\brief Check if a 32 bit unsigned number is in a range.
\param str string to check. Should not contain non-digit characters.
\param from start of range including this number
\param to end of range including this number
\return true or false
\brief Bridge leaving b-leg in the control of another thread. Call from b-leg first then call switch_ivr_multi_threaded_bridge on a-leg and b-leg.
\param session b-leg session
\return SWITCH_STATUS_SUCCESS if all is well
\brief Signal the session to broadcast audio
\param uuid the uuid of the session to broadcast on
\param path the path data of the broadcast “/path/to/file.wav []” or “speak:||”
\param flags flags to send to the request (SMF_ECHO_BRIDGED to send the broadcast to both sides of the call)
\return SWITCH_STATUS_SUCCESS if all is well
\brief Wait for DTMF digits calling a pluggable callback function when digits are collected.
\param session the session to read.
\param args arguements to pass for callbacks etc
\param timeout a timeout in milliseconds
\return SWITCH_STATUS_SUCCESS to keep the collection moving.
\brief Wait for specified number of DTMF digits, untile terminator is received or until the channel hangs up.
\param session the session to read.
\param buf strig to write to
\param buflen max size of buf
\param maxdigits max number of digits to read
\param terminators digits to end the collection
\param terminator actual digit that caused the collection to end (if any)
\param first_timeout timeout in ms
\param digit_timeout digit timeout in ms
\param abs_timeout abs timeout in ms
\return SWITCH_STATUS_SUCCESS to keep the collection moving.
@defgroup switch_ivr IVR Library
@ingroup core1
A group of core functions to do IVR related functions designed to be
building blocks for a higher level IVR interface.
@{
\brief Engage background Speech detection on a session
\param session the session to attach
\param mod_name the module name of the ASR library
\param grammar the grammar text, URI, or local file name
\param name the grammar name
\param dest the destination address
\param ah an ASR handle to use (NULL to create one)
\return SWITCH_STATUS_SUCCESS if all is well
\brief Disable all grammars on a background speech detection handle
\param session The session to change the grammar on
\return SWITCH_STATUS_SUCCESS if all is well
\brief Disable a grammar on a background speech detection handle
\param session The session to change the grammar on
\param name the grammar name
\return SWITCH_STATUS_SUCCESS if all is well
\brief Enable a grammar on a background speech detection handle
\param session The session to change the grammar on
\param name the grammar name
\return SWITCH_STATUS_SUCCESS if all is well
\brief Initialize background Speech detection on a session, so that parameters can be set, and grammars loaded.
After calling this function, it is possible to call switch_ivr_set_param_detect_speech() to set recognition parameters.
Calling switch_ivr_detect_speech_load_grammar() starts the speech recognition.
\param session the session to attach
\param mod_name the module name of the ASR library
\param dest the destination address
\param ah an ASR handle to use (NULL to create one)
\return SWITCH_STATUS_SUCCESS if all is well
\brief Load a grammar on a background speech detection handle
\param session The session to change the grammar on
\param grammar the grammar text, URI, or local file name
\param name the grammar name
\return SWITCH_STATUS_SUCCESS if all is well
\brief Start input timers on a background speech detection handle
\param session The session to start the timers on
\return SWITCH_STATUS_SUCCESS if all is well
\brief Unload a grammar on a background speech detection handle
\param session The session to change the grammar on
\param name the grammar name
\return SWITCH_STATUS_SUCCESS if all is well
\brief Destroys a digit stream object
\param stream a pointer to the stream object
\return NULL if no match found or consumer data that was associated with a given digit string when matched
\brief Create a new digit stream object
\param parser a pointer to the parser object created by switch_ivr_digit_stream_parser_new
\param stream a pointer to the stream object pointer
\return NULL if no match found or consumer data that was associated with a given digit string when matched
\brief Delete a string to action mapping
\param parser a pointer to the parser object created by switch_ivr_digit_stream_parser_new
\param digits the digit string to be removed from the map
\return SWITCH_STATUS_SUCCESS if all is well
\brief Feed digits collected into the stream for event match testing
\param parser a pointer to the parser object created by switch_ivr_digit_stream_parser_new
\param stream a stream to write data to
\param digit a digit to collect and test against the map of digit strings
\return NULL if no match found or consumer data that was associated with a given digit string when matched
\brief Create a digit stream parser object
\param pool the pool to use for the new hash
\param parser a pointer to the object pointer
\return SWITCH_STATUS_SUCCESS if all is well
\brief Set a digit string to action mapping
\param parser a pointer to the parser object created by switch_ivr_digit_stream_parser_new
\param digits a string of digits to associate with an action
\param data consumer data attached to this digit string
\return SWITCH_STATUS_SUCCESS if all is well
\brief Set a digit string terminator
\param parser a pointer to the parser object created by switch_ivr_digit_stream_parser_new
\param digit the terminator digit
\return SWITCH_STATUS_SUCCESS if all is well
\brief Reset the collected digit stream to nothing
\param stream a pointer to the parser stream object created by switch_ivr_digit_stream_new
\return SWITCH_STATUS_SUCCESS if all is well
\brief displace the media for a session with the audio from a file
\param session the session to displace
\param file filename
\param limit time limit in ms
\param flags m (mux) l (loop) or r(read session instead of write session)
\return SWITCH_STATUS_SUCCESS if all is well
\brief Eavesdrop on a another session
\param session our session
\param uuid the uuid of the session to spy on
\param require_group group name to use to limit by group
\param flags tweak read-mux, write-mux and dtmf
\return SWITCH_STATUS_SUCESS if all is well
\brief Generate an JSON CDR report.
\param session the session to get the data from.
\param json_cdr pointer to the json object
\return SWITCH_STATUS_SUCCESS if successful
\note on success the json object must be freed
\brief Generate an XML CDR report.
\param session the session to get the data from.
\param xml_cdr pointer to the xml_record
\return SWITCH_STATUS_SUCCESS if successful
\note on success the xml object must be freed
\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
\brief Toggles channel hold state of session
\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
\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
\brief Start generating DTMF inband
\param session the session to generate on
\param read_stream true to use the session we are reading from, false for the session we are writing to.
\return SWITCH_STATUS_SUCCESS if all is well
\brief Signal a session to request direct media access to it’s remote end
\param uuid the uuid of the session to request
\param flags flags to influence behaviour (SMF_REBRIDGE to rebridge the call in media mode)
\return SWITCH_STATUS_SUCCESS if all is well
\brief switch_ivr_menu_bind_action: Bind a keystroke to an action.
\param menu The menu obj you wish to bind to.
\param ivr_action switch_ivr_action_t enum of what you want to do.
\param arg Optional (sometimes necessary) string arguement.
\param bind KeyStrokes to bind the action to.
\return SWUTCH_STATUS_SUCCESS if the action was binded
\brief Bind a keystroke to a callback function.
\param menu The menu obj you wish to bind to.
\param function The function to call [int proto(struct switch_ivr_menu *, char *, size_t, void *)]
\param arg Optional (sometimes necessary) string arguement.
\param bind KeyStrokes to bind the action to.
\note The function is passed a buffer to fill in with any required argument data.
\note The function is also passed an optional void pointer to an object set upon menu execution. (think threads)
\note The function returns an switch_ivr_action_t enum of what you want to do. and looks to your buffer for args.
\return SWUTCH_STATUS_SUCCESS if the function was binded
\brief Execute a menu.
\param session The session running the menu.
\param stack The top-level menu object (the first one you created.)
\param name A pointer to the name of the menu.
\param obj A void pointer to an object you want to make avaliable to your callback functions that you may have binded with switch_ivr_menu_bind_function.
\return SWITCH_STATUS_SUCCESS if all is well
\brief Create a new menu object.
\param new_menu the pointer to the new menu
\param main The top level menu, (NULL if this is the top level one).
\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 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 transfer_sound Optional pointer to a sound to play upon transfer away from the menu.
\param confirm_macro phrase macro name to confirm input
\param confirm_key the dtmf key required for positive confirmation
\param tts_engine the tts engine to use for this menu
\param tts_voice the tts voice to use for this menu
\param confirm_attempts number of times to prompt to confirm input before failure
\param inter_timeout inter-digit timeout
\param digit_len max number of digits
\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).
\return SWITCH_STATUS_SUCCESS if the menu was created.
\brief free a stack of menu objects.
\param stack The top level menu you wish to destroy.
\return SWITCH_STATUS_SUCCESS if the object was a top level menu and it was freed
\param xml_menu_ctx The XML menu parser context previously created by switch_ivr_menu_stack_xml_init
\param name The xml tag name to add to the parser engine
\param function The menu function callback that will be executed when menu digits are bound to this name
\return SWITCH_STATUS_SUCCESS if all is well
\brief Build a menu stack from an xml source
\param xml_menu_ctx The XML menu parser context previously created by switch_ivr_menu_stack_xml_init
\param menu_stack The menu stack object that will be created for you
\param xml_menus The xml Menus source
\param xml_menu The xml Menu source of the menu to be created
\return SWITCH_STATUS_SUCCESS if all is well
\param xml_menu_ctx A pointer of a XML menu parser context to be created
\param pool memory pool (NULL to create one)
\return SWITCH_STATUS_SUCCESS if all is well
\brief Bridge Audio from one session to another
\param session one session
\param peer_session the other session
\param dtmf_callback a callback for messages and dtmf
\param session_data data to pass to the DTMF callback for session
\param peer_session_data data to pass to the DTMF callback for peer_session
\return SWITCH_STATUS_SUCCESS if all is well
\brief Signal a session to request indirect media allowing it to exchange media directly with another device
\param uuid the uuid of the session to request
\param flags flags to influence behaviour (SMF_REBRIDGE to rebridge the call in no_media mode)
\return SWITCH_STATUS_SUCCESS if all is well
\brief Make an outgoing call
\param session originating session
\param bleg B leg session
\param cause a pointer to hold call cause
\param bridgeto the desired remote callstring
\param timelimit_sec timeout in seconds for outgoing call
\param table optional state handler table to install on the channel
\param cid_name_override override the caller id name
\param cid_num_override override the caller id number
\param caller_profile_override override the entire calling caller profile
\param ovars variables to be set on the outgoing channel
\param flags flags to pass
\return SWITCH_STATUS_SUCCESS if bleg is a running session.
\note bleg will be read locked which must be unlocked with switch_core_session_rwunlock() before losing scope
\brief Parse command from an event
\param session the session on which to parse the event
\param event the event to parse
\return SWITCH_STATUS_SUCCESS if successful
\brief play a file to the session while doing speech recognition.
\param session the session to play and detect on
\param file the path to the file
\param mod_name the module name of the ASR library
\param grammar the grammar text, URI, or local file name
\param result of speech recognition, allocated from the session pool
\param input_timeout time to wait for input
\param args arguements to pass for callbacks etc
\return SWITCH_STATUS_SUCCESS if all is well
\brief play a file from the disk to the session
\param session the session to play the file too
\param fh file handle to use (NULL for builtin one)
\param file the path to the file
\param args arguements to pass for callbacks etc
\return SWITCH_STATUS_SUCCESS if all is well
\brief record a file from the session to a file
\param session the session to record from
\param fh file handle to use
\param file the path to the file
\param args arguements to pass for callbacks etc
\param limit max limit to record for (0 for infinite)
\return SWITCH_STATUS_SUCCESS if all is well
\brief record a file from the session to a file
\param session the session to record from
\param fh file handle to use
\param file the path to the file
\param args arguements to pass for callbacks etc
\param limit max limit to record for (0 for infinite)
\param vars vars to add to RECORD_START and RECORD_STOP automatically prefixed with Recording-Variable-
\return SWITCH_STATUS_SUCCESS if all is well
\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
\brief Signal the session to broadcast audio in the future
\param runtime when (in epoch time) to run the broadcast
\param uuid the uuid of the session to broadcast on
\param path the path data of the broadcast “/path/to/file.wav []” or “speak:||”
\param flags flags to send to the request (SMF_ECHO_BRIDGED to send the broadcast to both sides of the call)
\return the id of the task
\brief Hangup an existing session in the future
\param runtime the time (int epoch seconds) to transfer the call
\param uuid the uuid of the session to hangup
\param cause the hanup cause code
\param bleg hangup up the B-Leg if possible
\return the id of the task
\brief Transfer an existing session to another location in the future
\param runtime the time (int epoch seconds) to transfer the call
\param uuid the uuid of the session to transfer
\param extension the new extension
\param dialplan the new dialplan (OPTIONAL, may be NULL)
\param context the new context (OPTIONAL, may be NULL)
\return the id of the task
\brief Transfer an existing session to another location
\param session the session to transfer
\param extension the new extension
\param dialplan the new dialplan (OPTIONAL, may be NULL)
\param context the new context (OPTIONAL, may be NULL)
\brief Bridge Signalling from one session to another
\param session one session
\param peer_session the other session
\return SWITCH_STATUS_SUCCESS if all is well
\brief Wait for time to pass for a specified number of milliseconds
\param session the session to wait for.
\param ms the number of milliseconds
\param sync synchronize the channel’s audio before waiting
\param args arguements to pass for callbacks etc
\return SWITCH_STATUS_SUCCESS if the channel is still up
\brief Speak given text with given tts engine
\param session the session to speak on
\param tts_name the desired tts module
\param voice_name the desired voice
\param text the text to speak
\param args arguements to pass for callbacks etc
\return SWITCH_STATUS_SUCCESS if all is well
\brief Stop displacing a session
\param session the session
\param file file name from the switch_ivr_displace_session call
\return SWITCH_STATUS_SUCCESS if all is well
\brief Stop Recording a session
\param session the session to stop recording
\param file the path to the file
\return SWITCH_STATUS_SUCCESS if all is well
\brief Start looking for TONES
\param session the session to start looking
\param key the name of the tone.
\param tone_spec comma sep list of tone freqs
\param flags one or both of ‘r’ and ‘w’
\param timeout timeout
\param app optional application to execute when tone is found
\param data optional data for appliaction
\return SWITCH_STATUS_SUCCESS if all is well
\brief Transfer variables from one session to another
\param sessa the original session
\param sessb the new session
\param var the name of the variable to transfer (NULL for all)
\return SWITCH_STATUS_SUCCESS if all is well
\brief Signal the session with a protocol specific unhold message.
\param uuid the uuid of the session to hold
\return SWITCH_STATUS_SUCCESS if all is well
\brief Bridge two existing sessions
\param originator_uuid the uuid of the originator
\param originatee_uuid the uuid of the originator
\remark Any custom state handlers on both channels will be deleted
\return SWITCH_STATUS_SUCCESS if all is well
\brief Execute a registered JSON API command
\param json the name of the JSON API command to execute
\param arg the optional arguement to the command
\param session an optional session
\param stream stream for output
\return the status returned by the API call
\brief Increment resource.
\param backend to use
\param realm
\param resource
\param max - 0 means no limit, just count
\param interval - 0 means no interval
\return true/false - true ok, false over limit
\brief build a dynamic module object and register it (for use in double embeded modules)
\param filename the name of the modules source file
\param switch_module_load the function to call when the module is loaded
\param switch_module_runtime a function requested to be started in it’s own thread once loaded
\param switch_module_shutdown the function to call when the system is shutdown
\param runtime start the runtime thread or not
\return the resulting status
\note only use this function if you are making a module that in turn gateways module loading to another technology
\brief Enumerates a list of all modules discovered in a directory
\param the directory to look for modules in
\param memory pool
\param callback function to call for each module found
\param user data argument to pass to the callback function
\return the resulting status
\brief Enumerates a list of all currently loaded modules
\param callback function to call for each module found
\param user data argument to pass to the callback function
\return the resulting status
\brief Retrieve the chat application interface by it’s registered name
\param name the name of the chat application
\return the desired chat application interface
\brief Retrieve the list of loaded codecs into an array
\param array the array to populate
\param arraylen the max size in elements of the array
\return the number of elements added to the array
\brief Retrieve the list of loaded codecs into an array based on another array showing the sorted order
\param array the array to populate
\param arraylen the max size in elements of the array
\param prefs the array of preferred codec names
\param preflen the size in elements of the prefs
\return the number of elements added to the array
\note this function only considers codecs that are listed in the “prefs” array and ignores the rest.
\brief Retrieve the directory interface by it’s registered name
\param name the name of the directory interface
\return the desired directory interface
\brief Retrieve the management interface by it’s registered name
\param relative_oid the relative oid of the management interface
\return the desired management interface
\brief Load a module
\param dir the directory where the module resides
\param fname the file name of the module
\param runtime option to start the runtime thread if it exists
\param err pointer to error message
\return the status
\brief Unoad a module
\param dir the directory where the module resides
\param fname the file name of the module
\param err pointer to error message
\return the status
\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
Set the Multicast Time to Live (ttl) for a multicast transmission.
@param sock The socket to set the multicast ttl
@param ttl Time to live to Assign. 0-255, default=1
@remark If the TTL is 0, packets will only be seen by sockets on the local machine,
and only when multicast loopback is enabled.
Join a Multicast Group
@param sock The socket to join a multicast group
@param join The address of the multicast group to join
@param iface Address of the interface to use. If NULL is passed, the
default multicast interface will be used. (OS Dependent)
@param source Source Address to accept transmissions from (non-NULL
implies Source-Specific Multicast)
\brief Load a module
\param module_interface a pointer to a pointer to aim at your module’s local interface
\param filename the path to the module’s dll or so file
\return SWITCH_STATUS_SUCCESS on a successful load
This routine is a variant of the “sprintf()” from the
standard C library. The resulting string is written into memory
obtained from malloc() so that there is never a possiblity of buffer
overflow. This routine also implement some additional formatting
options that are useful for constructing SQL statements.
Create and initialize a mutex that can be used to synchronize threads.
@param lock the memory address where the newly created mutex will be
stored.
@param flags Or’ed value of:
Acquire the lock for the given mutex. If the mutex is already locked,
the current thread will be put to sleep until the lock becomes available.
@param lock the mutex on which to acquire the lock.
Attempt to acquire the lock for the given mutex. If the mutex has already
been acquired, the call returns immediately with APR_EBUSY. Note: it
is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine
if the return value was APR_EBUSY, for portability reasons.
@param lock the mutex on which to attempt the lock acquiring.
\brief return the event id that matches a given event name
\param name the name of the event
\param type the event id to return
\return SWITCH_STATUS_SUCCESS if there was a match
\brief Maps a port through the NAT Traversal System
\param port Internal port to map
\param proto Protocol
\param external_port [out] Mapped external port
\param sticky make the mapping permanent
\brief Initilize the rest of the NAT Traversal System
\note nat_init is called prior to some other modules being loaded.
This method allows us to init the rest of the NAT system.
\brief Execute the sql query and issue a callback for each row returned
\param file the file from which this function is called
\param func the function from which this function is called
\param line the line from which this function is called
\param handle the ODBC handle
\param sql the sql string to execute
\param callback the callback function to execute
\param pdata the state data passed on each callback invocation
\return SWITCH_STATUS_SUCCESS if the operation was successful
\note none
\brief Play a sound and gather digits with the number of retries specified if the user doesn’t give digits in the set time
\param session the current session to play sound to and collect digits
\param min_digits the fewest digits allowed for the response to be valid
\param max_digits the max number of digits to accept
\param max_tries number of times to replay the sound and capture digits
\param timeout time to wait for input (this is per iteration, so total possible time = max_tries * (timeout + audio playback length)
\param valid_terminators for input that can include # or * (useful for variable length prompts)
\param audio_file file to play
\param bad_input_audio_file file to play if the input from the user was invalid
\param var_name variable name to put results in
\param digit_buffer variable digits captured will be put back into (empty if capture failed)
\param digit_buffer_length length of the buffer for digits (should be the same or larger than max_digits)
\param digits_regex the qualifying regex
\return switch status, used to note status of channel (will still return success if digit capture failed)
\note to test for digit capture failure look for \0 in the first position of the buffer
Poll the sockets in the poll structure
@param aprset The poll structure we will be using.
@param numsock The number of sockets we are polling
@param nsds The number of sockets signalled.
@param timeout The amount of time in microseconds to wait. This is
a maximum, not a minimum. If a socket is signalled, we
will wake up before this time. A negative number means
wait until a socket is signalled.
@remark The number of sockets signalled is returned in the third argument.
This is a blocking call, and it will not return until either a
socket has been signalled, or the timeout has expired.
Add a socket or file descriptor to a pollset
@param pollset The pollset to which to add the descriptor
@param descriptor The descriptor to add
@remark If you set client_data in the descriptor, that value
will be returned in the client_data field whenever this
descriptor is signalled in fspr_pollset_poll().
@remark If the pollset has been created with APR_POLLSET_THREADSAFE
and thread T1 is blocked in a call to fspr_pollset_poll() for
this same pollset that is being modified via fspr_pollset_add()
in thread T2, the currently executing fspr_pollset_poll() call in
T1 will either: (1) automatically include the newly added descriptor
in the set of descriptors it is watching or (2) return immediately
with APR_EINTR. Option (1) is recommended, but option (2) is
allowed for implementations where option (1) is impossible
or impractical.
Setup a pollset object
@param pollset The pointer in which to return the newly created object
@param size The maximum number of descriptors that this pollset can hold
@param pool The pool from which to allocate the pollset
@param flags Optional flags to modify the operation of the pollset.
Block for activity on the descriptor(s) in a pollset
@param pollset The pollset to use
@param timeout Timeout in microseconds
@param num Number of signalled descriptors (output parameter)
@param descriptors Array of signalled descriptors (output parameter)
Remove a descriptor from a pollset
@param pollset The pollset from which to remove the descriptor
@param descriptor The descriptor to remove
@remark If the pollset has been created with APR_POLLSET_THREADSAFE
and thread T1 is blocked in a call to fspr_pollset_poll() for
this same pollset that is being modified via fspr_pollset_remove()
in thread T2, the currently executing fspr_pollset_poll() call in
T1 will either: (1) automatically exclude the newly added descriptor
in the set of descriptors it is watching or (2) return immediately
with APR_EINTR. Option (1) is recommended, but option (2) is
allowed for implementations where option (1) is impossible
or impractical.
Clear all memory in the pool and run all the cleanups. This also destroys all
subpools.
@param pool The pool to clear
@remark This does not actually free the memory, it just allows the pool
to re-use this memory for the next allocation.
@see fspr_pool_destroy()
\brief Function to evaluate an expression against a string
\param target The string to find a match in
\param expression The regular expression to run against the string
\return Boolean if a match was found or not
\brief Function to evaluate an expression against a string
\param target The string to find a match in
\param expression The regular expression to run against the string
\param partial_match If non-zero returns SUCCESS if the target is a partial match, on successful return, this is set to non-zero if the match was partial and zero if it was a full match
\return Boolean if a match was found or not
\brief Prepare a new resampler handle
\param new_resampler NULL pointer to aim at the new handle
\param from_rate the rate to transfer from in hz
\param to_rate the rate to transfer to in hz
\param quality the quality desired
\return SWITCH_STATUS_SUCCESS if the handle was created
\brief Resample one float buffer into another using specifications of a given handle
\param resampler the resample handle
\param src the source data
\param srclen the length of the source data
\return the used size of dst
switch_rfc822_date formats dates in the RFC822
format in an efficient manner. It is a fixed length
format which requires the indicated amount of storage,
including the trailing NUL terminator.
@param date_str String to write to.
@param t the time to convert
\brief Return the RFC2833 character based on an event id
\param event the event id to convert
\return the character represented by the event or null for an invalid event
\brief Read RTCP data from a given RTP session without copying
\param rtp_session the RTP session to read from
\param frame an RTCP frame to populate with information
\return the number of bytes read
\brief Acvite a jitter buffer on an RTP session
\param rtp_session the rtp session
\param queue_frames the number of frames to delay
\return SWITCH_STATUS_SUCCESS
\brief create a new RTP session handle
\param new_rtp_session a poiter to aim at the new session
\param payload the IANA payload number
\param samples_per_interval the default samples_per_interval
\param ms_per_packet time in microseconds per packet
\param flags flags to control behaviour
\param timer_name timer interface to use
\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
\brief Retrieve DTMF digits from a given RTP session
\param rtp_session RTP session to retrieve digits from
\param dtmf the dtmf
\return number of bytes read into the buffer
\brief Enable VAD on an RTP Session
\param rtp_session the RTP session
\param session the core session associated with the RTP session
\param codec the codec the channel is currenty using
\param flags flags for control
\return SWITCH_STAUTS_SUCCESS on success
\brief Get the default payload number for a given RTP session
\param rtp_session the RTP session to get the payload number from
\return the default payload of the RTP session
\brief Get the default samples per interval for a given RTP session
\param rtp_session the RTP session to get the samples per interval from
\return the default samples per interval of the RTP session
\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
\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
\brief prepare a new RTP session handle and fully initilize it
\param rx_host the local address
\param rx_port the local port
\param tx_host the remote address
\param tx_port the remote port
\param payload the IANA payload number
\param samples_per_interval the default samples_per_interval
\param ms_per_packet time in microseconds per packet
\param flags flags to control behaviour
\param timer_name timer interface to use
\param err a pointer to resolve error messages
\param pool a memory pool to use for the session
\param bundle_port port used by bundled stream locally, for video thread this is the port where it will forward audio (internal bundle port on which audio is listening), and for audio this is the port where it will send RTP (external bundle port where video is listening)
\return the new RTP session or NULL on failure
\brief Queue RFC2833 DTMF data into an RTP Session
\param rtp_session the rtp session to use
\param dtmf the dtmf digits to queue
\return SWITCH_STATUS_SUCCESS on success
\brief Queue RFC2833 DTMF data into an RTP Session
\param rtp_session the rtp session to use
\param dtmf the dtmf digits to queue
\return SWITCH_STATUS_SUCCESS on success
\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 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
\brief Set the default payload number for a given RTP session
\param rtp_session the RTP session to set the payload number on
\param payload the new default payload number
\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
\brief Assign a local address to the RTP session
\param rtp_session an RTP session to assign the local address to
\param host the ip or fqhn of the local address
\param port the local port
\param change_adv_addr change the advertised address for doing compare
\param err pointer for error messages
\note this call also binds the RTP session’s socket to the new address
\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
\brief Assign a remote address to the RTP session
\param rtp_session an RTP session to assign the remote address to
\param host the ip or fqhn of the remote address
\param port the remote port
\param err pointer for error messages
\brief Write data to a given RTP session
\param rtp_session the RTP session to write to
\param frame the frame to write
\return the number of bytes written
\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 m set mark bit or not
\param payload the IANA payload number
\param ts then number of bytes to increment the timestamp by
\param flags frame flags
\return the number of bytes written
\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
\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
\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
\brief Schedule a task in the future
\param task_runtime the time in epoch seconds to execute the task.
\param func the callback function to execute when the task is executed.
\param desc an arbitrary description of the task.
\param group a group id tag to link multiple tasks to a single entity.
\param cmd_id an arbitrary index number be used in the callback.
\param cmd_arg user data to be passed to the callback.
\param flags flags to alter behaviour
\return the id of the task
\brief Schedule a task in the future
\param task_runtime the time in epoch seconds to execute the task.
\param func the callback function to execute when the task is executed.
\param desc an arbitrary description of the task.
\param group a group id tag to link multiple tasks to a single entity.
\param cmd_id an arbitrary index number be used in the callback.
\param cmd_arg user data to be passed to the callback.
\param flags flags to alter behaviour
\param task_id pointer to put the id of the task to
\return the id of the task
\brief Separate a string into an array based on a character delimiter
\param buf the string to parse
\param delim the character delimiter
\param array the array to split the values into
\param arraylen the max number of elements in the array
\return the number of elements added to the array
\brief Convert an array of shorts to an array of floats
\param s an array of shorts
\param f an array of floats
\param len the size of the buffers
\return the size of the converted buffer
Create fspr_sockaddr_t from hostname, address family, and port.
@param sa The new fspr_sockaddr_t.
@param hostname The hostname or numeric address string to resolve/parse, or
NULL to build an address that corresponds to 0.0.0.0 or ::
@param family The address family to use, or SWITCH_UNSPEC if the system should
decide.
@param port The port number.
@param flags Special processing flags:
Accept a new connection request
@param new_sock A copy of the socket that is connected to the socket that
made the connection request. This is the socket which should
be used for all future communication.
@param sock The socket we are listening on.
@param pool The pool for the new socket.
Bind the socket to its associated port
@param sock The socket to bind
@param sa The socket address to bind to
@remark This may be where we will find out if there is any other process
using the selected port.
Issue a connection request to a socket either on the same machine
or a different one.
@param sock The socket we wish to use for our side of the connection
@param sa The address of the machine we wish to connect to.
Create a socket.
@param new_sock The new socket that has been set up.
@param family The address family of the socket (e.g., SWITCH_INET).
@param type The type of the socket (e.g., SOCK_STREAM).
@param protocol The protocol of the socket (e.g., SWITCH_PROTO_TCP).
@param pool The pool to use
\brief Create a pollfd out of a socket
\param pollfd the pollfd to create
\param sock the socket to add
\param flags the flags to modify the behaviour
\param client_data custom user data
\param pool the memory pool to use
\return SWITCH_STATUS_SUCCESS when successful
\brief Create a set of file descriptors to poll from a socket
\param poll the polfd to create
\param sock the socket to add
\param flags the flags to modify the behaviour
\param pool the memory pool to use
\return SWITCH_STATUS_SUCCESS when successful
Listen to a bound socket for connections.
@param sock The socket to listen on
@param backlog The number of outstanding connections allowed in the sockets
listen queue. If this value is less than zero, the listen
queue size is set to zero.
Read data from a network.
@param sock The socket to read the data from.
@param buf The buffer to store the data in.
@param len On entry, the number of bytes to receive; on exit, the number
of bytes received.
@remark
@param from The fspr_sockaddr_t to fill in the recipient info
@param sock The socket to use
@param flags The flags to use
@param buf The buffer to use
@param len The length of the available buffer
Send data over a network.
@param sock The socket to send the data over.
@param buf The buffer which contains the data to be sent.
@param len On entry, the number of bytes to send; on exit, the number
of bytes sent.
@remark
@param sock The socket to send from
@param where The fspr_sockaddr_t describing where to send the data
@param flags The flags to use
@param buf The data to send
@param len The length of the data to send
\brief Split a user@domain string as user and domain
\param in the input string
\param user the string to put the user into
\param domain the string to put the domain into
\return 1 if successfull
\note Extended formats protocol:user@domain:port (Example: sip:toto@example.org)
@} /
/* @} /
/*
This routine is a variant of the “sprintf()” from the
standard C library. The resulting string is written into memory
obtained from malloc() so that there is never a possiblity of buffer
overflow. This routine also implement some additional formatting
options that are useful for constructing SQL statements.
Return a human readable string describing the specified error.
@param statcode The error code the get a string for.
@param buf A buffer to hold the error string.
@bufsize Size of the buffer to hold the string.
Portable version of strerror_r(), work around for the incompatible
return type of GNU and XSI variants.
\param[in] errnum Error number
\param[both] buf Buffer for error message
\param[in] buflen Size of message buffer
\return Pointer to message buffer, returning error message or “Unknown error xxx” if none found
formats the exploded time according to the format specified
@param s string to write to
@param retsize The length of the returned string
@param max The maximum length of the string
@param format The format for the time string
@param tm The time to convert
formats the exploded time according to the format specified (does not validate format string)
@param s string to write to
@param retsize The length of the returned string
@param max The maximum length of the string
@param format The format for the time string
@param tm The time to convert
Signals all threads blocking on the given condition variable.
Each thread that was signaled is then scheduled to wake up and acquire
the associated mutex. This will happen in a serialized manner.
@param cond the condition variable on which to produce the broadcast.
Create and initialize a condition variable that can be used to signal
and schedule threads in a single process.
@param cond the memory address where the newly created condition variable
will be stored.
@param pool the pool from which to allocate the mutex.
Signals a single thread, if one exists, that is blocking on the given
condition variable. That thread is then scheduled to wake up and acquire
the associated mutex. Although it is not required, if predictable scheduling
is desired, that mutex must be locked while calling this function.
@param cond the condition variable on which to produce the signal.
Put the active calling thread to sleep until signaled to wake up or
the timeout is reached. Each condition variable must be associated
with a mutex, and that mutex must be locked before calling this
function, or the behavior will be undefined. As the calling thread
is put to sleep, the given mutex will be simultaneously released;
and as this thread wakes up the lock is again simultaneously acquired.
@param cond the condition variable on which to block.
@param mutex the mutex that must be locked upon entering this function,
is released while the thread is asleep, and is again acquired before
returning from this function.
@param timeout The amount of time in microseconds to wait. This is
a maximum, not a minimum. If the condition is signaled, we
will wake up before this time, otherwise the error APR_TIMEUP
is returned.
Put the active calling thread to sleep until signaled to wake up. Each
condition variable must be associated with a mutex, and that mutex must
be locked before calling this function, or the behavior will be
undefined. As the calling thread is put to sleep, the given mutex
will be simultaneously released; and as this thread wakes up the lock
is again simultaneously acquired.
@param cond the condition variable on which to block.
@param mutex the mutex that must be locked upon entering this function,
is released while the thread is asleep, and is again acquired before
returning from this function.
Create a new thread of execution
@param new_thread The newly created thread handle.
@param attr The threadattr to use to determine how to create the thread
@param func The function to start the new thread in
@param data Any data to be passed to the starting function
@param cont The pool to use
Set if newly created threads should be created in detached state.
@param attr The threadattr to affect
@param on Non-zero if detached threads should be created.
Convert time value from human readable format to a numeric fspr_time_t
e.g. elapsed usec since epoch
@param result the resulting imploded time
@param input the input exploded time
Convert time value from human readable format to a numeric fspr_time_t that
always represents GMT
@param result the resulting imploded time
@param input the input exploded time
\brief Quote shell argument
\param string the string to quote (example: a ’ b“’ c)
\return the quoted string (gives: ’a ‘'’ b“‘'’ c’ for unices, “a ’ b ’ c” for MS Windows), should be freed
\brief Quote shell argument, allocating from pool if provided
\param string the string to quote (example: a ’ b“’ c)
\param pool a memory pool to use
\return the quoted string (gives: ’a ‘'’ b“‘'’ c’ for unices, “a ’ b ’ c” for MS Windows), if pool not provided, returned value should be freed
Format a UUID into a string, following the standard format
@param buffer The buffer to place the formatted UUID string into. It must
be at least APR_UUID_FORMATTED_LENGTH + 1 bytes long to hold
the formatted UUID and a null terminator
@param uuid The UUID to format
\brief Adds a child tag. off is the offset of the child tag relative to the start
\ of the parent tag’s character content. Returns the child tag.
\param xml the xml node
\param name the name of the tag
\param off the offset
\return an xml node or NULL
\brief returns the first child tag (one level deeper) with the given name or NULL
\ if not found
\param xml an xml node
\param name the name of the child tag
\return an xml node or NULL
\brief Gets the string representation of an enum
\param enum_options the switch_xml_config_enum_item_t array for this enum
\param value int value to search
\brief Gets the int representation of an enum
\param enum_options the switch_xml_config_enum_item_t array for this enum
\param value string value to search
\brief Parses all the xml elements, following a ruleset defined by an array of switch_xml_config_item_t
\param xml The first element of the list to parse
\param reload true to skip all non-reloadable options
\param instructions instrutions on how to parse the elements
\see switch_xml_config_item_t
\brief Parses all of an event’s elements, following a ruleset defined by an array of switch_xml_config_item_t
\param event The event structure containing the key and values to parse
\param reload true to skip all non-reloadable options
\param instructions instrutions on how to parse the elements
\see switch_xml_config_item_t
\brief Parses a module’s settings
\param reload true to skip all non-reloadable options
\param file the configuration file to look for
\param instructions the instructions
\brief find a child tag in a node called ‘childname’ with an attribute ‘attrname’ which equals ‘value’
\param node the xml node
\param childname the child tag name
\param attrname the attribute name
\param value the value
\return an xml node or NULL
\brief Traverses the switch_xml structure to retrieve a specific subtag. Takes a
\ variable length list of tag names and indexes. The argument list must be
\ terminated by either an index of -1 or an empty string tag name. Example:
\ title = switch_xml_get(library, “shelf”, 0, “book”, 2, “title”, -1);
\ This retrieves the title of the 3rd book on the 1st shelf of library.
\ Returns NULL if not found.
\param xml the xml node
\return an xml node or NULL
\brief Returns the Nth tag with the same name in the same section at the same depth
\ or NULL if not found. An index of 0 returns the tag given.
\param xml the xml node
\param idx the index
\return an xml node or NULL
\brief initilize the core XML backend
\param pool a memory pool to use
\param err a pointer to set error strings
\return SWITCH_STATUS_SUCCESS if successful
\brief locate an xml pointer in the core registry
\param section the section to look in
\param tag_name the type of tag in that section
\param key_name the name of the key
\param key_value the value of the key
\param root a pointer to point at the root node
\param node a pointer to the requested node
\param params optional URL formatted params to pass to external gateways
\return SWITCH_STATUS_SUCCESS if successful root and node will be assigned
\brief open a config in the core registry
\param file_path the name of the config section e.g. modules.conf
\param node a pointer to point to the node if it is found
\param params optional URL formatted params to pass to external gateways
\return the root xml node associated with the current request or NULL
\brief open the Core xml root
\param reload if it’s is already open close it and open it again as soon as permissable (blocking)
\param err a pointer to set error strings
\return the xml root node or NULL
\brief A wrapper for switch_xml_parse_str() that accepts a file descriptor. First
\ attempts to mem map the file. Failing that, reads the file into memory.
\ Returns NULL on failure.
\param fd
\return a formated xml node or NULL
\brief Wrapper for switch_xml_parse_str() that accepts a file stream. Reads the entire
\ stream into memory and then parses it. For xml files, use switch_xml_parse_file()
\ or switch_xml_parse_fd()
\param fp a FILE pointer to parse
\return an xml node or NULL
\brief Given a string of xml data and its length, parses it and creates an switch_xml
\ structure. For efficiency, modifies the data by adding null terminators
\ and decoding ampersand sequences. If you don’t want this, copy the data and
\ pass in the copy. Returns NULL on failure.
\param s a string
\param len the length of the string
\return a formated xml node or NULL
\brief Parses a string into a switch_xml_t, ensuring the memory will be freed with switch_xml_free
\param s The string to parse
\param dup true if you want the string to be strdup()’d automatically
\return the switch_xml_t or NULL if an error occured
\brief returns a NULL terminated array of processing instructions for the given
\ target
\param xml the xml node
\param target the instructions
\return the array
\brief retrieve the core XML root node
\return the xml root node
\note this will cause a readlock on the root until it’s released with \see switch_xml_free
\brief Sets the given tag attribute or adds a new attribute if not found. A value
\ of NULL will remove the specified attribute.
\param xml the xml node
\param name the attribute name
\param value the attribute value
\return the tag given
\brief Wrapper for switch_xml_set_attr() that strdup()s name/value. Value cannot be NULL
\param xml the xml node
\param name the attribute name
\param value the attribute value
\return an xml node or NULL
\brief Wrapper for switch_xml_set_attr() that strdup()s name/value. Value cannot be NULL
\param xml the xml node
\param name the attribute name
\param value the attribute value
\return an xml node or NULL
\brief bind a search function to an external gateway
\param function the search function to bind
\param sections a bitmask of sections you wil service
\param user_data a pointer to private data to be used during the callback
\return SWITCH_STATUS_SUCCESS if successful
\note gateway functions will be executed in the order they were binded until a success is found else the root registry will be used
\brief wrapper for switch_xml_set_txt() that strdup()s txt
\ sets the character content for the given tag and returns the tag
\param xml the xml node
\param txt the text
\return an xml node or NULL
\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)
@defgroup switch_sqlite_top Brought To You By SQLite
@ingroup FREESWITCH
@{
/
/**
@defgroup switch_core_db Database Routines
@ingroup switch_sqlite_top
@{
/
/**
Each open database is represented by an instance of the
following opaque structure.
\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.