Class: AGI

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby-agi/agi.rb,
lib/ruby-agi/command.rb,
lib/ruby-agi/asterisk_variable.rb

Direct Known Subclasses

AsteriskVariable, Command

Instance Method Summary collapse

Constructor Details

#initialize ⇒ AGI

constructor method of class AGI

Parameters

  • none

Returns

  • self



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/ruby-agi/agi.rb', line 43

def initialize
	@@debug				= nil
	@@stdin_semaphore	= nil
	@@stdout_semaphore	= nil
	@@stderr_semaphore	= nil

	begin
		@@env = AsteriskVariable.new if @@env.nil?
	rescue NameError
		@@env = AsteriskVariable.new
	rescue
		raise(AGIError, "Error to initialize @@env in AGI#initialize, please report to [email protected]")
	end

	begin
		@@command = Command.new if @@command.nil?
	rescue NameError
		@@command = Command.new
	rescue
		raise(AGIError, "Error to initialize @@command in AGI#initialize, please report to [email protected]")
	end
end

Instance Method Details

#accountcode ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



426
427
428
 
# File 'lib/ruby-agi/agi.rb', line 426

def accountcode
	return env.accountcode
end

#answer ⇒ Object

Answers channel if not already in answer state.

Parameters

  • none

Returns

  • ReturnStatus object



451
452
453
 
# File 'lib/ruby-agi/agi.rb', line 451

def answer
	return command.answer
end

#callerid ⇒ Object

method to read callerid, Ex. “John Smith” <1234567890> regardless of asterisk version, method callerid would return “Caller Name” <Number>

Parameters

  • none

Returns

  • String : empty string for Unidentified



268
269
270
 
# File 'lib/ruby-agi/agi.rb', line 268

def callerid
	return env.callerid
end

#calleridname ⇒ Object

method to read calleridname, Ex. John Smith

Parameters

  • none

Returns

  • String : empty string for Unidentified



281
282
283
 
# File 'lib/ruby-agi/agi.rb', line 281

def calleridname
	return env.calleridname
end

#calleridnumber ⇒ Object

method to read calleridnumber, Ex. 1234567890

Parameters

  • none

Returns

  • String : empty string for Unidentified



294
295
296
 
# File 'lib/ruby-agi/agi.rb', line 294

def calleridnumber
	return env.calleridnumber
end

#callingani2 ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



318
319
320
 
# File 'lib/ruby-agi/agi.rb', line 318

def callingani2
	return env.callingani2
end

#callingpres ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



306
307
308
 
# File 'lib/ruby-agi/agi.rb', line 306

def callingpres
	return env.callingpres
end

#callingtns ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



342
343
344
 
# File 'lib/ruby-agi/agi.rb', line 342

def callingtns
	return env.callingtns
end

#callington ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



330
331
332
 
# File 'lib/ruby-agi/agi.rb', line 330

def callington
	return env.callington
end

#channel ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



218
219
220
 
# File 'lib/ruby-agi/agi.rb', line 218

def channel
	return env.channel
end

#channel_status(channel = nil) ⇒ Object

Returns the status of the specified channel. If no channel name is given the returns the status of the current channel.

Parameters

  • channel : name of the channel.

Returns

  • ReturnStatus object



477
478
479
 
# File 'lib/ruby-agi/agi.rb', line 477

def channel_status(channel=nil)
	return command.channel_status(channel)
end

#context ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



378
379
380
 
# File 'lib/ruby-agi/agi.rb', line 378

def context
	return env.context
end

#debug=(val) ⇒ Object

<method description>

Parameters

  • val(Boolean)

Returns

  • none



182
183
184
 
# File 'lib/ruby-agi/agi.rb', line 182

def debug=(val)
	@@debug = val
end

#debug? ⇒ Boolean

<method description>

Parameters

  • none

Returns

  • Boolean

Returns:

  • (Boolean) 


194
195
196
 
# File 'lib/ruby-agi/agi.rb', line 194

def debug?
	return @@debug == true
end

#dial(telephone_number = nil, protocol = nil, username = nil, context = nil, timeout = nil, options = nil) ⇒ Object

method to dial out

Parameters

  • telephone_number : telephone_number or extension to dial

  • protocol : protocol to be used to make this call

  • username : username to be used to make this call using the specified protocol

  • context : name of the context to be used for authentication

  • timeout : maximum allowed time in seconds to make this call

  • options : options to be passed in ‘Dial’ command

Returns

  • ReturnStatus object



872
873
874
 
# File 'lib/ruby-agi/agi.rb', line 872

def dial(telephone_number=nil, protocol=nil, username=nil, context=nil, timeout=nil, options=nil)
	return command.dial(telephone_number, protocol, username, context, timeout, options)
