Expand Minimize Picture-in-picture Power Device Status Voice Recognition Skip Back Skip Forward Minus Plus Play Search
Documentation
Sidebar

Class RegisterAppInterface

Hierarchy

java.lang.Object
     com.smartdevicelink.proxy.RPCStruct
         com.smartdevicelink.proxy.RPCMessage
             com.smartdevicelink.proxy.RPCRequest

Package
com.smartdevicelink.proxy.rpc

Overview

Registers the application's interface with SDL®, declaring properties of the registration, including the messaging interface version, the app name, etc. The mobile application must establish its interface registration with SDL® before any other interaction with SDL® can take place. The registration lasts until it is terminated either by the application calling the UnregisterAppInterface method, or by SDL® sending an OnAppInterfaceUnregistered notification, or by loss of the underlying transport connection, or closing of the underlying message transmission protocol RPC session

Until the application receives its first OnHMIStatus Notification, its HMI Status is assumed to be: com.smartdevicelink.proxy.rpc.enums.HMILevel=NONE, com.smartdevicelink.proxy.rpc.enums.AudioStreamingState =NOT_AUDIBLE, com.smartdevicelink.proxy.rpc.enums.SystemContext=MAIN

All SDL® resources which the application creates or uses (e.g. Choice Sets, Command Menu, etc.) are associated with the application's interface registration. Therefore, when the interface registration ends, the SDL® resources associated with the application are disposed of. As a result, even though the application itself may continue to run on its host platform (e.g. mobile device) after the interface registration terminates, the application will not be able to use the SDL® HMI without first establishing a new interface registration and re-creating its required SDL® resources. That is, SDL® resources created by (or on behalf of) an application do not persist beyond the life-span of the interface registration

Resources and settings whose lifespan is tied to the duration of an application's interface registration:
  • Choice Sets
  • Command Menus (built by successive calls to AddCommand )
  • Media clock timer display value
  • Media clock timer display value
  • Media clock timer display value

The autoActivateID is used to grant an application the HMILevel and AudioStreamingState it had when it last disconnected

Notes: The autoActivateID parameter, and associated behavior, is currently ignored by SDL®

When first calling this method (i.e. first time within life cycle of mobile app), an autoActivateID should not be included. After successfully registering an interface, an autoActivateID is returned to the mobile application for it to use in subsequent connections. If the connection between SDL® and the mobile application is lost, such as the vehicle is turned off while the application is running, the autoActivateID can then be passed in another call to RegisterAppInterface to re-acquire com.smartdevicelink.proxy.rpc.enums.HMILevel=FULL

If the application intends to stream audio it is important to indicate so via the isMediaApp parameter. When set to true, audio will reliably stream without any configuration required by the user. When not set, audio may stream, depending on what the user might have manually configured as a media source on SDL®

There is no time limit for how long the autoActivateID is "valid" (i.e. would confer focus and opt-in)

HMILevel is not defined before registering

Parameter List

Name Type Description Reg. Notes Version
MsgVersion MsgVersion Declares what version of the SDL interface the application expects to use with SDL Y To be compatible, app msg major version number must be less than or equal to SDL major version number.

If msg versions are incompatible, app has 20 seconds to attempt successful RegisterAppInterface (w.r.t. msg version) on underlying protocol session, else will be terminated. Major version number is a compatibility declaration. Minor version number indicates minor functional variations (e.g. features, capabilities, bug fixes) when sent from SDL to app (in RegisterAppInterface response).

However, the minor version number sent from the app to SDL (in RegisterAppInterface request) is ignored by SDL.
SmartDeviceLink 1.0
appName String The mobile application's name. This name is displayed in the SDL Mobile Applications menu. It also serves as the unique identifier of the application for SDL . Y

Must be 1-100 characters in length. Must consist of following characters:

May not be the same (by case insensitive comparison) as the name or any synonym of any currently registered application.

SmartDeviceLink 1.0
ttsName TTSChunk TTS string for VR recognition of the mobile application name. Meant to overcome any failing on speech engine in properly pronouncing / understanding app name. N

