agi.h

Go to the documentation of this file.

/* vim: set et sw=3 tw=0 fo=croqlaw cino=t0:
 *
 * astxx, the Asterisk C++ API and Utility Library.
 * Copyright (C) 2005-2007  Matthew A. Nicholson
 * Copyright (C) 2005-2007  Digium, Inc.
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License version 2.1 as published by the Free Software Foundation.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

#ifndef ASTXX_AGI_H
#define ASTXX_AGI_H

#include <map>
#include <string>
#include <astxx/exception.h>

namespace astxx {

   class agi {
      public: // agi Exceptions

         class error : public astxx::exception {
            public:
               error() throw() : astxx::exception("astxx AGI Exception") { }
               explicit error(const std::string& desc) throw() : astxx::exception(desc) { }
         };

         class unknown_error : public error {
            public:
               explicit unknown_error(int error_code, const std::string& desc) throw() : error(desc), code(error_code) { }

               int error_code() const { return code; }

            private:
               int code;

         };

         class usage_error : public error {
            public:
               explicit usage_error(const std::string& desc) throw() : error(desc) { }
         };

         class invalid_command : public error {
            public:
               invalid_command() throw() : error("Invalid or unknown command.  This could be a bug in astxx, or your Asterisk installation may be too old.") { }
               explicit invalid_command(const std::string& desc) throw() : error(desc) { }

         };

         class io_error : public error {
            public:
               io_error() throw() : error("There was a error communicating with the Asterisk server") { }
               explicit io_error(const std::string& desc) throw() : error(desc) { }

         };

         class application_error : public error {
            public:
               application_error() throw() : error("Error during application execution, possibly a hangup") { }
               explicit application_error(const std::string& desc) throw() : error(desc) { }

         };

         class hangup : public application_error {
            public:
               hangup() throw() : application_error("Channel hungup during execution") { }
               explicit hangup(const std::string& desc) throw() : application_error(desc) { }

         };

         class hangup_signal : public hangup {
            public:
               hangup_signal() throw() : hangup("Received SIGHUP from Asterisk, indicating a hangup") { }
         };

         class hangup_result : public hangup {
            public:
               hangup_result() throw() : hangup("Received \"hangup\" as the result of an AGI command") { }
         };

         class timeout : public application_error {
            public:
               timeout() throw() : application_error("Operation timed out") { }
               explicit timeout(const std::string& desc) throw() : application_error(desc) { }

         };

         class database_error : public application_error {
            public:
               database_error() : application_error("An Asterisk database operation failed") { }
               explicit database_error(const std::string& desc) : application_error(desc) { }

         };

         class no_channel : public application_error {
            public:
               no_channel() throw() : application_error("The requested channel could not be found") { }
               explicit no_channel(const std::string& channel) throw() : application_error("Channel '" + channel + "' was not found"), channel(channel) { }
               virtual ~no_channel() throw () { }

            private:
               std::string channel;

         };

         struct result {
            int code;                   
            std::string message;        
            int result;                 
            std::string result_string;  
            std::string data;            
            long endpos;
         };


      public:
         std::map<std::string, std::string> env;           
         result execute(const std::string& command) const; 
         std::string quote(const std::string item) const { return ("\"" + item + "\""); }  
         std::string quote(char item) const { return ("\"" + (item ? std::string(1, item) : "") + "\""); }  

      protected:
         agi();                         
         agi(const agi&);               
         agi& operator = (const agi&);  
         void read_env();
         void send_command(const std::string& command) const;
         result get_result() const;

      private:
         static volatile bool got_sighup;
         static void handle_sighup(int);
         static volatile bool got_sigpipe;
         static void handle_sigpipe(int);

         static const int control_stream_file_skip_time = 3000; 
         static const int get_data_max_digits = 1024;           

      public:
         static agi& instance();
         std::string operator [] (const std::string& key);
         std::map<std::string, std::string>::const_iterator begin() const;
         std::map<std::string, std::string>::const_iterator end() const;

         void test_hangup() const;
         void clear();

         // agi commands
         agi& answer();
         int channel_status(const std::string& channel = "") const;
         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;
         agi& database_del(const std::string& family, const std::string& key);
         agi& database_deltree(const std::string& family, const std::string& keytree = "");
         std::string database_get(const std::string& family, const std::string& key) const;
         agi& database_put(const std::string& family, const std::string& key, const std::string& value);
         int exec(const std::string& app, const std::string& options = "") const;
         std::string get_data(const std::string& file, int timeout = 0, int max_digits = get_data_max_digits) const;
         std::string get_full_variable(const std::string& variable, const std::string& channel = "") const;
         char get_option(const std::string& file, const std::string& escape_digits = "", int timeout = 0) const;
         std::string get_variable(const std::string& variable) const;
         agi& hangup(const std::string& channel = "");
         agi& noop();
         char receive_char(int timeout = 0) const;
         std::string receive_text(int timeout = 0) const;
         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;
         char say_alpha(const std::string& alphanum, const std::string& escape_digits = "") const;
         char say_alpha(int number, const std::string& escape_digits = "") const;
         char say_date(time_t date, const std::string& escape_digits = "") const;
         char say_datetime(time_t date, const std::string& escape_digits = "", const std::string& format = "", const std::string& timezone = "") const;
         char say_digits(int digits, const std::string& escape_digits = "") const;
         char say_number(int number, const std::string& escape_digits = "") const;
         char say_phonetic(const std::string& characters, const std::string& escape_digits = "") const;
         char say_time(time_t time, const std::string& escape_digits = "") const;
         agi& send_image(const std::string& image);
         agi& send_text(const std::string& text);
         agi& set_autohangup(int delay);
         agi& set_callerid(int number);
         agi& set_callerid(const std::string& cid);
         agi& set_context(const std::string& context);
         agi& set_extension(int extension);
         agi& set_extension(const std::string& extension);
         agi& set_music(bool enable, const std::string& music_class = "");
         agi& set_priority(int priority);
         agi& set_priority(const std::string& priority);
         agi& set_variable(const std::string& variable, const std::string& value);
         char stream_file(const std::string& filename, const std::string& escape_digits = "", long offset = 0) const;
         agi& tdd_mode(bool enable);
         agi& tdd_mode(const std::string& mode);
         agi& verbose(const std::string& text, int level = 1);
         char wait_for_digit(long timeout = -1) const;
   };

}

#endif