end

#dnid ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



354
355
356
 
# File 'lib/ruby-agi/agi.rb', line 354

def dnid
	return env.dnid
end

#enhanced ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



414
415
416
 
# File 'lib/ruby-agi/agi.rb', line 414

def enhanced
	return env.enhanced
end

#exec(asterisk_application, options = nil) ⇒ Object

Executes <application> with given <options>. Applications are the functions you use to create a dial plan in extensions.conf.

Parameters

  • application : Asterisk command of the application

  • options : options to be passed with the asterisk application

Returns

  • ReturnStatus object



492
493
494
 
# File 'lib/ruby-agi/agi.rb', line 492

def exec(asterisk_application, options=nil)
	return command.exec(asterisk_application, options)
end

#extension ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



390
391
392
 
# File 'lib/ruby-agi/agi.rb', line 390

def extension
	return env.extension
end

#get_variable(name) ⇒ Object

method to read a variable

Parameters

  • name : name of the variable to read

Returns

  • ReturnStatus object



522
523
524
 
# File 'lib/ruby-agi/agi.rb', line 522

def get_variable(name)
	return command.get_variable(name)
end

#hangup(channel = nil) ⇒ Object

method to hang up the specified channel. If no channel name is given, hangs up the current channel.

Parameters

  • channel : name of the channel to hang up

Returns

  • ReturnStatus object



535
536
537
 
# File 'lib/ruby-agi/agi.rb', line 535

def hangup(channel=nil)
	return command.hangup(channel)
end

#jump_to(context = nil, extension = nil, priority = nil) ⇒ Object

method to jump in a specified context, extension and priority

Parameters

  • context : name of the context

  • extension : name of the extension

  • priority : name of the priority

Returns

  • none



887
888
889
 
# File 'lib/ruby-agi/agi.rb', line 887

def jump_to(context=nil, extension=nil, priority=nil)
	command.jump_to(context, extension, priority)
end

#language ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



230
231
232
 
# File 'lib/ruby-agi/agi.rb', line 230

def language
	return env.language
end

#noop(msg) ⇒ Object

method that Does nothing !!

Parameters

  • msg : message to pass this method

Returns

  • ReturnStatus object

success: 200 result=0



549
550
551
 
# File 'lib/ruby-agi/agi.rb', line 549

def noop(msg)
	return command.noop(msg)
end

#priority ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



402
403
404
 
# File 'lib/ruby-agi/agi.rb', line 402

def priority
	return env.priority
end

#raw_command(str) ⇒ Object

<method description>

Parameters

  • str(String) : asterisk command in raw format to be executed

Returns

  • ReturnStatus object



438
439
440
 
# File 'lib/ruby-agi/agi.rb', line 438

def raw_command(str)
	return command.raw_command(str)
end

#rdnid ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



366
367
368
 
# File 'lib/ruby-agi/agi.rb', line 366

def rdnid
	return env.rdnid
end

#receive_char(timeout) ⇒ Object

Receives a character of text on a channel, and discards any further characters after the first one waiting. Most channels do not support the reception of text. See Asterisk Text for details.

Parameters

  • timeout : maximum time to wait for input in seconds

    negative or zero is not acceptable

Returns

  • ReturnStatus object



564
565
566
 
# File 'lib/ruby-agi/agi.rb', line 564

def receive_char(timeout)
	return command.receive_char(timeout)
end

#receive_text(timeout) ⇒ Object

Receives a string text on a channel. Most channels do not support the reception of text.

Parameters

  • timeout : time to wait for input in seconds

    negative or zero is not acceptable

Returns

  • ReturnStatus object



579
580
581
 
# File 'lib/ruby-agi/agi.rb', line 579

def receive_text(timeout)
	return command.receive_text(timeout)
end

#record_file(filename, format = 'gsm', escape_digits = nil, timeout = nil, beep = true) ⇒ Object

Record to a file until <escape digits> are received as dtmf.

Parameters

  • filename : location of the file where the audio file will be saved

  • format : specify what kind of file will be recorded.

  • timeout : maximum record time in seconds

    nil, negative or 0 for no timeout.

  • offset : [offset samples] is optional,

    and if provided will seek to the offset without exceeding the end of the file.

  • silence : number of seconds of silence allowed before the function returns

    despite the lack of dtmf digits or reaching timeout.
Silence value must be preceeded by "s=" and is optional.

Returns

  • ReturnStatus object



600
601
602
 
# File 'lib/ruby-agi/agi.rb', line 600

def record_file(filename, format='gsm', escape_digits=nil, timeout=nil, beep=true)
	return command.record_file(filename, format, escape_digits, timeout, beep)
