astxx::agi Class Reference
#include <astxx/agi.h>
Detailed Description
The agi handling class.This class can be used to interface with asterisk through the Asterisk Gateway Interface. It is designed to be instantated only once per run. Because of the design of the AGI interface, this is all that is necessary. The Singleton Patteren is used to ensure that all instances of the agi class are the same instance.
To use the agi class you simply call astxx::agi::instance(), which will return a refrence to the agi interface, creating an instance of the class if necessary.
Do not embed new lines (\n) in any of your AGI commands. This will cause unexpected behavior. One exception to this rule is the agi::verbose command which has been specially written in astxx to parse new lines out into multiple verbose commands (one per line).
Asterisk will send SIGHUP when the controlling channel is hungup. This signal is caught by agi::sighup_handler() and an internal flag is set. You can test for hangups using the agi::test_hangup() function which throws agi::hangup_signal (derrived from agi::hangup) if there was a hangup.
- Note:
- All agi commands may throw agi::hangup and or agi::application_error.
- See also:
- agi Commands
Definition at line 70 of file agi.h.
Public Member Functions | |
| agi & | answer () |
| Answer the channel. | |
| std::map< std::string, std::string >::const_iterator | begin () const |
| Get the beginning of the env std::map. | |
| int | channel_status (const std::string &channel="") const |
| Get the status of a channel. | |
| void | clear () |
| Clear any sig hup or sig pipe flags. | |
| char | control_stream_file (const std::string &filename, const std::string &escape_digits="", int skip_time=control_stream_file_skip_time, char fastforward=0, char rewind=0, char pause=0) const |
| Play a file on the channel with the option to control playback. | |
| agi & | database_del (const std::string &family, const std::string &key) |
| Delete a database key. | |
| agi & | database_deltree (const std::string &family, const std::string &keytree="") |
| Delete a database family or keytree. | |
| std::string | database_get (const std::string &family, const std::string &key) const |
| Get a value out of the Asterisk database. | |
| agi & | database_put (const std::string &family, const std::string &key, const std::string &value) |
| Put a value in the database. | |
| std::map< std::string, std::string >::const_iterator | end () const |
| Get the end of the env std::map. | |
| int | exec (const std::string &app, const std::string &options="") const |
| Execute a given application. | |
| result | execute (const std::string &command) const |
| execute the specfied command and return the agi::result | |
| std::string | get_data (const std::string &file, int timeout=0, int max_digits=get_data_max_digits) const |
| Stream a file and receive DTMF data. | |
| std::string | get_full_variable (const std::string &variable, const std::string &channel="") const |
| More robust version of astxx::agi::get_variable. | |
| char | get_option (const std::string &file, const std::string &escape_digits="", int timeout=0) const |
| Stream a file and read a digit. | |
| std::string | get_variable (const std::string &variable) const |
| Get the value of a channel variable. | |
| agi & | hangup (const std::string &channel="") |
| Hangup a channel. | |
| agi & | noop () |
| Does nothing. | |
| std::string | operator[] (const std::string &key) |
| Get an asterisk environment variable. | |
| std::string | quote (char item) const |
| Return a quoted string. | |
| std::string | quote (const std::string item) const |
| Return a quoted string. | |
| char | receive_char (int timeout=0) const |
| Receive a character from channels that support it. | |
| std::string | receive_text (int timeout=0) const |
| Receive text from channels that support it. | |
| char | record_file (const std::string &filename, const std::string &format, const std::string &escape_digits="", int timeout=-1, int silence=0, bool beep=true, long offset=0) const |
| Record audio and store it in the given location. | |
| char | say_alpha (int number, const std::string &escape_digits="") const |
| Say a given character string. | |
| char | say_alpha (const std::string &alphanum, const std::string &escape_digits="") const |
| Say a given character string. | |
| char | say_date (time_t date, const std::string &escape_digits="") const |
| Say a given date. | |
| char | say_datetime (time_t date, const std::string &escape_digits="", const std::string &format="", const std::string &timezone="") const |
| Say a given date in the format specfied. | |
| char | say_digits (int digits, const std::string &escape_digits="") const |
| Say a given digit string as indiviual digits. | |
| char | say_number (int number, const std::string &escape_digits="") const |
| Say a given number. | |
| char | say_phonetic (const std::string &characters, const std::string &escape_digits="") const |
| Say a given character string with phonetics (alpha, bravo, charile. | |
| char | say_time (time_t time, const std::string &escape_digits="") const |
| Says a given time. | |
| agi & | send_image (const std::string &image) |
| Send an image to channels that support it. | |
| agi & | send_text (const std::string &text) |
| Send text to channels that support it. | |
| agi & | set_autohangup (int delay) |
| Hangup a channel after the specified time has passed. | |
| agi & | set_callerid (const std::string &cid) |
| Set the callerid for the current channel. | |
| agi & | set_callerid (int number) |
| Set the callerid for the current channel. | |
| agi & | set_context (const std::string &context) |
| Set the channel context. | |
| agi & | set_extension (const std::string &extension) |
| Set the channel extension. | |
| agi & | set_extension (int extension) |
| Set the channel extension. | |
| agi & | set_music (bool enable, const std::string &music_class="") |
| Enable/Disable music on hold generator. | |
| agi & | set_priority (const std::string &priority) |
| Set the priority of the channel. | |
| agi & | set_priority (int priority) |
| Set the priority of the channel. | |
| agi & | set_variable (const std::string &variable, const std::string &value) |
| Set a given variable. | |
| char | stream_file (const std::string &filename, const std::string &escape_digits="", long offset=0) const |
| Plays a given file on the audio channel. | |
| agi & | tdd_mode (const std::string &mode) |
| Change the TDD mode of the channel. | |
| agi & | tdd_mode (bool enable) |
| Toggles TDD mode on or off (for the deaf). | |
| void | test_hangup () const |
| Check for a hangup. | |
| agi & | verbose (const std::string &text, int level=1) |
| Log a message to the Asterisk verbose log. | |
| char | wait_for_digit (long timeout=-1) const |
| Wait for a digit to be pressed. | |
Static Public Member Functions | |
| static agi & | instance () |
| Get the instance of the agi class. | |
Public Attributes | |
|
std::map< std::string, std::string > | env |
| The agi environment. | |
Protected Member Functions | |
| agi (const agi &) | |
| Hidden copy constructor. | |
| agi () | |
| This constructor reads the agi environment variables. | |
| result | get_result () const |
| Get the result of the last agi command, from Asterisk. | |
| agi & | operator= (const agi &) |
| Hidden copy constructor. | |
| void | read_env () |
| Read the agi environment variables. | |
| void | send_command (const std::string &command) const |
| Send an agi command to Asterisk. | |
Classes | |
| class | application_error |
| An application encountered an error during execution. More... | |
| class | database_error |
| There was a error with the Asterisk database. More... | |
| class | error |
| Generic agi Exception. More... | |
| class | hangup |
| A channel was hungup while executing an agi command. More... | |
| class | hangup_result |
| "hangup" was recieved as the result of a command. More... | |
| class | hangup_signal |
| A channel was hungup while executing an agi command. More... | |
| class | invalid_command |
| An invalid or unknown command was executed. More... | |
| class | io_error |
| There was an error communicating with the asterisk server. More... | |
| class | no_channel |
| The requested channel could not be found. More... | |
| struct | result |
| Holds the result of an AGI command. More... | |
| class | timeout |
| The current command timed out. More... | |
| class | unknown_error |
| Asterisk has reported an error we do not understand. More... | |
| class | usage_error |
| An application has reported a usage error. More... | |
Constructor & Destructor Documentation
| agi::agi | ( | ) | [protected] |
This constructor reads the agi environment variables.
Because this class adheres to the Singleton patteren, it cannot be instantiated directly and must be implicitly created through the agi::instance() function. This constructor handles getting and storing the agi environment, and setting up the SIGHUP signal handler.
- Exceptions:
-
agi::error thrown if there is an error during construction
Definition at line 61 of file agi.cc.
References read_env().
Member Function Documentation
| map< string, string >::const_iterator agi::begin | ( | ) | const |
| map< string, string >::const_iterator agi::end | ( | ) | const |
Get the end of the env std::map.
- Returns:
- a const_iterator to the end of the std::map
Definition at line 129 of file agi.cc.
References env.
Referenced by get_result().
| agi::result agi::execute | ( | const std::string & | command | ) | const |
execute the specfied command and return the agi::result
Send an agi command and return the result.
- Parameters:
-
command the command to be sent
- Returns:
- the result of the command as an agi::result struct
- Exceptions:
-
throws agi::hangup if the channel is hungup during execution throws agi::application_error if an application returns -1 (applications may return -1 on hangup)
Definition at line 154 of file agi.cc.
References astxx::agi::result::data, get_result(), astxx::agi::result::result, send_command(), and test_hangup().
Referenced by answer(), channel_status(), control_stream_file(), database_del(), database_deltree(), database_get(), database_put(), exec(), get_data(), get_full_variable(), get_option(), get_variable(), hangup(), noop(), receive_char(), receive_text(), record_file(), say_alpha(), say_date(), say_datetime(), say_digits(), say_number(), say_phonetic(), say_time(), send_image(), send_text(), set_autohangup(), set_callerid(), set_context(), set_extension(), set_music(), set_priority(), set_variable(), stream_file(), tdd_mode(), verbose(), and wait_for_digit().
| agi::result agi::get_result | ( | ) | const [protected] |
Get the result of the last agi command, from Asterisk.
- Returns:
- the result as an astxx::agi::result struct
Definition at line 181 of file agi.cc.
References astxx::agi::result::code, astxx::agi::result::data, end(), astxx::agi::result::endpos, astxx::agi::result::message, astxx::agi::result::result, and astxx::agi::result::result_string.
Referenced by execute().
| agi & agi::instance | ( | ) | [static] |
Get the instance of the agi class.
The instance function returns the single instance of the agi class. This function is probably the most non thread safe part of the agi class.
- Returns:
- the instance of the agi class
- Exceptions:
-
agi::error thrown from the class constructor if construction fails
| string agi::operator[] | ( | const std::string & | key | ) |
Get an asterisk environment variable.
The [] operator when applied to an instance of the agi class will return the environment variable that matches the string passed.
- Todo:
- Currently this function will return an empty string if the key passed is not found in the environment. It may be better to throw an exception to avoid confusion.
- Parameters:
-
key the variable to retrieve
- Returns:
- the value of the environment variable
Definition at line 113 of file agi.cc.
References env.
| void agi::send_command | ( | const std::string & | command | ) | const [protected] |
| void agi::test_hangup | ( | ) | const |
Check for a hangup.
This function tests if we have recieved a hangup from Asterisk in the form of a SIGHUP signal. If we have it throws an agi::hangup_signal exception.
- Exceptions:
-
agi::hangup_signal thrown if we have recieved a hangup
Definition at line 289 of file agi.cc.
Referenced by execute().
The documentation for this class was generated from the following files:
