org.asteriskjava.manager.event.DtmfEvent Maven / Gradle / Ivy
Show all versions of asterisk-java Show documentation
/*
* Copyright 2004-2006 Stefan Reuter
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package org.asteriskjava.manager.event;
/**
* A DtmfEvent is triggered each time a DTMF digit is sent or received on a
* channel.
* To support variable-length DTMF Asterisk (since 1.4.0) interally uses two different frames
* for DTMF releated events (AST_FRAME_DTMF_BEGIN and AST_FRAME_DTMF_END).
* Before 1.4.0 Asterisk only used one frame (AST_FRAME_DTMF) which is now an alias for
* AST_FRAME_DTMF_END.
* Many other systems and devices (like mobile phone providers) do not support variable-length DTMF.
* In these cases you will only see AST_FRAME_DTMF_END frames in Asterisk.
* When building DTMF aware applications you should not rely on AST_FRAME_DTMF_BEGIN.
* Generally it is safe to just ignore them and only react on AST_FRAME_DTMF_END frames.
* To check whether an DtmfEvent represents an AST_FRAME_DTMF_BEGIN or
* AST_FRAME_DTMF_END frame use the {@link #isBegin()} and {@link #isEnd()} methods.
*
* You can find more information on how Asterisk handles DTMF in the
* DTMF article at voip-info.org
* It is implemented in main/channel.c.
* Available since Asterisk 1.6
*
* @author srt
* @version $Id$
* @since 1.0.0
*/
public class DtmfEvent extends ManagerEvent
{
/**
* Serializable version identifier.
*/
static final long serialVersionUID = 0L;
public static final String DIRECTION_RECEIVED = "Received";
public static final String DIRECTION_SENT = "Sent";
private String channel;
private String uniqueId;
private String digit;
private String direction;
private Boolean begin;
private Boolean end;
/**
* Creates a new DtmfEvent.
*
* @param source
*/
public DtmfEvent(Object source)
{
super(source);
}
/**
* Returns the name of the channel the DTMF digit was sent or received on.
* The channel name is of the form "Zap/<channel number>".
*
* @return the channel name.
*/
public String getChannel()
{
return channel;
}
/**
* Sets the name of the channel.
*
* @param channel the channel name.
*/
public void setChannel(String channel)
{
this.channel = channel;
}
/**
* Returns the unique id of the the channel the DTMF digit was sent or received on.
*
* @return the unique id of the channel.
*/
public String getUniqueId()
{
return uniqueId;
}
/**
* Sets the unique id of the the channel.
*
* @param uniqueId the unique id of the the channel.
*/
public void setUniqueId(String uniqueId)
{
this.uniqueId = uniqueId;
}
/**
* Returns the DTMF digit that was sent or received.
*
* @return the DTMF digit that was sent or received.
*/
public String getDigit()
{
return digit;
}
/**
* Sets the DTMF digit that was sent or received.
*
* @param digit the DTMF digit that was sent or received.
*/
public void setDigit(String digit)
{
this.digit = digit;
}
/**
* Returns whether the DTMF digit was sent or received.
* Possible values are:
*
* - Received
* - Sent
*
*
* @return "Reveived" if the DTMF was received (sent from the device to Asterisk) or "Sent" if the DTMF
* digit was sent (sent from Asterisk to the device).
* @see #DIRECTION_RECEIVED
* @see #DIRECTION_SENT
*/
public String getDirection()
{
return direction;
}
/**
* Sets whether the DTMF digit was sent or received.
*
* @param direction "Received" or "Sent".
*/
public void setDirection(String direction)
{
this.direction = direction;
}
/**
* Returns whether this event represents an AST_FRAME_DTMF_BEGIN frame.
* Gerally your application will want to ignore begin events. You will only need
* them if you want to make use of the duration a DTMF key was pressed.
* Note that there will be DTMF end events without a corresponding begin event
* as not all systems (including Asterisk prior to 1.4.0) support variable-length
* DTMF.
*
* @return true if this is a DTMF begin event (key pressed),
* false otherwise.
*/
public Boolean isBegin()
{
return begin != null && begin;
}
/**
* Sets whether this event represents an AST_FRAME_DTMF_BEGIN frame.
*
* @param begin true if this is a DTMF begin event (key pressed),
* false otherwise.
*/
public void setBegin(Boolean begin)
{
this.begin = begin;
}
/**
* Returns whether this event represents an AST_FRAME_DTMF_END frame.
* DTMF information received from systems that do not support variable-length
* DTMF you will only see DTMF end events.
*
* @return true if this is a DTMF end event (key released),
* false otherwise.
*/
public boolean isEnd()
{
return end != null && end;
}
/**
* Sets whether this event represents an AST_FRAME_DTMF_END frame.
*
* @param end true if this is a DTMF end event (key released),
* false otherwise.
*/
public void setEnd(Boolean end)
{
this.end = end;
}
/**
* Returns whether the DTMF digit was received by Asterisk (sent from the device to Asterisk).
*
* @return true if the DTMF digit was received by Asterisk,
* false otherwise.
* @see #getDirection()
*/
public boolean isReceived()
{
return direction != null && DIRECTION_RECEIVED.equalsIgnoreCase(direction);
}
/**
* Returns whether the DTMF digit was sent from Asterisk to the device.
*
* @return true if the DTMF digit was sent from Asterisk to the device,
* false otherwise.
* @see #getDirection()
*/
public boolean isSent()
{
return direction != null && DIRECTION_SENT.equalsIgnoreCase(direction);
}
}