cagi.c

asterisk c-agi 提供c 语言接口的例子

// If you don't 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. 
//
// If you don't specify $max_digits 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.
//
// @link http://www.voip-info.org/wiki-get+data
// @param string $filename file to play. Do not include file extension.
// @param integer $timeout milliseconds
// @param integer $max_digits
//
// This differs from other commands with return DTMF as numbers representing ASCII characters.
//
int AGITool_get_data(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *filename, int timeout, int max_digits)
{
	return AGITool_sendcmd(tool, res, "GET DATA %s %d %d\n", filename,timeout,max_digits);
}

//
// Fetch the value of a variable.
//
// Does not work with global variables. Does not work with some variables that are generated by modules.
//
// @link http://www.voip-info.org/wiki-Asterisk+variables
// @param string $variable name
//
int AGITool_get_variable(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *variable)
{
	return AGITool_sendcmd(tool, res, "GET VARIABLE %s\n", variable);
}

//
// Added this to make it easier to get a variable. more self explainatory.
// 
int AGITool_get_variable2(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *variable, char *dest, int len)
{
	int ret=AGITool_sendcmd(tool, res, "GET VARIABLE %s\n", variable);
	strlcpy(dest,res->data,len);
	return ret;
}

//
// Hangup the specified channel. If no channel name is given, hang up the current channel.
//
// With power comes responsibility. Hanging up channels other than your own isn't something
// that is done routinely. If you are not sure why you are doing so, then don't.
//
// Most channels do not support the reception of text.
//
// @param string $channel
//
int AGITool_hangup(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *channel)
{
  return AGITool_sendcmd(tool, res, "HANGUP %s\n", channel);
}

//
// Receive a character of text from a connected channel. Waits up to $timeout milliseconds for
// a character to arrive, or infinitely if $timeout is zero.
//
// @param integer $timeout milliseconds
// res->result is 0 on timeout or not supported, -1 on failure. Otherwise 
// it is the decimal value of the DTMF tone. Use chr() to convert to ASCII.
//
int AGITool_receive_char(AGI_TOOLS *tool, AGI_CMD_RESULT *res, int timeout)
{
	return AGITool_sendcmd(tool, res, "RECEIVE CHAR %d\n", timeout);
}

//
// 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.
//
// @link http://www.voip-info.org/wiki-record+file
// @param string $file to record, without extension, often created in /var/lib/asterisk/sounds
// @param string $format of the file. GSM and WAV are commonly used formats. MP3 is read-only and thus cannot be used.
// @param string $escape_digits
// @param integer $timeout is the maximum record time in milliseconds, or -1 for no timeout.
// @param boolean $beep
// @param integer $silence number of seconds of silence allowed before the function returns despite the 
// lack of dtmf digits or reaching timeout.
// res->result is -1 on error, 0 on hangup, otherwise a decimal value of the 
// DTMF tone. Use chr() to convert to ASCII.
//
int AGITool_record_file(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *file, char *format, char *escape_digits, int timeout, int beep, int silence, int offset)
{
	char buf[255];
	snprintf(buf,sizeof(buf),"RECORD FILE %s %s \"%s\" %d",file,format,escape_digits, timeout);
	if (offset>0) {
		snprintf(&buf[strlen(buf)], sizeof(buf)-strlen(buf)," %d",offset);
	}
	if(beep) {
		snprintf(&buf[strlen(buf)], sizeof(buf)-strlen(buf)," BEEP");
	}
	if(silence>0) {
		snprintf(&buf[strlen(buf)], sizeof(buf)-strlen(buf)," s=%d",silence);
	}
	strcat(buf,"\n");
	return AGITool_sendcmd(tool, res, buf);
}

//
// Say the given digit string, returning early if any of the given DTMF escape digits are received on the channel.
//
// @link http://www.voip-info.org/wiki-say+digits
// @param integer $digits
// @param string $escape_digits
// @res->result is -1 on hangup or error, 0 if playback completes with no 
// digit received, otherwise a decimal value of the DTMF tone.  Use chr() to convert to ASCII.
//
int AGITool_say_digits(AGI_TOOLS *tool, AGI_CMD_RESULT *res,char *digits, char *escape_digits)
{
	return AGITool_sendcmd(tool, res, "SAY DIGITS %s \"%s\"\n", digits, escape_digits);
}

