SDL_Android/SmartDeviceLinkProxyAndroid/src/com/smartdevicelink/proxy/rpc/RegisterAppInterface.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.AppHMIType;\r
   9 import com.smartdevicelink.proxy.rpc.enums.Language;\r
  10 import com.smartdevicelink.util.DebugTool;\r
  11 /**\r
  12  * Registers the application's interface with SMARTDEVICELINK&reg;, declaring properties of\r
  13  * the registration, including the messaging interface version, the app name,\r
  14  * etc. The mobile application must establish its interface registration with\r
  15  * SMARTDEVICELINK&reg; before any other interaction with SMARTDEVICELINK&reg; can take place. The\r
  16  * registration lasts until it is terminated either by the application calling\r
  17  * the <i> {@linkplain UnregisterAppInterface}</i> method, or by SMARTDEVICELINK&reg;\r
  18  * sending an <i> {@linkplain OnAppInterfaceUnregistered}</i> notification, or\r
  19  * by loss of the underlying transport connection, or closing of the underlying\r
  20  * message transmission protocol RPC session\r
  21  * <p>\r
  22  * Until the application receives its first <i>{@linkplain OnHMIStatus}</i>\r
  23  * Notification, its HMI Status is assumed to be: <i>\r
  24  * {@linkplain com.smartdevicelink.proxy.rpc.enums.HMILevel}</i>=NONE, <i>\r
  25  * {@linkplain com.smartdevicelink.proxy.rpc.enums.AudioStreamingState}\r
  26  * </i>=NOT_AUDIBLE, <i>\r
  27  * {@linkplain com.smartdevicelink.proxy.rpc.enums.SystemContext}</i>=MAIN\r
  28  * <p>\r
  29  * All SMARTDEVICELINK&reg; resources which the application creates or uses (e.g. Choice\r
  30  * Sets, Command Menu, etc.) are associated with the application's interface\r
  31  * registration. Therefore, when the interface registration ends, the SMARTDEVICELINK&reg;\r
  32  * resources associated with the application are disposed of. As a result, even\r
  33  * though the application itself may continue to run on its host platform (e.g.\r
  34  * mobile device) after the interface registration terminates, the application\r
  35  * will not be able to use the SMARTDEVICELINK&reg; HMI without first establishing a new\r
  36  * interface registration and re-creating its required SMARTDEVICELINK&reg; resources. That\r
  37  * is, SMARTDEVICELINK&reg; resources created by (or on behalf of) an application do not\r
  38  * persist beyond the life-span of the interface registration\r
  39  * <p>\r
  40  * Resources and settings whose lifespan is tied to the duration of an\r
  41  * application's interface registration:<br/>\r
  42  * <ul>\r
  43  * <li>Choice Sets</li>\r
  44  * <li>Command Menus (built by successive calls to <i>{@linkplain AddCommand}\r
  45  * </i>)</li>\r
  46  * <li>Media clock timer display value</li>\r
  47  * <li>Media clock timer display value</li>\r
  48  * <li>Media clock timer display value</li>\r
  49  * </ul>\r
  50  * <p>\r
  51  * The autoActivateID is used to grant an application the HMILevel and\r
  52  * AudioStreamingState it had when it last disconnected\r
  53  * <p>\r
  54  * <b>Notes: </b>The autoActivateID parameter, and associated behavior, is\r
  55  * currently ignored by SMARTDEVICELINK&reg;\r
  56  * <p>\r
  57  * When first calling this method (i.e. first time within life cycle of mobile\r
  58  * app), an autoActivateID should not be included. After successfully\r
  59  * registering an interface, an autoActivateID is returned to the mobile\r
  60  * application for it to use in subsequent connections. If the connection\r
  61  * between SMARTDEVICELINK&reg; and the mobile application is lost, such as the vehicle is\r
  62  * turned off while the application is running, the autoActivateID can then be\r
  63  * passed in another call to RegisterAppInterface to re-acquire <i>\r
  64  * {@linkplain com.smartdevicelink.proxy.rpc.enums.HMILevel}</i>=FULL\r
  65  * <p>\r
  66  * If the application intends to stream audio it is important to indicate so via\r
  67  * the isMediaApp parameter. When set to true, audio will reliably stream\r
  68  * without any configuration required by the user. When not set, audio may\r
  69  * stream, depending on what the user might have manually configured as a media\r
  70  * source on SMARTDEVICELINK&reg;\r
  71  * <p>\r
  72  * There is no time limit for how long the autoActivateID is "valid" (i.e. would\r
  73  * confer focus and opt-in)\r
  74  * <p>\r
  75  * <b>HMILevel is not defined before registering</b><br/>\r
  76  * </p>\r
  77  * \r
  78  * @since SmartDeviceLink 1.0\r
  79  * @see UnregisterAppInterface\r
  80  * @see OnAppInterfaceUnregistered\r
  81  */\r
  82 public class RegisterAppInterface extends RPCRequest {\r
  83         /**\r
  84          * Constructs a new RegisterAppInterface object\r
  85          */\r
  86     public RegisterAppInterface() {\r
  87         super("RegisterAppInterface");\r
  88     }\r
  89         /**\r
  90          * Constructs a new RegisterAppInterface object indicated by the Hashtable\r
  91          * parameter\r
  92          * <p>\r
  93          * \r
  94          * @param hash\r
  95          *            The Hashtable to use\r
  96          */    \r
  97     public RegisterAppInterface(Hashtable hash) {\r
  98         super(hash);\r
  99     }\r
 100         /**\r
 101          * Gets the version of the SMARTDEVICELINK&reg; SmartDeviceLink interface\r
 102          * \r
 103          * @return smartdevicelinkMsgVersion -a smartdevicelinkMsgVersion object representing version of\r
 104          *         the SMARTDEVICELINK&reg; SmartDeviceLink interface\r
 105          */    \r
 106     public smartdevicelinkMsgVersion getsmartdevicelinkMsgVersion() {\r
 107         Object obj = parameters.get(Names.smartDeviceLinkMsgVersion);\r
 108         if (obj instanceof smartdevicelinkMsgVersion) {\r
 109                 return (smartdevicelinkMsgVersion) obj;\r
 110         } else if (obj instanceof Hashtable) {\r
 111                 return new smartdevicelinkMsgVersion((Hashtable) obj);\r
 112         }\r
 113         return null;\r
 114     }\r
 115         /**\r
 116          * Sets the version of the SMARTDEVICELINK&reg; SmartDeviceLink interface\r
 117          * \r
 118          * @param smartDeviceLinkMsgVersion\r
 119          *            a smartdevicelinkMsgVersion object representing version of the SMARTDEVICELINK&reg;\r
 120          *            SmartDeviceLink interface\r
 121          *            <p>\r
 122          *            <b>Notes: </b>To be compatible, app msg major version number\r
 123          *            must be less than or equal to SMARTDEVICELINK&reg; major version number.\r
 124          *            If msg versions are incompatible, app has 20 seconds to\r
 125          *            attempt successful RegisterAppInterface (w.r.t. msg version)\r
 126          *            on underlying protocol session, else will be terminated. Major\r
 127          *            version number is a compatibility declaration. Minor version\r
 128          *            number indicates minor functional variations (e.g. features,\r
 129          *            capabilities, bug fixes) when sent from SMARTDEVICELINK&reg; to app (in\r
 130          *            RegisterAppInterface response). However, the minor version\r
 131          *            number sent from the app to SMARTDEVICELINK&reg; (in RegisterAppInterface\r
 132          *            request) is ignored by SMARTDEVICELINK&reg;\r
 133          */    \r
 134     public void setsmartdevicelinkMsgVersion(smartdevicelinkMsgVersion smartDeviceLinkMsgVersion) {\r
 135         if (smartDeviceLinkMsgVersion != null) {\r
 136             parameters.put(Names.smartDeviceLinkMsgVersion, smartDeviceLinkMsgVersion);\r
 137         } else {\r
 138                 parameters.remove(Names.smartDeviceLinkMsgVersion);\r
 139         }\r
 140     }\r
 141         /**\r
 142          * Gets Mobile Application's Name\r
 143          * \r
 144          * @return String -a String representing the Mobile Application's Name\r
 145          */    \r
 146     public String getAppName() {\r
 147         return (String) parameters.get(Names.appName);\r
 148     }\r
 149         /**\r
 150          * Sets Mobile Application's Name, This name is displayed in the SMARTDEVICELINK&reg;\r
 151          * Mobile Applications menu. It also serves as the unique identifier of the\r
 152          * application for SmartDeviceLink\r
 153          * \r
 154          * @param appName\r
 155          *            a String value representing the Mobile Application's Name\r
 156          *            <p>\r
 157          *            <b>Notes: </b>\r
 158          *            <ul>\r
 159          *            <li>Must be 1-100 characters in length</li>\r
 160          *            <li>May not be the same (by case insensitive comparison) as\r
 161          *            the name or any synonym of any currently-registered\r
 162          *            application</li>\r
 163          *            </ul>\r
 164          */    \r
 165     public void setAppName(String appName) {\r
 166         if (appName != null) {\r
 167             parameters.put(Names.appName, appName);\r
 168         } else {\r
 169                 parameters.remove(Names.appName);\r
 170         }\r
 171     }\r
 172 \r
 173         /**\r
 174          * Gets TTS string for VR recognition of the mobile application name\r
 175          * \r
 176          * @return Vector<TTSChunk> -Vector value representing the TTS string\r
 177          * @since SmartDeviceLink 2.0\r
 178          */\r
 179     public Vector<TTSChunk> getTtsName() {\r
 180         if (parameters.get(Names.ttsName) instanceof Vector<?>) {\r
 181                 Vector<?> list = (Vector<?>)parameters.get(Names.ttsName);\r
 182                 if (list != null && list.size() > 0) {\r
 183                     Object obj = list.get(0);\r
 184                     if (obj instanceof TTSChunk) {\r
 185                         return (Vector<TTSChunk>) list;\r
 186                     } else if (obj instanceof Hashtable) {\r
 187                         Vector<TTSChunk> newList = new Vector<TTSChunk>();\r
 188                         for (Object hashObj : list) {\r
 189                             newList.add(new TTSChunk((Hashtable) hashObj));\r
 190                         }\r
 191                         return newList;\r
 192                     }\r
 193                 }\r
 194         }\r
 195         return null;\r
 196     }\r
 197 \r
 198         /**\r
 199          * \r
 200          * @param ttsName\r
 201          *            a Vector<TTSChunk> value represeting the TTS Name\r
 202          *            <p>\r
 203          *            <b>Notes: </b><br/>\r
 204          *            <ul>\r
 205          *            <li>Size must be 1-100</li>\r
 206          *            <li>Needs to be unique over all applications</li>\r
 207          *            <li>May not be empty</li>\r
 208          *            <li>May not start with a new line character</li>\r
 209          *            <li>May not interfere with any name or synonym of previously\r
 210          *            registered applications and the following list of words</li>\r
 211          *            <li>Needs to be unique over all applications. Applications\r
 212          *            with the same name will be rejected</li>\r
 213          *            </ul>\r
 214          * @since SmartDeviceLink 2.0\r
 215          */\r
 216     public void setTtsName(Vector<TTSChunk> ttsName) {\r
 217         if (ttsName != null) {\r
 218             parameters.put(Names.ttsName, ttsName);\r
 219         } else {\r
 220                 parameters.remove(Names.ttsName);\r
 221         }\r
 222     }\r
 223         /**\r
 224          * Gets a String representing an abbreviated version of the mobile\r
 225          * applincation's name (if necessary) that will be displayed on the NGN\r
 226          * media screen\r
 227          * \r
 228          * @return String -a String value representing an abbreviated version of the\r
 229          *         mobile applincation's name\r
 230          */    \r
 231     public String getNgnMediaScreenAppName() {\r
 232         return (String) parameters.get(Names.ngnMediaScreenAppName);\r
 233     }\r
 234         /**\r
 235          * Sets a String representing an abbreviated version of the mobile\r
 236          * applincation's name (if necessary) that will be displayed on the NGN\r
 237          * media screen\r
 238          * \r
 239          * @param ngnMediaScreenAppName\r
 240          *            a String value representing an abbreviated version of the\r
 241          *            mobile applincation's name\r
 242          *            <p>\r
 243          *            <b>Notes: </b>\r
 244          *            <ul>\r
 245          *            <li>Must be 1-5 characters</li>\r
 246          *            <li>If not provided, value will be derived from appName\r
 247          *            truncated to 5 characters</li>\r
 248          *            </ul>\r
 249          */    \r
 250     public void setNgnMediaScreenAppName(String ngnMediaScreenAppName) {\r
 251         if (ngnMediaScreenAppName != null) {\r
 252             parameters.put(Names.ngnMediaScreenAppName, ngnMediaScreenAppName);\r
 253         } else {\r
 254                 parameters.remove(Names.ngnMediaScreenAppName);\r
 255         }\r
 256     }\r
 257         /**\r
 258          * Gets the Vector<String> representing the an array of 1-100 elements, each\r
 259          * element containing a voice-recognition synonym\r
 260          * \r
 261          * @return Vector<String> -a Vector value representing the an array of\r
 262          *         1-100 elements, each element containing a voice-recognition\r
 263          *         synonym\r
 264          */    \r
 265     public Vector<String> getVrSynonyms() {\r
 266         if (parameters.get(Names.vrSynonyms) instanceof Vector<?>) {\r
 267                 Vector<?> list = (Vector<?>)parameters.get(Names.vrSynonyms);\r
 268                 if (list != null && list.size()>0) {\r
 269                         Object obj = list.get(0);\r
 270                         if (obj instanceof String) {\r
 271                                 return (Vector<String>) list;\r
 272                         }\r
 273                 }\r
 274         }\r
 275         return null;\r
 276     }\r
 277         /**\r
 278          * Sets a vrSynonyms representing the an array of 1-100 elements, each\r
 279          * element containing a voice-recognition synonym\r
 280          * \r
 281          * @param vrSynonyms\r
 282          *            a Vector<String> value representing the an array of 1-100\r
 283          *            elements\r
 284          *            <p>\r
 285          *            <b>Notes: </b>\r
 286          *            <ul>\r
 287          *            <li>Each vr synonym is limited to 40 characters, and there can\r
 288          *            be 1-100 synonyms in array</li>\r
 289          *            <li>May not be the same (by case insensitive comparison) as\r
 290          *            the name or any synonym of any currently-registered\r
 291          *            application</li>\r
 292          *            </ul>\r
 293          */    \r
 294     public void setVrSynonyms(Vector<String> vrSynonyms) {\r
 295         if (vrSynonyms != null) {\r
 296             parameters.put(Names.vrSynonyms, vrSynonyms);\r
 297         } else {\r
 298                 parameters.remove(Names.vrSynonyms);\r
 299         }\r
 300     }\r
 301         /**\r
 302          * Gets a Boolean representing MediaApplication\r
 303          * \r
 304          * @return Boolean -a Boolean value representing a mobile application that is\r
 305          *         a media application or not\r
 306          */    \r
 307     public Boolean getIsMediaApplication() {\r
 308         return (Boolean) parameters.get(Names.isMediaApplication);\r
 309     }\r
 310         /**\r
 311          * Sets a Boolean to indicate a mobile application that is a media\r
 312          * application or not\r
 313          * \r
 314          * @param isMediaApplication\r
 315          *            a Boolean value\r
 316          */    \r
 317     public void setIsMediaApplication(Boolean isMediaApplication) {\r
 318         if (isMediaApplication != null) {\r
 319             parameters.put(Names.isMediaApplication, isMediaApplication);\r
 320         } else {\r
 321                 parameters.remove(Names.isMediaApplication);\r
 322         }\r
 323     }\r
 324         /**\r
 325          * Gets a Language enumeration indicating what language the application\r
 326          * intends to use for user interaction (Display, TTS and VR)\r
 327          * \r
 328          * @return Enumeration -a language enumeration\r
 329          */    \r
 330     public Language getLanguageDesired() {\r
 331         Object obj = parameters.get(Names.languageDesired);\r
 332         if (obj instanceof Language) {\r
 333             return (Language) obj;\r
 334         } else if (obj instanceof String) {\r
 335             Language theCode = null;\r
 336             try {\r
 337                 theCode = Language.valueForString((String) obj);\r
 338             } catch (Exception e) {\r
 339                 DebugTool.logError("Failed to parse " + getClass().getSimpleName() + "." + Names.languageDesired, e);\r
 340             }\r
 341             return theCode;\r
 342         }\r
 343         return null;\r
 344     }\r
 345         /**\r
 346          * Sets an enumeration indicating what language the application intends to\r
 347          * use for user interaction (Display, TTS and VR)\r
 348          * \r
 349          * @param languageDesired\r
 350          *            a Language Enumeration\r
 351          *            <p>\r
 352          * \r
 353          */    \r
 354     public void setLanguageDesired(Language languageDesired) {\r
 355         if (languageDesired != null) {\r
 356             parameters.put(Names.languageDesired, languageDesired);\r
 357         } else {\r
 358                 parameters.remove(Names.languageDesired);\r
 359         }\r
 360     }\r
 361 \r
 362         /**\r
 363          * Gets an enumeration indicating what language the application intends to\r
 364          * use for user interaction ( Display)\r
 365          * \r
 366          * @return Language - a Language value representing an enumeration\r
 367          *         indicating what language the application intends to use for user\r
 368          *         interaction ( Display)\r
 369          * @since SmartDeviceLink 2.0\r
 370          */\r
 371     public Language getHmiDisplayLanguageDesired() {\r
 372         Object obj = parameters.get(Names.hmiDisplayLanguageDesired);\r
 373         if (obj instanceof Language) {\r
 374             return (Language) obj;\r
 375         } else if (obj instanceof String) {\r
 376             Language theCode = null;\r
 377             try {\r
 378                 theCode = Language.valueForString((String) obj);\r
 379             } catch (Exception e) {\r
 380                 DebugTool.logError("Failed to parse " + getClass().getSimpleName() + "." + Names.hmiDisplayLanguageDesired, e);\r
 381             }\r
 382             return theCode;\r
 383         }\r
 384         return null;\r
 385     }\r
 386 \r
 387         /**\r
 388          * Sets an enumeration indicating what language the application intends to\r
 389          * use for user interaction ( Display)\r
 390          * \r
 391          * @param hmiDisplayLanguageDesired\r
 392          * @since SmartDeviceLink 2.0\r
 393          */\r
 394     public void setHmiDisplayLanguageDesired(Language hmiDisplayLanguageDesired) {\r
 395         if (hmiDisplayLanguageDesired != null) {\r
 396             parameters.put(Names.hmiDisplayLanguageDesired, hmiDisplayLanguageDesired);\r
 397         } else {\r
 398                 parameters.remove(Names.hmiDisplayLanguageDesired);\r
 399         }\r
 400     }\r
 401 \r
 402         /**\r
 403          * Gets a list of all applicable app types stating which classifications to\r
 404          * be given to the app.e.g. for platforms , like GEN2, this will determine\r
 405          * which "corner(s)" the app can populate\r
 406          * \r
 407          * @return Vector<AppHMIType> - a Vector value representing a list of all\r
 408          *         applicable app types stating which classifications to be given to\r
 409          *         the app\r
 410          * @since SmartDeviceLinke 2.0\r
 411          */\r
 412     public Vector<AppHMIType> getAppHMIType() {\r
 413         if (parameters.get(Names.appHMIType) instanceof Vector<?>) {\r
 414                 Vector<?> list = (Vector<?>)parameters.get(Names.appHMIType);\r
 415                 if (list != null && list.size() > 0) {\r
 416                     Object obj = list.get(0);\r
 417                     if (obj instanceof AppHMIType) {\r
 418                         return (Vector<AppHMIType>) list;\r
 419                     } else if (obj instanceof String) {\r
 420                         Vector<AppHMIType> newList = new Vector<AppHMIType>();\r
 421                         for (Object hashObj : list) {\r
 422                             String strFormat = (String)hashObj;\r
 423                             AppHMIType toAdd = null;\r
 424                             try {\r
 425                                 toAdd = AppHMIType.valueForString(strFormat);\r
 426                             } catch (Exception e) {\r
 427                                 DebugTool.logError("Failed to parse " + getClass().getSimpleName() + "." + Names.appHMIType, e);                            }\r
 428                             if (toAdd != null) {\r
 429                                 newList.add(toAdd);\r
 430                             }\r
 431                         }\r
 432                         return newList;\r
 433                     }\r
 434                 }\r
 435         }\r
 436         return null;\r
 437     }\r
 438 \r
 439         /**\r
 440          * Sets a a list of all applicable app types stating which classifications\r
 441          * to be given to the app. e.g. for platforms , like GEN2, this will\r
 442          * determine which "corner(s)" the app can populate\r
 443          * \r
 444          * @param appHMIType\r
 445          *            a Vector<AppHMIType>\r
 446          *            <p>\r
 447          *            <b>Notes: </b>\r
 448          *            <ul>\r
 449          *            <li>Array Minsize: = 1</li>\r
 450          *            <li>Array Maxsize = 100</li>\r
 451          *            </ul>\r
 452          * @since SmartDeviceLink 2.0\r
 453          */\r
 454     public void setAppHMIType(Vector<AppHMIType> appHMIType) {\r
 455         if (appHMIType != null) {\r
 456             parameters.put(Names.appHMIType, appHMIType);\r
 457         } else {\r
 458                 parameters.remove(Names.appHMIType);\r
 459         }\r
 460     }\r
 461 \r
 462         /**\r
 463          * Gets the unique ID, which an app will be given when approved by Ford\r
 464          * \r
 465          * @return String - a String value representing the unique ID, which an app\r
 466          *         will be given when approved by Ford\r
 467          * @since SmartDeviceLink 2.0\r
 468          */\r
 469     public String getAppID() {\r
 470         return (String) parameters.get(Names.appID);\r
 471     }\r
 472 \r
 473         /**\r
 474          * Sets a unique ID, which an app will be given when approved by Ford\r
 475          * \r
 476          * @param appID\r
 477          *            a String value representing a unique ID, which an app will be\r
 478          *            given when approved by Ford\r
 479          *            <p>\r
 480          *            <b>Notes: </b>Maxlength = 100\r
 481          * @since SmartDeviceLink 2.0\r
 482          */\r
 483     public void setAppID(String appID) {\r
 484         if (appID != null) {\r
 485             parameters.put(Names.appID, appID);\r
 486         } else {\r
 487                 parameters.remove(Names.appID);\r
 488         }\r
 489     }\r
 490 }\r