asterisk agi 编程函数解析收藏.doc

asterisk agi 编程函数解析收藏 一下内容转自网络。 Introduction The AGI facility allows you to launch scripts, written in just about any language, from an Asterisk dial plan. Communication between your script and Asterisk is via standard input and standard output.拨号方案中，可以采用各种语言很方便的通过AGI接口编写实施脚本。脚本和Asterisk之间通过标准的输入输出进行交互。 Starting your script Each item in an extension is of the form: exten = extension-number,priority,application,argumentsTo launch an AGI script the application is agi and the argument is the filename of your script. The script:执行AGI脚本时，Application应用就是agi，参数是脚本的文件名，同时脚本需要满足以下条件 must be executable必须可执行，chomd 755 must be located in /var/lib/asterisk/agi-bin必须放置在指定目录 must be specified complete with an extension必须指定完整分机信息 For example to run a Python script named test.py then a suitable extension item would be: exten = 1,2,agi,test.pyWhen your script runs, you get a message saying so on the asterisk console provided you have your verbosity level set to 3 or higher. If your script isnt found (you mis-typed the name) you will get a message sayingfailed to execute . no such file or directory.If your script isnt executable (you forgot to give it execute permission) you will get a message sayingfailed to execute . permission denied.脚本执行时，可以从控制台上得到不同基本的详细信息，例如，文件不能被执行，或者找不到文件等等。In any case, dont pay too much attention to the console message sayingagi script test.py completed returning 0.This simply indicated that executing (or attempting to execute) the script is done; it does NOT imply that the script executed successfully.无论如何，不要在意控制台上输入的返回0，这仅仅表示脚本执行了，并不代表脚本执行成功。Your script can issue messages to the Asterisk console by sending them to standard error. At least in the initial stages of developing an agi script it isnt a Bad Idea to have the script issue messages along the line ofHi, Im starting nowandTerminating normallyjust so you know your script ran and completed successfully.通过向Asterisk控制台信息输出，可以得到AGI脚本的执行信息，至少在开发初期中，控制台信息输出是个好办法。You can also use the agi VERBOSE command(documented below)to send messages to the console with the added advantage that you can suppress or enable such messages depending on the verbosity setting.通过agi VERBOSE命令，可以将信息发送到asterisk控制台上，并且而通过verbosity设置可以关闭开启这个功能。 Passing arguments to your AGI script传递参数到AGI脚本 Yes Virginia you can pass arguments to your AGI script. You do so by following the name of your script with a vertical bar then the text you want to pass in. Extending the above example, to pass in yada as an argument we get:在脚本名称后紧跟竖线和需要传送的文本，就可以把需要的参数传入脚本 exten = 1,2,agi,test.py|yadaAGI scripts *always* receive two arguments. The first argument is the full path to the script itself. The second argument is the stuff passed in from the exten line. Its that second argument we are concerned with here. A few things to note about the second argument:AGI脚本总是接收2种参数，1是脚本的完整路径，2是拨号方案中Exten传递的参数，需要关注的就是第2中参数，有几点注意： If no argument is given on the exten line or if the argument given is empty, then the argument received is an empty string.如果exten语句种没有给定参数，或者参数值为空，那么接收到的参数为空字符串 The argument received consists of everything on the line following the vertical bar up until a vertical bar, a semi-colon or a comma. That means the argument may contain spaces.接收的参数为紧跟在竖线后面的一行数据，到竖线、分号、逗号结束，这意味着参数可以包含很多间隔隔开。 Quotes, single or double, are simply taken as part of the argument; they have no special effect.单引号，双引号作为参数的以部分，没有特殊效果 By the time you get the argument any trailing spaces have been deleted but leading spaces are not deleted.得到参数时，会删除后面的空格，不会删除前面的空格 Communicating with Asterisk In theory communicating with Asterisk is wonderfully simple:与Asterisk通信是非常简单的 You write to standard output to send a command to Asterisk.通过标准的输出，发送命令到Asterisk You read from standard input to get the reply from Asterisk.通过标准的输入，从Asterisk接收信息 A few things to note: At script startup time Asterisk sends various pieces of information to your script and you should read these items, via standard input, before doing much else. Each item is sent on a line terminated with a newline and the end of the list is indicated by an empty line. The list of items received will look something like this:当脚本执行时，Asterisk会向脚本发送各种的信息，可以在做其他事情之前通过标准输入获取这些信息，每项数据都是一行，发送完毕Asterisk会发送一个空行，表示结束。内容如下： agi_request: test.py agi_channel: Zap/1-1 agi_language: en agi_type: Zap agi_callerid: agi_dnid: agi_context: default agi_extension: 3 agi_priority: 1If you need the information provided then save it; otherwise feel free to throw it away.如果需要这些数据，就先保存起来，否则不用处理它 Commands sent to Asterisk must be terminated with a newline character.命令发送到Asterisk必须以换行符结束 The result returned by AGI commands is a text string, generally of the form:AGI命令返回文本字符串，如下格式200 Result=although some commands return additional information after the number. If you send Asterisk an invalid command your result will be有时会在number数字后附加一些信息。如果向Asterisk发送了无效的命令，信息如下：510 Invalid or unknown commandAll commands return a result. Commands which dont really need to return a result return 0 as the number. Commands which do need to return a result return various values, as described under the heading Returns below.所有的命令都有返回结果，不需要返回值的将返回数字0，需要返回值的在Returns后显示注解信息。 ANSWER Purpose目的 Answer channel if not already in answer state.如果通道不再应答状态，则应答该通道Returns -1 on channel failure, or 0 if successful. AUTOHANGUP Purpose Cause the channel to automatically hangup at seconds in the future. If is 0 then the autohangup feature is disabled on this channel.在指定时间自动通道挂机，如果时间为0，则该命令在此通道上无效Returns 0Note If the channel is hungup prior to seconds, this setting has no effect. |如果挂机发生在设定事件之前，此设置无效 CHANNEL STATUS Purpose Return the status of the specified channel. If no channel name is specified, return the status of the current channel.返回指定通道的状态，如果通道没有指定，返回当前通道状态Returns -1 There is no channel that matches the given 没有匹配的通道0 Channel is down and available通道没有上线（激活）但有效1 Channel is down, but reserved通道没有上线（激活）但有预留2 Channel is off hook通道在挂机状态3 Digits (or equivalent) have been dialed通道准备拨号4 Line is ringing通道正在振铃5 Remote end is ringing通道远端正在振铃6 Line is up线路激活可用7 Line is busy线路忙Examples CHANNEL STATUSReturn the status of the current channel.CHANNEL STATUS Zap/9-1Return the status of channel Zap/9-1Note The to use is the same as the channel names reported by the Asterisk console show channels command.通道名称与asterisk控制台上 show channels命令显示的通道名字一致 EXEC Purpose Executes the specified Asterisk with given .带参数执行指定的Asterisk 应用Returns Whatever the application returns, or -2 on failure to find the application.返回值-2表示执行错误，没有找到指定应用 GET DATA Purpose Plays the given file and receives DTMF data. This is similar to STREAM FILE, but this command can accept and return many DTMF digits, while STREAM FILE returns immediately after the first DTMF digit is detected.播放指定的语音文件，同时获取DTMF按键信号，与STREAMFILE类似，但此命令能够接收到多个DTMF按键，而STREAMFILE在接收到第一个DTMF按键时立刻返回。Returns If the command ended due to timeout then the result is of the form 200 Result= (timeout)where will be zero or more ASCII characters depending on what the user pressed. If the command ended because the maximum number of digits were entered then the result is of the form 200 Result=and the number of digits returned will be equal to . In either case what you get are actual ASCII characters. For example if the user pressed the one key, the three key and then the star key, the result would be 200 Result=13* (timeout)This differs from other commands with return DTMF as numbers representing ASCII characters. Notes Dont give an extension with the filename.音频文件名称命名不要与分机相同 Asterisk looks for the file to play in /var/lib/asterisk/sounds If the user doesnt press any keys then the message plays, there is milliseconds of silence then the command ends.如果用户没有按键，声音播放完毕后，静默，然后命令结束 The user has the opportunity to press a key at any time during the message or the post-message silence. If the user presses a key while the message is playing, the message stops playing. When the first key is pressed a timer starts counting for milliseconds. Every time the user presses another key the timer is restarted. The command ends when the counter goes to zero or the maximum number of digits is entered, whichever happens first.在播放音频和静默时间内，用户可以按键打断，按键将停止播放音频，超时时间计时从用户第一个按键开始计时，每次按键重新计时，当用户按键复合最大按键数量或超时时间结束，命令结束 If you dont specify a time out then a default timeout of 2000 is used following a pressed digit. If no digits are pressed then 6 seconds of silence follow the message.如果没有定义超时时间，缺省的时间为按键后20秒，如果没有按键，静默6秒后命令结束 If you want to specify then you *must* specify a as well.如果想定义最大按键，最好定义超时时间 If you dont specify then the user can enter as many digits as they want.如果没有定义最大按键，用户可以按任意多的按键 Pressing the # key has the same effect as the timer running out: the command ends and any previously keyed digits are returned. A side effect of this is that there is no way to read a # key using this command.按#号箭的效果相当于超时时间结束，命令终止并返回#号建前面的按键，不能获取到#号建本身 GET VARIABLE Purpose Fetch the value of a variable.取得变量值 Returns Returns 0 if the variable hasnt been set. Returns 1 followed by the value of the variable in parenthesis if it has been set.Example SET VARIABLE Baffy This is a test200 result=1GET VARIABLE Baffy200 result=1 (This is a test) HANGUP Purpose Hangup the specified channel. If no channel name is given, hang up the current channel.Returns If the hangup was successful then the result is200 result=1If no channel matches the you specified then the result is200 result=-1Examples HANGUPHangup the current channel.HANGUP Zap/9-1Hangup channel Zap/9-1Notes The to use is the same as the channel names reported by the Asterisk console show channels command.与控制台上show channels命令显示的通道名字相同With power comes responsibility. Hanging up channels other than your own isnt something that is done routinely. If you are not sure why you are doing so, then dont. RECEIVE CHAR Purpose Receive a character of text from a connected channel. Waits up to milliseconds for a character to arrive, or infinitely if is zero.从链接的通道上获取文本的字符，在超时时间内获取到达的字符，如果超时时间为0，则持续接收。Returns If a character is received, returns the ASCII value of the character as a decimal number. For example if the character A is received the result would be如果一个字符串到达，以10进制数字的方式返回字符的ASCII码，例如A的返回值为：65 result=65 If the channel does not support text reception or if the no character arrives in milliseconds then the result is如果通道不支持文本接收，或者在超时时间内没有字符被接收，结果如下 result=0 (timeout) On error or failure the result is result=-1Note Most channels do not support the reception of text.大多数通道不支持接收文本 RECORD FILE BEEP Purpose Record sound to a file until an acceptable DTMF digit is received or a specified amount of time has passed. Optionally the file BEEP is played before recording begins.录制通道内的声音，生成文件，直到接收到DTMF确认结束按键，或者超时时间结束。在录制声音时，可以选择在录制前提示BEEP滴。Returns The documentation in the code says on hangup the result is -1, however when I tried it the hangup result was源代码文档中描述挂机返回结果为-1，但实际测试结果为0（hangup） result=0 (hangup) If an error occurs then the result is -1. This can happen, for example, if you ask for a non-existent format.如果有错误发生，返回值为-1，例如没有可生成的语音文件格式 If the user presses an acceptable escape digit then the result is a number representing the ASCII digit pressed. For example if recording terminated because the user pressed the 2 key the result is result=50 (dtmf)Example RECORD FILE baffy gsm 123 5000 beepRecord sound in gsm format to file baffy.gsm. Play a beep before starting to record. Stop recording if user presses 1, 2 or 3, after five seconds of recording, or if the user hangs up.Notes Dont put an extension on the filename; the filename extension will be created based on the specified. The file will be created in /var/lib/asterisk/sounds specifies what kind of file will be recorded. GSM is a commonly used format. To find out what other formats are supported start Asterisk with at a verbosity level of at least 2 (-vvc) and look for the messages that appear saying = Registered file format . Most but not all registered formats can be used, for example, Asterisk can read but not write files in mp3 format.录音格式有很多种，GSM是常用的一种，可以在控制台上（高等级模式，至少2个V）查看注册到系统的文件格式，但不是所有的注册文件格式都可以使用，例如Asterisk可以读取但不能生成mp3文件格式 If you dont want ANY digits to terminate recording then specify instead of a digit string. To change the above example so no digits terminate recording useRECORD FILE baffy gsm 5000 beep如果不需要任何按键确认录音结束，使用代替确认按键字符 is the maximum record time in milliseconds, or -1 for no timeout. When this document was written Nov 2002 I was unable to get to work; this command always kept recording until I pressed an escape digit or hung up, as if -1 had been specified for timeout. A patch to correct this has been submitted but has not yet shown up in the CVS tree.超时时间是定义的最大录音时间周期，或者为-1即没有超时时间。在此文档2002年11月编写的时候，超时时间还不能正常工作。 SAY DIGITS Purpose Say the given digit string, returning early if any of the given DTMF escape digits are received on the channel. If no DTMF digits are to be received specifyfor .播音给定的数字字符，当取消按键确认收到则命令结束，如果不需要取消按键，采用带入函数Returns Zero if playback completes without a digit being received, or the ASCII numerical representation of the digit pressed, or -1 on error or hangup.Example SAY DIGITS 123 78#The digits one, two, three are spoken. If the user presses the 7, 8 or # key the speaking stops and the command ends. If the user pressed no keys the result would be200 result=0. If the user pressed the # key then the result would be200 result=35. SAY NUMBER Purpose Say the given number, returning early if any of the given DTMF escape digits are received on the channel. If no DTMF digits are to be accepted specifyfor .播音指定的数值。Returns Zero if playback completes without a digit being received, or the ASCII numerical representation of the digit pressed, or -1 on error or hangup.Example SAY NUMBER 123 789The phrase one hundred twenty three is spoken. If the user presses the 7, 8 or 9 key the speaking stops and the command ends. If the user pressed no keys the result would be200 result=0. If the user pressed the # key then the result would be200 result=35. SEND IMAGE Purpose Send the specified image on a channel. The image name should not should not include the extension.Returns Zero if the image is sent or if the channel does not support image transmission. Returns -1 only on error or hangup.Notes Asterisk looks for the image in/var/lib/asterisk/images Most channels do not support the transmission of images. SEND TEXT Purpose Send the given text to the connected channel.Returns 0 if text is sent or if the channel does not support text transmission. Returns -1 only on error or hangup.Example SEND TEXT Hello worldNote Most channels do not support transmission of text. SET CALLERID Purpose Changes the caller ID of the current channel设置当前通道的主叫号码Returns Always returns200 result=1Example SET CALLERID John SmithNotes This command will let you take liberties with the but the format shown in the example above works well: the name enclosed in double quotes followed immediately by the number inside angle brackets.这条命令可以按照规定格式任意修改主叫号码，格式：名字用双引号后面紧跟角括号里面的数字 If there is no name then you can omit it.如果没有名字，可以省略 If the name contains no spaces you can omit the double quotes around it.如果名字中没有空格，可以省略双引号 The number must follow the name immediately; dont put a space between them.号码必须紧跟名字，而且中间不能有空格 The angle brackets around the number are necessary; if you omit them the number will be considered to be part of the name.数字两边的角括号是必须的，如果省略他，会被认为号码是名字的一部分 SET CONTEXT Purpose Sets the context for continuation upon exiting the application.设置应用结束后的context从而继续流程Returns Always returns200 result=0.Example SET CONTEXT demoNotes Setting the context does NOT automatically reset the extension and the priority; if you want to start at the top of the new context you should set extension and priority yourself.设置context不会自动重设extension和priority，如果想从头开始执行，需要手动设置extension和priority If you specify a non-existent context you receive no error indication (the result returned is still result=0) but you do get a warning message on the Asterisk console.如果设置了不存在的context，没有任何错误提示，在控制台上将不会收到任何警告信息，仍然返回result=0 SET EXTENSION Purpose Set the extension to be used for continuation upon exitin