org.asteriskjava.manager.event.AsyncAgiEvent Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of asterisk-java Show documentation
The free Java library for Asterisk PBX integration.
The newest version!
package org.asteriskjava.manager.event;

import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/**
 * The following sub events are reported:
 * 
 * Start: A channel has started the AGI("agi:async") application and is awaiting Async AGI commands.
 * Exec:  Execution of an AGI command initiated through {@link org.asteriskjava.manager.action.AgiAction}
 * has finished.
 * End:   A channel has left the AGI("agi:async") application.
 * 
 * It is implemented in res/res_agi.c.
 * 

 * Available since Asterisk 1.6
 *
 * @author srt
 * @version $Id$
 * @see org.asteriskjava.manager.action.AgiAction
 * @since 1.0.0
 */
public class AsyncAgiEvent extends ResponseEvent {
    /**
     * Serializable version identifier.
     */
    static final long serialVersionUID = 0L;

    public static final String SUB_EVENT_START = "Start";
    public static final String SUB_EVENT_EXEC = "Exec";
    public static final String SUB_EVENT_END = "End";

    private String channel;
    private String subEvent;
    private String commandId;
    private String result;
    private String env;
    private String uniqueId;

    public String getUniqueId() {
        return uniqueId;
    }

    public void setUniqueId(String uniqueId) {
        this.uniqueId = uniqueId;
    }

    /**
     * Creates a new AsyncAgiEvent.
     *
     * @param source
     */
    public AsyncAgiEvent(Object source) {
        super(source);
    }

    /**
     * Returns the name of the channel this event occurred on.
     *
     * @return the name of the channel this event occurred on.
     */
    public String getChannel() {
        return channel;
    }

    /**
     * Sets the name of the channel this event occurred on.
     *
     * @param channel the name of the channel this event occurred on.
     */
    public void setChannel(String channel) {
        this.channel = channel;
    }

    /**
     * Returns the sub event type. This is either "Start", "Exec" or "End".
     *
     * @return the sub event type.
     */
    public String getSubEvent() {
        return subEvent;
    }

    /**
     * Sets the sub event type.
     *
     * @param subEvent the sub event type.
     */
    public void setSubEvent(String subEvent) {
        this.subEvent = subEvent;
    }

    /**
     * Returns the command id of the corresponding {@link org.asteriskjava.manager.action.AgiAction}.
     * This property is only available for the "Exec" sub event.
     *
     * @return the command id.
     * @see org.asteriskjava.manager.action.AgiAction#setCommandId(String)
     */
    public String getCommandId() {
        return commandId;
    }

    /**
     * Sets the command id.
     *
     * @param commandId the command id.
     */
    public void setCommandId(String commandId) {
        this.commandId = commandId;
    }

    /**
     * Returns the raw result of a command execution in response to the corresponding
     * {@link org.asteriskjava.manager.action.AgiAction}.

     * This property is only available for the "Exec" sub event.

     * The result is URL encoded and ends with a newline ("\n").

     * Example:
     * 
     * 200%20result%3d0
     * 
     *
     * @return the URL encoded result.
     */
    public String getResult() {
        return result;
    }

    /**
     * Decodes the result.
     *
     * @return the decoded result.
     */
    public List decodeResult() {
        return decode(getResult());
    }

    /**
     * Sets the raw result.
     *
     * @param result the URL encoded result.
     */
    public void setResult(String result) {
        this.result = result;
    }

    /**
     * Returns the raw AGI environment similar to the AGI request for FastAGI.
     * This property is only available for the "Start" sub event.

     * The environment is passed in multiple lines (separated by "\n"). Each line is URL encoded
     * and contains a key and a value. The environment ends with two newline characters ("\n\n").

     * Example:
     * 
     * ...
     * agi_channel%3a%20IAX2%2fpbx0-1
     * agi_language%3a%20de
     * agi_type%3a%20IAX2
     * agi_uniqueid%3a%201201838738.19
     * agi_version%3a%201.6.0-beta1
     * ...
     * 
     *
     * @return the URL encoded AGI environment.
     */
    public String getEnv() {
        return env;
    }

    /**
     * Decodes the AGI environment and returns a list of lines.
     *
     * @return The decoded AGI environment or an empty list if the environment is not available (that is
     * if {@link #getEnv()} returns null).
     * @see #getEnv()
     */
    public List decodeEnv() {
        return decode(getEnv());
    }

    private List decode(String s) {
        final List result = new ArrayList<>();

        if (s == null) {
            return result;
        }

        try {
            final String decodedString = URLDecoder.decode(s, "UTF-8");
            result.addAll(Arrays.asList(decodedString.split("\n")));
        } catch (UnsupportedEncodingException e) {
            throw new RuntimeException("This JDK does not support UTF-8 encoding", e);
        }

        return result;
    }

    /**
     * Sets the AGI environment.
     *
     * @param env the URL encoded AGI environment.
     */
    public void setEnv(String env) {
        this.env = env;
    }

    /**
     * Checks is this a start sub event.
     *
     * @return true if this is a "Start" sub event, false otherwise.
     */
    public boolean isStart() {
        return isSubEvent(SUB_EVENT_START);
    }

    /**
     * Checks is this an exec sub event.
     *
     * @return true if this is an "Exec" sub event, false otherwise.
     */
    public boolean isExec() {
        return isSubEvent(SUB_EVENT_EXEC);
    }

    /**
     * Checks is this an end sub event.
     *
     * @return true if this is an "End" sub event, false otherwise.
     */
    public boolean isEnd() {
        return isSubEvent(SUB_EVENT_END);
    }

    protected boolean isSubEvent(String subEvent) {
        return this.subEvent != null && this.subEvent.equalsIgnoreCase(subEvent);
    }
}