end

#request ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



206
207
208
 
# File 'lib/ruby-agi/agi.rb', line 206

def request
	return env.request
end

#say_digits(digit_string, escape_digits = nil) ⇒ Object

Say a given digit string, returning early if any of the given DTMF digits are received on the channel.

Parameters

  • number : number to announce

  • escape_digit : if digit pressed during playback, will return from announce

Returns

  • ReturnStatus (object)

failure: 200 result=-1 success: 200 result=0 digit pressed: 200 result=<digit> <digit> is the ascii code for the digit pressed.



619
620
621
 
# File 'lib/ruby-agi/agi.rb', line 619

def say_digits(digit_string, escape_digits=nil)
	return command.say_digits(digit_string, escape_digits)
end

#say_number(number, escape_digits = nil) ⇒ Object

Say a given number, returning early if any of the given DTMF digits are received on the channel.

Parameters

  • number : number to announce

  • escape_digit : if pressed, return from program

Returns

  • ReturnStatus object



633
634
635
 
# File 'lib/ruby-agi/agi.rb', line 633

def say_number(number, escape_digits=nil)
	return command.say_number(number, escape_digits)
end

#say_phonetic(string, escape_digits = nil) ⇒ Object

Say a given character string with phonetics, returning early if any of the given DTMF digits are received on the channel.

Parameters

  • string : character string to announce

  • escape_digit : digit to be pressed to escape from program

Returns

  • ReturnStatus (object)



647
648
649
 
# File 'lib/ruby-agi/agi.rb', line 647

def say_phonetic(string, escape_digits=nil)
	return command.say_phonetic(string, escape_digits)
end

#say_time(time = Time.now.to_i, escape_digits = '#') ⇒ Object

Say a given time, returning early if any of the given DTMF digits are received on the channel.

Parameters

  • time : number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC).

  • escape_digits : digit to be pressed to escape from the program

Returns

  • ReturnStatus (object)



661
662
663
 
# File 'lib/ruby-agi/agi.rb', line 661

def say_time(time=Time.now.to_i, escape_digits='#')
	return command.say_time(time, escape_digits)
end

#semaphore ⇒ Object 



162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/ruby-agi/agi.rb', line 162

def semaphore
	if block_given?
		stderr_semaphore.synchronize do 
			stdout_semaphore.synchronize do 
				stdin_semaphore.synchronize do 
					yield
				end
			end
		end
	end
end

#send_image(image) ⇒ Object

Sends the given image on a channel. Most channels do not support the transmission of images. Image names should not include extensions.

Parameters

  • image : location of image

Returns

  • ReturnStatus (object)



676
677
678
 
# File 'lib/ruby-agi/agi.rb', line 676

def send_image(image)
	return command.send_image(image)
end

#send_text(text) ⇒ Object

Sends the given text on a channel. Most channels do not support the transmission of text. Text consisting of greater than one word should be placed in quotes since the command only accepts a single argument.

Parameters

  • text : text to be send

Returns

  • ReturnStatus (object)



691
692
693
 
# File 'lib/ruby-agi/agi.rb', line 691

def send_text(text)
	return command.send_text(text)
end

#set_auto_hangup(val) ⇒ Object

<method description>

Parameters

  • val(Integer) : time in secconds

Returns

  • ReturnStatus object



463
464
465
 
# File 'lib/ruby-agi/agi.rb', line 463

def set_auto_hangup(val)
	return command.set_auto_hangup(val)
end

#set_caller_id(number) ⇒ Object

Changes the callerid of the current channel.

Parameters

  • number : number to be set a callerid

Returns

  • ReturnStatus (object)



704
705
706
 
# File 'lib/ruby-agi/agi.rb', line 704

def set_caller_id(number)
	return command.set_caller_id(number)
end

#set_context(context) ⇒ Object

Sets the context for continuation upon exiting the application.

Parameters

  • context : name of the context

Returns

  • ReturnStatus object



717
718
719
 
# File 'lib/ruby-agi/agi.rb', line 717

def set_context(context)
	return command.set_context(context)
end

#set_extension(extension) ⇒ Object

Changes the extension for continuation upon exiting the application.

Parameters

  • extension: name or number of extension to be set

Returns

  • ReturnStatus object



730
731
732
 
# File 'lib/ruby-agi/agi.rb', line 730

def set_extension(extension)
	return command.set_extension(extension)
end

#set_music(mode = true, moh_class = 'default') ⇒ Object

Enables/Disables the music on hold generator.

Parameters

  • mode : on or off

  • moh_class : name of the music on hold class 

    'default' for not provided or nil

Returns

  • ReturnStatus object



757
758
759
 