//
// Say the given character string, returning early if any of the given DTMF escape digits are received on the channel.
//
// @param string $text
// @param string $escape_digits
// @res->result is -1 on hangup or error, 0 if playback completes with no 
// digit received, otherwise a decimal value of the DTMF tone.  Use chr() to convert to ASCII.
//
int AGITool_say_phonetic(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *text, char *escape_digits)
{
	return AGITool_sendcmd(tool, res, "SAY PHONETIC %s \"%s\"\n", text, escape_digits);
}

//
// Say the given number, returning early if any of the given DTMF escape digits are received on the channel.
//
// @link http://www.voip-info.org/wiki-say+number
// @param integer number
// @param string escape_digits
// @res->result is -1 on hangup or error, 0 if playback completes with no 
// digit received, otherwise a decimal value of the DTMF tone.  Use chr() to convert to ASCII.
//s
int AGITool_say_number(AGI_TOOLS *tool, AGI_CMD_RESULT *res, int number, char *escape_digits)
{
	return AGITool_sendcmd(tool, res, "SAY NUMBER %d \"%s\"\n", number, escape_digits);
}

//
// Send the specified image on a channel.
//
// Most channels do not support the transmission of images.
//
// @param string $image without extension, often in /var/lib/asterisk/images
// @res->result is -1 on hangup or error, 0 if the image is sent or 
// channel does not support image transmission.
//
int AGITool_send_image(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *image)
{
	return AGITool_sendcmd(tool, res, "SEND IMAGE %s\n", image);
}

//
// Send the given text to the connected channel.
//
// Most channels do not support transmission of text.
//
// @param $text
// @res->result is -1 on hangup or error, 0 if the text is sent or 
// channel does not support text transmission.
//
int AGITool_send_text(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *text)
{
	return AGITool_sendcmd(tool, res, "SEND TEXT \"%s\"\n", text);
}

//
// Changes the caller ID of the current channel
//
// @param string $cid example: "John Smith"<1234567>
// This command will let you take liberties with the <caller ID specification> 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; don't 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.
//
int AGITool_set_callerid(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *cid)
{
	return AGITool_sendcmd(tool, res, "SET CALLERID %s\n", cid);
}

//
// Sets the context for continuation upon exiting the application.
//
// 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. 
//
// If you specify a non-existent context you receive no error indication (['result'] is still 0) but you do get a 
// warning message on the Asterisk console.
//
// @param string $context 
//
int AGITool_set_context(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *context)
{
  return AGITool_sendcmd(tool, res, "SET CONTEXT %s\n", context);
}

//
// Set the extension to be used for continuation upon exiting the application.
//
// Setting the extension does NOT automatically reset the priority. If you want to start with the first priority of the 
// extension you should set the priority yourself. 
//
// If you specify a non-existent extension you receive no error indication (['result'] is still 0) but you do 
// get a warning message on the Asterisk console.
//
// @param string $extension
//
int AGITool_set_extension(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *extension)
{
	return AGITool_sendcmd(tool, res, "SET EXTENSION %s\n", extension);
}

//
// Set the priority to be used for continuation upon exiting the application.
//
// If you specify a non-existent priority you receive no error indication (['result'] is still 0)
// and no warning is issued on the Asterisk console.
//
// @param integer $priority
//
int AGITool_set_priority(AGI_TOOLS *tool, AGI_CMD_RESULT *res, int priority)
{
	return AGITool_sendcmd(tool, res, "SET PRIORITY %d\n", priority);
}

//
// Sets a variable to the specified value. The variables so created can later be used by later using ${<variablename>}
// in the dialplan.
//
// 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.
//
// @param string $variable is case sensitive
// @param string $value
//
int AGITool_set_variable(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *variable, char *value)
{
//  $value = str_replace("\n", '\n', addslashes($value));
	return AGITool_sendcmd(tool, res, "SET VARIABLE %s \"%s\"\n", variable, value);
}

//
// Play the given audio file, allowing playback to be interrupted by a DTMF digit. This command is similar to the GET DATA 
// command but this command returns after the first DTMF digit has been pressed while GET DATA can accumulated any number of 
// digits before returning.
//
// @example examples/ping.php Ping an IP address
//
// @param string $filename without extension, often in /var/lib/asterisk/sounds
// @param string $escape_digits
// @param integer $offset
// @res->result is -1 on hangup or error, 0 if playback completes with no 
// digit received, otherwise a decimal value of the DTMF tone.  Use chr() to convert to ASCII.
//
int AGITool_stream_file(AGI_TOOLS *tool, AGI_CMD_RESULT *res,char *filename, char *escape_digits, int offset)
{
	return AGITool_sendcmd(tool, res, "STREAM FILE %s \"%s\" %d\n", filename, escape_digits, offset);
}

