NAME

OSDial - Perl extension for interfacing with OSDial

SYNOPSIS

  use strict;
  use OSDial;

  my $osdial = OSDial->new('DB'=>1);

  # Database example
  while ( my $rec = $osdial->sql_query("SELECT * FROM servers;") ) {
    print $rec->{server_ip} . ": " . $rec->{server_name} . "\n";

    # Secondary connection and query
    while ( my $rec2 = $osdial->sql_query( sprintf('SELECT * FROM osdial_log WHERE server_ip=%s;', $rec->quote($rec->{server_ip}) ) ) {
      print "    " . $rec2->{lead_id} . ": " . $rec2->{call_date} . ": " . $rec2->{status} . "\n";
    }
    
  }

  # Asterisk::AGI example
  $osdial->AGI('myscript.pl');
  $osdial->AGI->verbose("OSDial Rocks",1);
  $osdial->AGI->hangup();

DESCRIPTION

This module is inteded to provided quick and easy access to common functions in OSDial. The module will read existing configuration files, connect to the OSDial database, and interface with Asterisk as needed.

CONSTRUCTOR

new() - create a new OSDial object.

Creates a new OSDial object. new optionally takes arguments in the form of key value pairs.

Examples:

   $osdial = OSDial->new( DB => 1);

   $osdial = new OSDial( DB => 1);

   $osdial = OSDial->new( VARDB_server   => '127.0.0.1',
                          VARDB_database => 'osdial',
                          VARDB_user     => 'osdial',
                          VARDB_pass     => 'osdial1234' );

Contructor Arguments and Defaults

   DB                               => '0'
   
   PATHconf                         => '/etc/osdial.conf'
   PATHdocs                         => '/usr/share/doc/osdial-2.2.9.083'
   PATHhome                         => '/opt/osdial/bin'
   PATHlogs                         => '/var/log/osdial'
   PATHagi                          => '/var/lib/asterisk/agi-bin'
   PATHweb                          => '/opt/osdial/html'
   PATHsounds                       => '/var/lib/asterisk/sounds'
   PATHmonitor                      => '/var/spool/asterisk/VDmonitor'
   PATHDONEmonitor                  => '/var/spool/asterisk/VDmonitor'
   PATHarchive_home                 => '/opt/osdial/recordings'
   PATHarchive_unmixed              => 'processing/unmixed'
   PATHarchive_mixed                => 'processing/mixed'
   PATHarchive_sorted               => 'completed'
   PATHarchive_backup               => '/opt/osdial/backups/recordings'
   
   VARserver_ip                     => '127.0.0.1'
   VARactive_keepalives             => 'X'
   
   VARDB_server                     => '127.0.0.1'
   VARDB_database                   => 'osdial'
   VARDB_user                       => 'osdial'
   VARDB_pass                       => 'osdial1234'
   VARDB_port                       => '3306'
   
   VARfastagi_log_min_servers       => '3'
   VARfastagi_log_max_servers       => '16'
   VARfastagi_log_min_spare_servers => '2'
   VARfastagi_log_max_spare_servers => '8'
   VARfastagi_log_max_requests      => '1000'
   VARfastagi_log_checkfordead      => '30'
   VARfastagi_log_checkforwait      => '60'
   
   VARFTP_host                      => '127.0.0.1'
   VARFTP_user                      => 'osdial'
   VARFTP_pass                      => 'osdialftp1234'
   VARFTP_port                      => '21'
   VARFTP_dir                       => 'recordings/processing/unmixed'
   VARHTTP_path                     => '/'
   
   VARREPORT_host                   => '127.0.0.1'
   VARREPORT_user                   => 'osdial'
   VARREPORT_pass                   => 'osdialftp1234'
   VARREPORT_port                   => '21'
   VARREPORT_dir                    => 'reports'
   
   VARcps                           => '9'
   VARadapt_min_level               => '1.5'
   VARadapt_overlimit_mod           => '20'
   VARflush_hopper_each_run         => '0'
   VARflush_hopper_manual           => '1'

METHODS - AGI

This method overloads the Asterisk::AGI module, parsing AGI variable into the OSDial object and allowing direct access to AGI functions.

The AGI() method must first be called with the name of the current script or instance. After the initial call, AGI() will return the AGI object for execution of AGI events.

AGI( [script_name] ) - starts the AGI component.

When called the first time, it will initialize the AGI obeject.

   $osdial = new OSDial;
   $osdial->AGI('agi-script_name.agi');

Subsequent calls to AGI() will return a reference to the AGI object. This reference can be used to call Asterisk::AGI functions or be assigned to another variable to be called.

   $osdial->AGI->verbose("OSDial Rocks",1);
   $osdial->AGI->hangup();
   
   $AGI = $osdial->AGI();
   $AGI->verbose("OSDial Rocks",1);
   $AGI->hangup();

agi_output($string, [$extended_info]) - AGI logging method.

This method outputs a given $string to the AGI log file if AGI logging is enabled for the server as defined by VARserver_ip. The file is stored in the directory specified by the OSDial object variable PATHlogs in a file called agiout.YYYY-MM-DD. The $extended_info variable is an optional boolean flag which instructs the routine to log the channel, extension, priority, type, and account_code AGI channel variables;

   $osdial->agi_output("An AGI event occurred");
   
   $osdial->agi_output("Event occurred with additional channel variables",1);

METHODS - SQL

These methods provide quick and easy access to the OSDial Database by way of its configuration files.

Every method has a definable $DBhandle scalar variable. This variable is a text representation of the handle being accessed. If not given, this always defaults to "A". This is very useful for running nested queries, as you only need to call the nested statement with a different $DBhandle. Every SQL method will first check to see if the $DBhandle exists and a connection to that database has already been established. If a $DBhandle, has not yet been opened, sql_connect will automatically be called.

   # Create a connection to DBhandle "A".
   $osdial->sql_connect();
   # Run given query against DBhandle "A".
   $row = $osdial->sql_query("SELECT * FROM servers LIMIT 1;");
   print $row->{"server_ip"} . "\n";
   
   # Create a connection to DBhandle "SVR".
   $osdial->sql_connect("SVR");
   # Run given query against DBhandle "SVR".
   while ($row = $osdial->sql_query("SELECT * FROM servers;","SVR")) {
       # Run given query against DBhandle "OSDL", automatically connecting to handle.
       $subrow = $osdial->sql_query("SELECT * FROM osdial_log WHERE server_ip='" . $row->{"server_ip"} . "';","OSDL");
       print $subrow->{"call_date"} . "\n";
   }

sql_connect( [$DBhandle], [$DBname, [$DBserver]. [$DBport], [$DBuser], [$DBpass]] ) - connect to SQL server.

Connects to SQL server using sting label in $DBhandle, if not given default to "A". If $DBname is given, sql_connect will allow you to override the respective default server values for this connection.

   $osdial->sql_connect("B");

sql_disconnect( [$DBhandle] ) - disconnect from SQL server.

Disconnects from the database connection referenced by $DBhandle. If $DBhandle is not given, it defaults to "A".

   $osdial->sql_disconnect("B");

sql_query( $query, [$DBhandle] ) - Issues an SQL query.

The sql_query() method allows you to execute SQL statments. The result is a HASHREF containing the key value pairs of a queried row. This method will retain its iterative position within the running current running query and will output each row on subsequent calls. If it is run with a new and different query, while a previous query is currently buffered, it will flush the buffer and start the new query. Just be mindful to start sub-queries with a different $DBhandle to avoid clearing the current buffer of the parent query.

   # Called in a single iteration, yeilds row #1.
   $row = $osdial->sql_query('SELECT * FROM servers;');
   
   # Called again with same query, yeilds row #2.
   $row = $osdial->sql_query('SELECT * FROM servers;');
   
   # Called again with diffent query, flushes buffer and yeilds row #1.
   $row = $osdial->sql_query('SELECT * FROM server_stats;');
   
   # Called in while loop, will cycle through all rows returned by query.
   while ($row = $osdial->sql_query('SELECT * FROM servers;')) {
      print $row->{"server_ip"} . "\n";
   }

If an INSERT, UPDATE, or DELETE query is given, options will automatically be passed to sql_execute().

If $DBhandle does not reference a current active database connection, sql_connect() will automatically by called.

sql_execute( $query, [$DBhandle] ) - disconnect from SQL server.

Execute the given statement in $query.

   # Example Insert.
   $osdial->sql_execute("INSERT INTO table SET row='value';");
   
   # Example Update.
   $osdial->sql_execute("UPDATE table SET row='value' WHERE key='id';");

   # Example Delete.
   $osdial->sql_execute("DELETE FROM table WHERE key='id';");

If an SELECT or SHOW query is given, options will automatically be passed to sql_query().

If $DBhandle does not reference a current active database connection, sql_connect() will automatically by called.

sql_quote( $string ) - returns properly escaped string in single-quotes.

Returns escaped strings for inclusion in queries. Returned string is already enclosed within single-quotes.

   $test = $osdial->sql_quote("Here's a test.");
   # Result: $test = "'Here\'s a test.'";

Aliases for sql_quote( $string ) include quote( $string ) and mres( $string ).

sql_max_packet( ) - returns maximum packet allowed.

Returns the maximum allowed packet size that the SQL server will except.

   $max_packet = $osdial->sql_max_packet();

METHODS - OSDial

General methods for OSDial that help with everyday functions.

debug( $level, $module, $sprintf_string, @sprintf_params ) - Send debug output to STDERR.

If $level matches the current Debug Level set by DB, then output a debug statement to STDERR. The name of the calling module should be specified in $module. The outputted string is taken in the same format as sprintf() in the form of $sprintf_string and @sprintf_params.

   $osdial->debug(1,'main', 'The %s function failed!', $var);

event_logger( $logname, $string ) - Send event to logfile.

Sends an event, $string, to the logfile in PATHlogs, named $logfile.YYYY-MM-DD.

   $osdial->event_logger('eventlog','An event was triggered.');

get_datetime( [$time] )

Returns time() or $time, if given, in the format: YYYY-MM-DD HH:MM:SS

   $osdial->get_datetime();

get_date( $time )

Returns time() or $time, if given, in the format: YYYY-MM-DD

   $osdial->get_date();

media_add_files( $directory, [$pattern], [$update_data] )

All files in $directory are scaned and loaded into the databsae if they do not already exist in it.

The $pattern variable allows for a regex expression to be applied against the filename. The default $patter is .*.

If the file exists in the database and $update_data is true, the data is updated. The default action is to skip files which are already present.

media_add_file( $filepath, [$mimetype], [$description], [$extension], [$update_data] )

This function opens the media file $filepath and splits the binary data into segments which are small enough to be sent to the SQL server without exceeding the max_allowed_packet size.

If $mimetype is not given, it will be guessed using the extension of $filepath.

   g722    => 'audio/G722'
   g729    => 'audio/G729'
   gsm     => 'audio/GSM'
   ogg     => 'audio/ogg'
   ulaw    => 'audio/PCMU'
   alaw    => 'audio/PCMA'
   siren7  => 'audio/siren7'
   siren14 => 'audio/siren14'
   sln     => 'audio/sln'
   sln16   => 'audio/sln-16'
   mp3     => 'audio/mpeg'
   wav     => 'audio/x-wav'

If $description is not given, the filename is stripped off of $filepath and used.

If $extension is not given and the filename is not numeric, it is left blank. If the filename will be used if it is numeric.

If the file exists in the database and $update_data is true, the data is updated. The default action is to skip files which are already present.

media_delete_filedata( $filename ): Removes all entries in the osdial_media_data table associated with $filename.

media_get_filedata( $filename ): Combines all of the entries in the osdial_media_data table associated with $filename and returns the binary data.

media_save_file( $directory, $filename, [$overwrite] ): Export entry matching $filename and save into the given $directory. File is skipped and is not overwitten unless $overwrite is true.

media_save_files( $directory, [$pattern], [$overwrite] ): All files matching the regex $patten are exported and saved into the given $directory. The default $pattern is .*. Files are skipped and not overwitten unless $overwrite is true.

AUTHOR

Lott Caskey, <lottcaskey@gmail.com>

COPYRIGHT

LICENSE

AGPLv3

This file is part of OSDial.

OSDial is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

OSDial 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 Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with OSDial. If not, see http://www.gnu.org/licenses/.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 134:: You forgot a '=back' before '=head2'
Around line 190:: =back without =over

To install OSDial, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OSDial

CPAN shell

perl -MCPAN -e shell
install OSDial

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)