# File 'lib/ruby-agi/agi.rb', line 757

def set_music(mode=true, moh_class='default')
	return command.set_music(mode, moh_class)
end

#set_priority(priority) ⇒ Object

Changes the priority for continuation upon exiting the application.

Parameters

  • priority : number of priority

Returns

  • ReturnStatus object



742
743
744
 
# File 'lib/ruby-agi/agi.rb', line 742

def set_priority(priority)
	return command.set_priority(priority)
end

#set_variable(name, value) ⇒ Object

These variables live in the channel Asterisk creates when you pickup a phone and as such they are both local and temporary. Variables created in one channel can not be accessed by another channel. When you hang up the phone, the channel is deleted and any variables in that channel are deleted as well.

Parameters

  • variablename : name of the variable

  • value : value to be set for the variable

Returns

  • ReturnStatus object



776
777
778
 
# File 'lib/ruby-agi/agi.rb', line 776

def set_variable(name, value)
	return command.set_variable(name, value)
end

#stream_file(filename, escape_digits = '#') ⇒ Object

Send the given file, allowing playback to be interrupted by the given digits, if any. Use double quotes for the digits if you wish none to be permitted. If sample offset is provided then the audio will seek to sample offset before play starts. Remember, the file extension must not be included in the filename.

Parameters

  • filename : location of the file to be played

  • escape_digit: digit to be pressed to escape from playback

Returns

  • ReturnStatus object



794
795
796
 
# File 'lib/ruby-agi/agi.rb', line 794

def stream_file(filename, escape_digits='#')
	return command.stream_file(filename, escape_digits)
end

#tdd_mode(settings = true) ⇒ Object

Enable/Disable TDD transmission/reception on a channel. This function is currently (01July2005) only supported on Zap channels. As of 02July2005, this function never returns 0 (Not Capable). If it fails for any reason, -1 (Failure) will be returned, otherwise 1 (Success) will be returned. The capability for returning 0 if the channel is not capable of TDD MODE is a future plan.

Parameters

  • mode : mode of the tdd to be set

    set tdd on if non-zero or 'true' specified

Returns

  • ReturnStatus object



813
814
815
 
# File 'lib/ruby-agi/agi.rb', line 813

def tdd_mode(settings=true)
	return command.tdd_mode(settings)
end

#type ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



242
243
244
 
# File 'lib/ruby-agi/agi.rb', line 242

def type
	return env.type
end

#uniqueid ⇒ Object

<method description>

Parameters

  • none

Returns

  • String



254
255
256
 
# File 'lib/ruby-agi/agi.rb', line 254

def uniqueid
	return env.uniqueid
end

#verbose(message, level = 3) ⇒ Object

Sends <message> to the console via verbose message system. The Asterisk verbosity system works as follows. The Asterisk user gets to set the desired verbosity at startup time or later using the console ‘set verbose’ command. Messages are displayed on the console if their verbose level is less than or equal to desired verbosity set by the user. More important messages should have a low verbose level; less important messages should have a high verbose level.

Parameters

  • message : message to be send as log

  • level : verbose level to be set

    [level] is the the verbose level (1-4)
If you specify a verbose level less than 1 or greater than 4, the verbosity is 1.
The default verbosity seems to be 0 (in 1.0.8),
and supplying a 0 (zero) verbosity does work:
the message will be displayed regardless of the console verbosity setting.

Returns

  • ReturnStatus object



839
840
841
 
# File 'lib/ruby-agi/agi.rb', line 839

def verbose(message, level=3)
	return command.verbose(message, level)
end

#wait_for_digit(timeout = nil) ⇒ Object

Waits up to <timeout> milliseconds for channel to receive a DTMF digit.

Parameters

  • timeout : maximum allow waiting time in seconds to get input

    nil, zero or negative would be considered as infinite wait time

Returns

  • ReturnStatus object



854
855
856
 
# File 'lib/ruby-agi/agi.rb', line 854

def wait_for_digit(timeout=nil)
	return command.wait_for_digit(timeout)
end

#wait_for_digits(filename, timeout = nil, max_digit = nil) ⇒ Object

method to get digit(s) pressing ‘#’ will always terminate the input process

Parameters

  • filename : audio to be played before get as input

  • timeout : maximum allowed time in second(s) to receive each digit

    wait for ever if timeout is nil or negative or zero

  • max_digit: maximum number of digits to get as input

    wait for unlimited number of digits if max_digit is nil or negative or zero

Returns

  • ReturnStatus object



509
510
511
 
# File 'lib/ruby-agi/agi.rb', line 509

def wait_for_digits(filename, timeout=nil, max_digit=nil)
	return command.wait_for_digits(filename, timeout, max_digit)
end