Size must be 1-100 Needs to be unique over all applications. May not be empty.

May not start with a new line character.

SmartDeviceLink 2.0
ngnMediaScreenAppName String Provides an abbreviated version of the app name (if necessary) that will be displayed on the NGN media screen. N - Must be 1-5 characters. If not provided, value will be derived from appName truncated to 5 characters. SmartDeviceLink 1.0
vrSynonyms String An array of 1-100 elements, each element containing a voice-recognition synonym by which this app can be called when being addressed in the mobile applications menu. N Each vr synonym is limited to 40 characters, and there can be 1-100 synonyms in array. May not be the same (by case insensitive comparison) as the name or any synonym of any currently-registered application. SmartDeviceLink 1.0
isMediaApplication Boolean Indicates that the application will be streaming audio to SDL (via A2DP) that is audible outside of the BT media source. Y SmartDeviceLink 1.0
languageDesired Language An enumeration indicating what language the application intends to use for user interaction (Display, TTS and VR). Y If the language indicated does not match the active language on SDL, the interface registration will be rejected.If the user changes the SDL language while this interface registration is active, the interface registration will be terminated. SmartDeviceLink 1.0
hmiDisplayLanguageDesired Language An enumeration indicating what language the application intends to use for user interaction ( Display). Y SmartDeviceLink 2.0
appHMIType AppHMIType List of all applicable app types stating which classifications to be given to the app.e.g. for platforms , like GEN2, this will determine which "corner(s)" the app can populate N Array Minsize: 1; Array Maxsize: 100 SmartDeviceLink 2.0
hashID String ID used to uniquely identify current state of all app data that can persist through connection cycles (e.g. ignition cycles).This registered data (commands, submenus, choice sets, etc.) can be reestablished without needing to explicitly reregister each piece. If omitted, then the previous state of an app's commands, etc. will not be restored.When sending hashID, all RegisterAppInterface parameters should still be provided (e.g. ttsName, etc.). N maxlength:100 SmartDeviceLink 2.3.1
deviceInfo DeviceInfo Various information abount connecting device. N SmartDeviceLink 2.3.1
appID String ID used to validate app with policy table entries Y Maxlength: 100 SmartDeviceLink 2.0
fullAppID String ID used to validate app with policy table entries N Maxlength: 100 SmartDeviceLink 5.0
hmiCapabilities HMICapabilities Specifies the HMI capabilities. N SmartDeviceLink 2.3.2.2
sdlVersion String The SmartDeviceLink version. N Maxlength: 100 SmartDeviceLink 2.3.2.2
systemSoftwareVersion String The software version of the system that implements the SmartDeviceLink core. N Maxlength: 100 SmartDeviceLink 2.3.2.2
dayColorScheme TemplateColorScheme The color scheme that is used for day. N SmartDeviceLink 5.0
nightColorScheme TemplateColorScheme The color scheme that is used for night. N SmartDeviceLink 5.0

Quick Jump

Fields
Constructors
Methods

Fields

KEY_TTS_NAME

public static final java.lang.String KEY_TTS_NAME
Constant Value
"ttsName"

KEY_HMI_DISPLAY_LANGUAGE_DESIRED

public static final java.lang.String KEY_HMI_DISPLAY_LANGUAGE_DESIRED
Constant Value
"hmiDisplayLanguageDesired"

KEY_APP_HMI_TYPE

public static final java.lang.String KEY_APP_HMI_TYPE
Constant Value
"appHMIType"

KEY_APP_ID

public static final java.lang.String KEY_APP_ID
Constant Value
"appID"

KEY_FULL_APP_ID

public static final java.lang.String KEY_FULL_APP_ID
Constant Value
"fullAppID"

KEY_LANGUAGE_DESIRED

public static final java.lang.String KEY_LANGUAGE_DESIRED
Constant Value
"languageDesired"

KEY_DEVICE_INFO

public static final java.lang.String KEY_DEVICE_INFO
Constant Value
"deviceInfo"

KEY_APP_NAME

public static final java.lang.String KEY_APP_NAME
Constant Value
"appName"

