View Javadoc

1   /*
2    * Copyright  2004-2005 Stefan Reuter
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   *
16   */
17  package net.sf.asterisk.fastagi.reply;
18  
19  import java.util.List;
20  
21  /***
22   * Reply received in response to an AGICommand.<br>
23   * The AGIReply contains information about success or failure of the execution
24   * of an AGICommand and - depending on the command sent - additional information
25   * returned, for example the value of a variable requested by a
26   * GetVariableCommand.
27   * 
28   * @see net.sf.asterisk.fastagi.command.AGICommand
29   * @author srt
30   * @version $Id: AGIReply.java,v 1.14 2005/10/25 22:37:34 srt Exp $
31   */
32  public interface AGIReply
33  {
34      /***
35       * Status code (200) indicating Asterisk successfully processed the
36       * AGICommand.
37       */
38      public static int SC_SUCCESS = 200;
39  
40      /***
41       * Status code (510) indicating Asterisk was unable to process the
42       * AGICommand because there is no command with the given name available.
43       */
44      public static int SC_INVALID_OR_UNKNOWN_COMMAND = 510;
45  
46      /***
47       * Status code (520) indicating Asterisk was unable to process the
48       * AGICommand because the syntax used was not correct. This is most likely
49       * due to missing required parameters or additional parameters sent that are
50       * not understood.<br>
51       * Ensure proper quoting of the parameters when you receive this status
52       * code.
53       */
54      public static int SC_INVALID_COMMAND_SYNTAX = 520;
55  
56      /***
57       * Returns the first line of the raw reply.
58       * 
59       * @return the first line of the raw reply.
60       */
61      String getFirstLine();
62  
63      /***
64       * Returns a List containing the lines of the raw reply.
65       * 
66       * @return a List containing the lines of the raw reply.
67       */
68      List getLines();
69  
70      /***
71       * Returns the return code (the result as int).
72       * 
73       * @return the return code or -1 if the result is not an int.
74       */
75      int getResultCode();
76  
77      /***
78       * Returns the return code as character.
79       * 
80       * @return the return code as character.
81       */
82      char getResultCodeAsChar();
83  
84      /***
85       * Returns the result, that is the part directly following the "result="
86       * string.
87       * 
88       * @return the result.
89       */
90      String getResult();
91  
92      /***
93       * Returns the status code.<br>
94       * Supported status codes are:
95       * <ul>
96       * <li>200 Success
97       * <li>510 Invalid or unknown command
98       * <li>520 Invalid command syntax
99       * </ul>
100      * 
101      * @return the status code.
102      */
103     int getStatus();
104 
105     /***
106      * Returns an additional attribute contained in the reply.<br>
107      * For example the reply to the StreamFileCommand contains an additional
108      * endpos attribute indicating the frame where the playback was stopped.
109      * This can be retrieved by calling getAttribute("endpos") on the
110      * corresponding reply.
111      * 
112      * @param name the name of the attribute to retrieve. The name is case
113      *            insensitive.
114      * @return the value of the attribute or <code>null</code> if it is not
115      *         set.
116      */
117     String getAttribute(String name);
118 
119     /***
120      * Returns the text in parenthesis contained in this reply.<br>
121      * The meaning of this property depends on the command sent. Sometimes it
122      * contains a flag like "timeout" or "hangup" or - in case of the
123      * GetVariableCommand - the value of the variable.
124      * 
125      * @return the text in the parenthesis or <code>null</code> if not set.
126      */
127     String getExtra();
128 
129     /***
130      * Returns the synopsis of the command sent if Asterisk expected a different
131      * syntax (getStatus() == SC_INVALID_COMMAND_SYNTAX).
132      * 
133      * @return the synopsis of the command sent, <code>null</code> if there
134      *         were no syntax errors.
135      */
136     String getSynopsis();
137 
138     /***
139      * Returns the usage of the command sent if Asterisk expected a different
140      * syntax (getStatus() == SC_INVALID_COMMAND_SYNTAX).
141      * 
142      * @return the usage of the command sent, <code>null</code> if there were
143      *         no syntax errors.
144      */
145     String getUsage();
146 
147 }