//
// Enable or disable TDD transmission/reception on the current channel.
//
// @param string $setting can be on, off or mate
// @res->result is 1 on sucess, 0 if the channel is not TDD capable.
//
int AGITool_tdd_mode(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *setting)
{
	return AGITool_sendcmd(tool, res, "TDD MODE %s\n", setting);
}

//
// Sends $message to the Asterisk console via the 'verbose' message system.
//
// If the Asterisk verbosity level is $level or greater, send $message to the console.
//
// 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.
//
// @param string $message
// @param integer $level from 1 to 4
//
int AGITool_verbose(AGI_TOOLS *tool, AGI_CMD_RESULT *res,char *message, int level)
{
	return AGITool_sendcmd(tool, res, "VERBOSE \"%s\" %d\n", message, level);
}

//
// Waits up to $timeout milliseconds for channel to receive a DTMF digit
//
// @param integer $timeout in millisecons. Use -1 for the timeout value if you want the call to wait indefinitely.
// @return array, see evaluate for return information. ['result'] is 0 if wait completes with no 
// digit received, otherwise a decimal value of the DTMF tone.  
//
int AGITool_wait_for_digit(AGI_TOOLS *tool, AGI_CMD_RESULT *res, int timeout)
{
	return AGITool_sendcmd(tool, res, "WAIT FOR DIGIT %d\n", timeout);
}

//
// Adds or updates an entry in the Asterisk database for a given family, key, and value.
//
// @param string $family
// @param string $key
// @param string $value
// @res->result is 1 on sucess, 0 otherwise
//
int AGITool_database_put(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *family, char *key, char *value)
{
	return AGITool_sendcmd(tool, res, "DATABASE PUT \"%s\" \"%s\" \"%s\"\n", family, key, value);
}

//
// Retrieves an entry in the Asterisk database for a given family and key.
//
// @param string $family
// @param string $key
// @res->result is 1 on sucess, 0 failure. res->data holds the value
//
int AGITool_database_get(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *family, char *key)
{
	return AGITool_sendcmd(tool, res, "DATABASE GET \"%s\" \"%s\"\n", family, key);
}

//
// Deletes an entry in the Asterisk database for a given family and key.
//
// @param string $family
// @param string $key
// @res->result is 1 on sucess, 0 otherwise.
//
int AGITool_database_del(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *family, char *key)
{
	return AGITool_sendcmd(tool, res, "DATABASE DEL \"%s\" \"%s\"\n", family, key);
}

//
// Deletes a family or specific keytree within a family in the Asterisk database.
//
// @param string $family
// @param string $keytree
// @res->result is 1 on sucess, 0 otherwise.
//
int AGITool_database_deltree(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *family, char *keytree)
{
	if (strlen(keytree)) {
		return AGITool_sendcmd(tool, res, "DATABASE DELTREE \"%s\" \"%s\"", family, keytree);
	} else {
		return AGITool_sendcmd(tool, res, "DATABASE DELTREE \"%s\"", family);
	}
}


//
// Say a given time, returning early if any of the given DTMF escape digits are received on the channel.
//
// @link http://www.voip-info.org/wiki-say+time
// @param integer $time
// @param string $escape_digits
// @res->result is -1 on hangup or error, 0 if playback completes with no 
// digit received, otherwise a decimal value of the DTMF tone.  Use chr() to convert to ASCII.
//
int AGITool_say_time(AGI_TOOLS *tool, AGI_CMD_RESULT *res, int time, char *escape_digits)
{
	return AGITool_sendcmd(tool, res, "SAY TIME %d \"%s\"\n", time, escape_digits);
}

//
// Does nothing
//
int AGITool_noop(AGI_TOOLS *tool, AGI_CMD_RESULT *res, char *msgstr)
{
	char msgbuff[1024];
	sprintf(msgbuff,"NoOp %s",msgstr);
	return AGITool_sendcmd(tool, res, msgbuff);
}

//
// Enable/Disable Music on hold generator
//
// @param boolean $enabled