KEY_NGN_MEDIA_SCREEN_APP_NAME

public static final java.lang.String KEY_NGN_MEDIA_SCREEN_APP_NAME
Constant Value
"ngnMediaScreenAppName"

KEY_IS_MEDIA_APPLICATION

public static final java.lang.String KEY_IS_MEDIA_APPLICATION
Constant Value
"isMediaApplication"

KEY_VR_SYNONYMS

public static final java.lang.String KEY_VR_SYNONYMS
Constant Value
"vrSynonyms"

KEY_SDL_MSG_VERSION

public static final java.lang.String KEY_SDL_MSG_VERSION
Constant Value
"syncMsgVersion"

KEY_HASH_ID

public static final java.lang.String KEY_HASH_ID
Constant Value
"hashID"

KEY_DAY_COLOR_SCHEME

public static final java.lang.String KEY_DAY_COLOR_SCHEME
Constant Value
"dayColorScheme"

KEY_NIGHT_COLOR_SCHEME

public static final java.lang.String KEY_NIGHT_COLOR_SCHEME
Constant Value
"nightColorScheme"

Inherited Fields

From Class Fields
com.smartdevicelink.proxy.RPCRequest onResponseListener
com.smartdevicelink.proxy.RPCMessage KEY_REQUEST, KEY_RESPONSE, KEY_NOTIFICATION, KEY_FUNCTION_NAME, KEY_PARAMETERS, KEY_CORRELATION_ID, messageType, parameters, function
com.smartdevicelink.proxy.RPCStruct KEY_BULK_DATA, KEY_PROTECTED, store

Constructors

RegisterAppInterface()

Constructs a new RegisterAppInterface object

public RegisterAppInterface()

RegisterAppInterface( java.util.Hashtable<java.lang.String, java.lang.Object> hash )

Constructs a new RegisterAppInterface object indicated by the Hashtable parameter

public RegisterAppInterface(java.util.Hashtable<java.lang.String, java.lang.Object> hash)

Parameters

hash
The Hashtable to use

RegisterAppInterface( SdlMsgVersion syncMsgVersion, String appName, Boolean isMediaApplication, Language languageDesired, Language hmiDisplayLanguageDesired, String fullAppID )

Constructs a new RegisterAppInterface object

public RegisterAppInterface(SdlMsgVersion syncMsgVersion,String appName,Boolean isMediaApplication,Language languageDesired,Language hmiDisplayLanguageDesired,String fullAppID)

Parameters

syncMsgVersion
a SdlMsgVersion object representing version of the SDL® SmartDeviceLink interface
Notes: To be compatible, app msg major version number must be less than or equal to SDL® major version number. If msg versions are incompatible, app has 20 seconds to attempt successful RegisterAppInterface (w.r.t. msg version) on underlying protocol session, else will be terminated. Major version number is a compatibility declaration. Minor version number indicates minor functional variations (e.g. features, capabilities, bug fixes) when sent from SDL® to app (in RegisterAppInterface response). However, the minor version number sent from the app to SDL® (in RegisterAppInterface request) is ignored by SDL®
appName
a String value representing the Mobile Application's Name
Notes:
  • Must be 1-100 characters in length
  • May not be the same (by case insensitive comparison) as the name or any synonym of any currently-registered application
isMediaApplication
a Boolean value
languageDesired
a Language Enumeration
hmiDisplayLanguageDesired
fullAppID
a String value representing a unique ID, which an app will be given when approved
Notes: Maxlength = 100

Methods

getSdlMsgVersion()

Gets the version of the SDL® SmartDeviceLink interface

public com.smartdevicelink.proxy.rpc.SdlMsgVersion getSdlMsgVersion()

setSdlMsgVersion( SdlMsgVersion sdlMsgVersion )

Sets the version of the SDL® SmartDeviceLink interface

public void setSdlMsgVersion(SdlMsgVersion sdlMsgVersion)

Parameters

sdlMsgVersion
a SdlMsgVersion object representing version of the SDL® SmartDeviceLink interface

