SDL_Android/SmartDeviceLinkProxyAndroid/src/com/smartdevicelink/proxy/rpc/PerformInteraction.java

   1 package com.smartdevicelink.proxy.rpc;\r
   2 \r
   3 import java.util.Hashtable;\r
   4 import java.util.Vector;\r
   5 \r
   6 import com.smartdevicelink.proxy.RPCRequest;\r
   7 import com.smartdevicelink.proxy.constants.Names;\r
   8 import com.smartdevicelink.proxy.rpc.enums.InteractionMode;\r
   9 import com.smartdevicelink.util.DebugTool;\r
  10 /**\r
  11  * Performs an application-initiated interaction in which the user can select a\r
  12  * {@linkplain Choice} from among the specified Choice Sets. For instance, an\r
  13  * application may use a PerformInteraction to ask a user to say the name of a\r
  14  * song to play. The user's response is only valid if it appears in the\r
  15  * specified Choice Sets and is recognized by SMARTDEVICELINK\r
  16  * <p>\r
  17  * Function Group: Base\r
  18  * <p>\r
  19  * <b>HMILevel needs to be FULL</b>\r
  20  * </p>\r
  21  * \r
  22  * @since SmartDeviceLink 1.0\r
  23  * @see CreateInteractionChoiceSet\r
  24  * @see DeleteInteractionChoiceSet\r
  25  */\r
  26 public class PerformInteraction extends RPCRequest {\r
  27         /**\r
  28          * Constructs a new PerformInteraction object\r
  29          */\r
  30     public PerformInteraction() {\r
  31         super("PerformInteraction");\r
  32     }\r
  33         /**\r
  34          * Constructs a new PerformInteraction object indicated by the Hashtable\r
  35          * parameter\r
  36          * <p>\r
  37          * \r
  38          * @param hash\r
  39          *            The Hashtable to use\r
  40          */    \r
  41     public PerformInteraction(Hashtable hash) {\r
  42         super(hash);\r
  43     }\r
  44         /**\r
  45          * Gets the Text that Displayed when the interaction begins. This text may\r
  46          * be overlaid by the "Listening" prompt during the interaction. Text is\r
  47          * displayed on first line of multiline display, and is centered. If text\r
  48          * does not fit on line, it will be truncated\r
  49          * \r
  50          * @return String -the text displayed when the interaction begins\r
  51          */\r
  52     public String getInitialText() {\r
  53         return (String) parameters.get(Names.initialText);\r
  54     }\r
  55         /**\r
  56          * Sets the Text that Displayed when the interaction begins. This text may\r
  57          * be overlaid by the "Listening" prompt during the interaction. Text is\r
  58          * displayed on first line of multiline display, and is centered. If text\r
  59          * does not fit on line, it will be truncated\r
  60          * \r
  61          * @param initialText\r
  62          *            a String value that Displayed when the interaction begins\r
  63          */    \r
  64     public void setInitialText(String initialText) {\r
  65         if (initialText != null) {\r
  66             parameters.put(Names.initialText, initialText);\r
  67         } else {\r
  68                 parameters.remove(Names.initialText);\r
  69         }\r
  70     }\r
  71         /**\r
  72          * Gets an An array of one or more TTSChunks that, taken together, specify\r
  73          * what is to be spoken to the user at the start of an interaction\r
  74          * \r
  75          * @return Vector<TTSChunk> -a Vector<TTSChunk> value, specify what is to be\r
  76          *         spoken to the user at the start of an interaction\r
  77          */\r
  78     public Vector<TTSChunk> getInitialPrompt() {\r
  79         if (parameters.get(Names.initialPrompt) instanceof Vector<?>) {\r
  80                 Vector<?> list = (Vector<?>)parameters.get(Names.initialPrompt);\r
  81                 if (list != null && list.size() > 0) {\r
  82                     Object obj = list.get(0);\r
  83                     if (obj instanceof TTSChunk) {\r
  84                         return (Vector<TTSChunk>) list;\r
  85                     } else if (obj instanceof Hashtable) {\r
  86                         Vector<TTSChunk> newList = new Vector<TTSChunk>();\r
  87                         for (Object hashObj : list) {\r
  88                             newList.add(new TTSChunk((Hashtable)hashObj));\r
  89                         }\r
  90                         return newList;\r
  91                     }\r
  92                 }\r
  93         }\r
  94         return null;\r
  95     }\r
  96         /**\r
  97          * Sets An array of one or more TTSChunks that, taken together, specify what\r
  98          * is to be spoken to the user at the start of an interaction\r
  99          * \r
 100          * @param initialPrompt\r
 101          *            a Vector<TTSChunk> value, specify what is to be spoken to the\r
 102          *            user at the start of an interaction\r
 103          */    \r
 104     public void setInitialPrompt(Vector<TTSChunk> initialPrompt) {\r
 105         if (initialPrompt != null) {\r
 106             parameters.put(Names.initialPrompt, initialPrompt);\r
 107         } else {\r
 108                 parameters.remove(Names.initialPrompt);\r
 109         }\r
 110     }\r
 111         /**\r
 112          * Gets the Indicates mode that indicate how user selects interaction\r
 113          * choice. User can choose either by voice (VR_ONLY), by visual selection\r
 114          * from the menu (MANUAL_ONLY), or by either mode (BOTH)\r
 115          * \r
 116          * @return InteractionMode -indicate how user selects interaction choice\r
 117          *         (VR_ONLY, MANUAL_ONLY or BOTH)\r
 118          */    \r
 119     public InteractionMode getInteractionMode() {\r
 120         Object obj = parameters.get(Names.interactionMode);\r
 121         if (obj instanceof InteractionMode) {\r
 122             return (InteractionMode) obj;\r
 123         } else if (obj instanceof String) {\r
 124             InteractionMode theCode = null;\r
 125             try {\r
 126                 theCode = InteractionMode.valueForString((String) obj);\r
 127             } catch (Exception e) {\r
 128                 DebugTool.logError("Failed to parse " + getClass().getSimpleName() + "." + Names.interactionMode, e);\r
 129             }\r
 130             return theCode;\r
 131         }\r
 132         return null;\r
 133     }\r
 134         /**\r
 135          * Sets the Indicates mode that indicate how user selects interaction\r
 136          * choice. User can choose either by voice (VR_ONLY), by visual selection\r
 137          * from the menu (MANUAL_ONLY), or by either mode (BOTH)\r
 138          * \r
 139          * @param interactionMode\r
 140          *            indicate how user selects interaction choice (VR_ONLY,\r
 141          *            MANUAL_ONLY or BOTH)\r
 142          */    \r
 143     public void setInteractionMode(InteractionMode interactionMode) {\r
 144         if (interactionMode != null) {\r
 145             parameters.put(Names.interactionMode, interactionMode);\r
 146         } else {\r
 147                 parameters.remove(Names.interactionMode);\r
 148         }\r
 149     }\r
 150         /**\r
 151          * Gets a Vector<Integer> value representing an Array of one or more Choice\r
 152          * Set IDs\r
 153          * \r
 154          * @return Vector<Integer> -a Vector<Integer> value representing an Array of\r
 155          *         one or more Choice Set IDs. User can select any choice from any\r
 156          *         of the specified Choice Sets\r
 157          */    \r
 158     public Vector<Integer> getInteractionChoiceSetIDList() {\r
 159         if(parameters.get(Names.interactionChoiceSetIDList) instanceof Vector<?>){\r
 160                 Vector<?> list = (Vector<?>)parameters.get(Names.interactionChoiceSetIDList);\r
 161                 if(list != null && list.size()>0){\r
 162                         Object obj = list.get(0);\r
 163                         if(obj instanceof Integer){\r
 164                                 return (Vector<Integer>) list;\r
 165                         }\r
 166                 }\r
 167         }\r
 168         return null;\r
 169     }\r
 170         /**\r
 171          * Sets a Vector<Integer> representing an Array of one or more Choice Set\r
 172          * IDs. User can select any choice from any of the specified Choice Sets\r
 173          * \r
 174          * @param interactionChoiceSetIDList\r
 175          *            -a Vector<Integer> representing an Array of one or more Choice\r
 176          *            Set IDs. User can select any choice from any of the specified\r
 177          *            Choice Sets\r
 178          *            <p>\r
 179          *            <b>Notes: </b>Min Value: 0; Max Vlaue: 2000000000\r
 180          */    \r
 181     public void setInteractionChoiceSetIDList(Vector<Integer> interactionChoiceSetIDList) {\r
 182         if (interactionChoiceSetIDList != null) {\r
 183             parameters.put(Names.interactionChoiceSetIDList, interactionChoiceSetIDList);\r
 184         } else {\r
 185                 parameters.remove(Names.interactionChoiceSetIDList);\r
 186         }\r
 187     }\r
 188         /**\r
 189          * Gets a Vector<TTSChunk> which taken together, specify the help phrase to\r
 190          * be spoken when the user says "help" during the VR session\r
 191          * \r
 192          * @return Vector<TTSChunk> -a Vector<TTSChunk> which taken together,\r
 193          *         specify the help phrase to be spoken when the user says "help"\r
 194          *         during the VR session\r
 195          */    \r
 196     public Vector<TTSChunk> getHelpPrompt() {\r
 197         if(parameters.get(Names.helpPrompt) instanceof Vector<?>){\r
 198                 Vector<?> list = (Vector<?>)parameters.get(Names.helpPrompt);\r
 199                 if (list != null && list.size() > 0) {\r
 200                     Object obj = list.get(0);\r
 201                     if (obj instanceof TTSChunk) {\r
 202                         return (Vector<TTSChunk>) list;\r
 203                     } else if (obj instanceof Hashtable) {\r
 204                         Vector<TTSChunk> newList = new Vector<TTSChunk>();\r
 205                         for (Object hashObj : list) {\r
 206                             newList.add(new TTSChunk((Hashtable)hashObj));\r
 207                         }\r
 208                         return newList;\r
 209                     }\r
 210                 }\r
 211         }\r
 212         return null;\r
 213     }\r
 214         /**\r
 215          * Sets An array of TTSChunks which, taken together, specify the help phrase\r
 216          * to be spoken when the user says "help" during the VR session\r
 217          * <p>\r
 218          * If this parameter is omitted, the help prompt will be constructed by SMARTDEVICELINK\r
 219          * from the first vrCommand of each choice of all the Choice Sets specified\r
 220          * in the interactionChoiceSetIDList parameter\r
 221          * <P>\r
 222          * <b>Notes: </b>The helpPrompt specified in\r
 223          * {@linkplain SetGlobalProperties} is not used by PerformInteraction\r
 224          * \r
 225          * @param helpPrompt\r
 226          *            a Vector<TTSChunk> which taken together, specify the help\r
 227          *            phrase to be spoken when the user says "help" during the VR\r
 228          *            session\r
 229          */    \r
 230     public void setHelpPrompt(Vector<TTSChunk> helpPrompt) {\r
 231         if (helpPrompt != null) {\r
 232             parameters.put(Names.helpPrompt, helpPrompt);\r
 233         } else {\r
 234                 parameters.remove(Names.helpPrompt);\r
 235         }\r
 236     }\r
 237         /**\r
 238          * Gets An array of TTSChunks which, taken together, specify the phrase to\r
 239          * be spoken when the listen times out during the VR session\r
 240          * \r
 241          * @return Vector<TTSChunk> -a Vector<TTSChunk> specify the phrase to be\r
 242          *         spoken when the listen times out during the VR session\r
 243          */    \r
 244     public Vector<TTSChunk> getTimeoutPrompt() {\r
 245         if (parameters.get(Names.timeoutPrompt) instanceof Vector<?>) {\r
 246                 Vector<?> list = (Vector<?>)parameters.get(Names.timeoutPrompt);\r
 247                 if (list != null && list.size() > 0) {\r
 248                     Object obj = list.get(0);\r
 249                     if (obj instanceof TTSChunk) {\r
 250                         return (Vector<TTSChunk>) list;\r
 251                     } else if (obj instanceof Hashtable) {\r
 252                         Vector<TTSChunk> newList = new Vector<TTSChunk>();\r
 253                         for (Object hashObj : list) {\r
 254                             newList.add(new TTSChunk((Hashtable)hashObj));\r
 255                         }\r
 256                         return newList;\r
 257                     }\r
 258                 }\r
 259         }\r
 260         return null;\r
 261     }\r
 262         /**\r
 263          * Sets An array of TTSChunks which, taken together, specify the phrase to\r
 264          * be spoken when the listen times out during the VR session\r
 265          * <p>\r
 266          * <b>Notes: </b>The timeoutPrompt specified in\r
 267          * {@linkplain SetGlobalProperties} is not used by PerformInteraction\r
 268          * \r
 269          * @param timeoutPrompt\r
 270          *            a Vector<TTSChunk> specify the phrase to be spoken when the\r
 271          *            listen times out during the VR session\r
 272          */    \r
 273     public void setTimeoutPrompt(Vector<TTSChunk> timeoutPrompt) {\r
 274         if (timeoutPrompt != null) {\r
 275             parameters.put(Names.timeoutPrompt, timeoutPrompt);\r
 276         } else {\r
 277                 parameters.remove(Names.timeoutPrompt);\r
 278         }\r
 279     }\r
 280         /**\r
 281          * Gets a Integer value representing the amount of time, in milliseconds,\r
 282          * SMARTDEVICELINK will wait for the user to make a choice (VR or Menu)\r
 283          * \r
 284          * @return Integer -a Integer representing the amount of time, in\r
 285          *         milliseconds, SMARTDEVICELINK will wait for the user to make a choice (VR or\r
 286          *         Menu)\r
 287          */    \r
 288     public Integer getTimeout() {\r
 289         return (Integer) parameters.get(Names.timeout);\r
 290     }\r
 291         /**\r
 292          * Sets the amount of time, in milliseconds, SMARTDEVICELINK will wait for the user to\r
 293          * make a choice (VR or Menu). If this time elapses without the user making\r
 294          * a choice, the timeoutPrompt will be spoken. After this timeout value has\r
 295          * been reached, the interaction will stop and a subsequent interaction will\r
 296          * take place after SMARTDEVICELINK speaks the timeout prompt. If that times out as\r
 297          * well, the interaction will end completely. If omitted, the default is\r
 298          * 10000ms\r
 299          * \r
 300          * @param timeout\r
 301          *            an Integer value representing the amount of time, in\r
 302          *            milliseconds, SMARTDEVICELINK will wait for the user to make a choice (VR\r
 303          *            or Menu)\r
 304          *            <p>\r
 305          *            <b>Notes: </b>Min Value: 5000; Max Value: 100000\r
 306          */    \r
 307     public void setTimeout(Integer timeout) {\r
 308         if (timeout != null) {\r
 309             parameters.put(Names.timeout, timeout);\r
 310         } else {\r
 311                 parameters.remove(Names.timeout);\r
 312         }\r
 313     }\r
 314 \r
 315         /**\r
 316          * Gets a Voice recognition Help, which is a suggested VR Help Items to\r
 317          * display on-screen during Perform Interaction\r
 318          * \r
 319          * @return Vector<VrHelpItem> -a Vector value representing a suggested VR\r
 320          *         Help Items to display on-screen during Perform Interaction\r
 321          * @since SmartDeviceLink 2.0\r
 322          */\r
 323     public Vector<VrHelpItem> getVrHelp() {\r
 324         if (parameters.get(Names.vrHelp) instanceof Vector<?>) {\r
 325                 Vector<?> list = (Vector<?>)parameters.get(Names.vrHelp);\r
 326                 if (list != null && list.size() > 0) {\r
 327                     Object obj = list.get(0);\r
 328                     if (obj instanceof VrHelpItem) {\r
 329                         return (Vector<VrHelpItem>) list;\r
 330                     } else if (obj instanceof Hashtable) {\r
 331                         Vector<VrHelpItem> newList = new Vector<VrHelpItem>();\r
 332                         for (Object hashObj : list) {\r
 333                             newList.add(new VrHelpItem((Hashtable)hashObj));\r
 334                         }\r
 335                         return newList;\r
 336                     }\r
 337                 }\r
 338         }\r
 339         return null;\r
 340     }\r
 341 \r
 342         /**\r
 343          * \r
 344          * @param vrHelp\r
 345          *            a Vector representing a suggested VR Help Items to display\r
 346          *            on-screen during Perform Interaction<br/>\r
 347          *            If omitted on supported displays, the default SMARTDEVICELINK generated\r
 348          *            list of suggested choices will be displayed\r
 349          *            <p>\r
 350          *            <b>Notes: </b>Min=1; Max=100\r
 351          * @since SmartDeviceLink 2.0\r
 352          */\r
 353     public void setVrHelp(Vector<VrHelpItem> vrHelp) {\r
 354         if (vrHelp != null) {\r
 355             parameters.put(Names.vrHelp, vrHelp);\r
 356         } else {\r
 357                 parameters.remove(Names.vrHelp);\r
 358         }\r
 359     }\r
 360 }\r