Notes: To be compatible, app msg major version number must be less than or equal to SDL® major version number. If msg versions are incompatible, app has 20 seconds to attempt successful RegisterAppInterface (w.r.t. msg version) on underlying protocol session, else will be terminated. Major version number is a compatibility declaration. Minor version number indicates minor functional variations (e.g. features, capabilities, bug fixes) when sent from SDL® to app (in RegisterAppInterface response). However, the minor version number sent from the app to SDL® (in RegisterAppInterface request) is ignored by SDL®

getDeviceInfo()

public com.smartdevicelink.proxy.rpc.DeviceInfo getDeviceInfo()

setDeviceInfo( DeviceInfo deviceInfo )

public void setDeviceInfo(DeviceInfo deviceInfo)

Parameters

deviceInfo

getAppName()

Gets Mobile Application's Name

public java.lang.String getAppName()

setAppName( String appName )

Sets Mobile Application's Name, This name is displayed in the SDL® Mobile Applications menu. It also serves as the unique identifier of the application for SmartDeviceLink

public void setAppName(String appName)

Parameters

appName
a String value representing the Mobile Application's Name

Notes:
  • Must be 1-100 characters in length
  • May not be the same (by case insensitive comparison) as the name or any synonym of any currently-registered application

getTtsName()

Gets TTS string for VR recognition of the mobile application name

public java.util.List getTtsName()

setTtsName( java.util.List<com.smartdevicelink.proxy.rpc.TTSChunk> ttsName )

public void setTtsName(java.util.List<com.smartdevicelink.proxy.rpc.TTSChunk> ttsName)

Parameters

ttsName
a List value represeting the TTS Name

Notes:
  • Size must be 1-100
  • Needs to be unique over all applications
  • May not be empty
  • May not start with a new line character
  • May not interfere with any name or synonym of previously registered applications and the following list of words
  • Needs to be unique over all applications. Applications with the same name will be rejected

getNgnMediaScreenAppName()

Gets a String representing an abbreviated version of the mobile applincation's name (if necessary) that will be displayed on the NGN media screen

public java.lang.String getNgnMediaScreenAppName()

setNgnMediaScreenAppName( String ngnMediaScreenAppName )

Sets a String representing an abbreviated version of the mobile applincation's name (if necessary) that will be displayed on the NGN media screen

public void setNgnMediaScreenAppName(String ngnMediaScreenAppName)

Parameters

ngnMediaScreenAppName
a String value representing an abbreviated version of the mobile applincation's name

Notes:
  • Must be 1-5 characters
  • If not provided, value will be derived from appName truncated to 5 characters

getVrSynonyms()

Gets the List representing the an array of 1-100 elements, each element containing a voice-recognition synonym

public java.util.List getVrSynonyms()

setVrSynonyms( java.util.List<java.lang.String> vrSynonyms )

Sets a vrSynonyms representing the an array of 1-100 elements, each element containing a voice-recognition synonym

public void setVrSynonyms(java.util.List<java.lang.String> vrSynonyms)

Parameters

vrSynonyms
a List value representing the an array of 1-100 elements

Notes:
  • Each vr synonym is limited to 40 characters, and there can be 1-100 synonyms in array
  • May not be the same (by case insensitive comparison) as the name or any synonym of any currently-registered application

getIsMediaApplication()

Gets a Boolean representing MediaApplication

public java.lang.Boolean getIsMediaApplication()

setIsMediaApplication( Boolean isMediaApplication )

Sets a Boolean to indicate a mobile application that is a media application or not

public void setIsMediaApplication(Boolean isMediaApplication)

Parameters

isMediaApplication
a Boolean value

getLanguageDesired()

Gets a Language enumeration indicating what language the application intends to use for user interaction (Display, TTS and VR)

public com.smartdevicelink.proxy.rpc.enums.Language getLanguageDesired()

setLanguageDesired( Language languageDesired )

Sets an enumeration indicating what language the application intends to use for user interaction (Display, TTS and VR)

public void setLanguageDesired(Language languageDesired)

Parameters

languageDesired
a Language Enumeration

getHmiDisplayLanguageDesired()

Gets an enumeration indicating what language the application intends to use for user interaction ( Display)

public com.smartdevicelink.proxy.rpc.enums.Language getHmiDisplayLanguageDesired()

setHmiDisplayLanguageDesired( Language hmiDisplayLanguageDesired )

Sets an enumeration indicating what language the application intends to use for user interaction ( Display)

public void setHmiDisplayLanguageDesired(Language hmiDisplayLanguageDesired)

Parameters

hmiDisplayLanguageDesired

getAppHMIType()

Gets a list of all applicable app types stating which classifications to be given to the app.e.g. for platforms , like GEN2, this will determine which "corner(s)" the app can populate

public java.util.List getAppHMIType()

setAppHMIType( java.util.List<com.smartdevicelink.proxy.rpc.enums.AppHMIType> appHMIType )

Sets a a list of all applicable app types stating which classifications to be given to the app. e.g. for platforms , like GEN2, this will determine which "corner(s)" the app can populate

public void setAppHMIType(java.util.List<com.smartdevicelink.proxy.rpc.enums.AppHMIType> appHMIType)

Parameters

appHMIType
a List

Notes:
  • Array Minsize: = 1
  • Array Maxsize = 100

getHashID()

public java.lang.String getHashID()

setHashID( String hashID )

public void setHashID(String hashID)

Parameters

hashID

getAppID()

Gets the unique ID, which an app will be given when approved

public java.lang.String getAppID()

setAppID( String appID )

Sets a unique ID, which an app will be given when approved

public void setAppID(String appID)

Parameters

appID
a String value representing a unique ID, which an app will be given when approved

Notes: Maxlength = 100

getFullAppID()

Gets the unique ID, which an app will be given when approved

public java.lang.String getFullAppID()

setFullAppID( String fullAppID )

Sets a unique ID, which an app will be given when approved
Note: this will automatically parse the fullAppID into the smaller appId and set the appId value as well

public void setFullAppID(String fullAppID)

Parameters

fullAppID
a String value representing a unique ID, which an app will be given when approved

Notes: Maxlength = 100

format( Version rpcVersion, boolean formatParams )

public void format(Version rpcVersion,boolean formatParams)

Parameters

rpcVersion
formatParams

getDayColorScheme()

Gets the color scheme that is currently used for day

public com.smartdevicelink.proxy.rpc.TemplateColorScheme getDayColorScheme()

setDayColorScheme( TemplateColorScheme templateColorScheme )

Sets the color scheme that is intended to be used for day

public void setDayColorScheme(TemplateColorScheme templateColorScheme)

Parameters

templateColorScheme
a TemplateColorScheme object representing the colors that will be used for day color scheme

getNightColorScheme()

Gets the color scheme that is currently used for night

public com.smartdevicelink.proxy.rpc.TemplateColorScheme getNightColorScheme()

setNightColorScheme( TemplateColorScheme templateColorScheme )

Sets the color scheme that is intended to be used for night

public void setNightColorScheme(TemplateColorScheme templateColorScheme)

Parameters

templateColorScheme
a TemplateColorScheme object representing the colors that will be used for night color scheme

Inherited Methods

From Class Methods
com.smartdevicelink.proxy.RPCRequest getCorrelationID, setCorrelationID, setOnRPCResponseListener, getOnRPCResponseListener
com.smartdevicelink.proxy.RPCMessage getFunctionName, setFunctionName, getMessageType, setParameters, getParameters, getObject, getString, getInteger, getFloat, getDouble, getBoolean, getLong
com.smartdevicelink.proxy.RPCStruct getStoreValue, getStore, deserializeJSON, deserializeJSONObject, serializeJSON, serializeJSON, format, getBulkData, setBulkData, setPayloadProtected, isPayloadProtected, getMessageTypeName, hasKey, setValue, getValue, getObject, formatObject, getValueForString, getString, getInteger, getDouble, getFloat, getBoolean, getLong
java.lang.Object getClass, hashCode, equals, clone, toString, notify, notifyAll, wait, wait, wait, finalize
View on GitHub.com
Previous Section Next Section