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

SDLRegisterAppInterface Class Reference

Section Contents

Overview

Registers the application’s interface with SDL. The RegisterAppInterface RPC declares the properties of the app, 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 SDLUnregisterAppInterface method, or by SDL sending an SDLOnAppInterfaceUnregistered 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 SDLOnHMIStatus notification, its SDLHMILevel is assumed to be NONE, the SDLAudioStreamingState is assumed to be NOT_AUDIBLE, and the SDLSystemContext is assumed to be 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 include: choice sets, command menus, and the media clock timer display value

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.

@since SDL 1.0

See

SDLUnregisterAppInterface, SDLOnAppInterfaceUnregistered

-initWithLifecycleConfiguration:

Convenience init for registering the application with a lifecycle configuration.

Objective-C

- (nonnull instancetype)initWithLifecycleConfiguration:
    (nonnull SDLLifecycleConfiguration *)lifecycleConfiguration;

Swift

init(lifecycleConfiguration: SDLLifecycleConfiguration)

Parameters

lifecycleConfiguration

Configuration options for SDLManager

-initWithAppName:appId:languageDesired:

Convenience init for registering the application.

Objective-C

- (nonnull instancetype)initWithAppName:(nonnull NSString *)appName
                                  appId:(nonnull NSString *)appId
                        languageDesired:(nonnull SDLLanguage)languageDesired;

Swift

init(appName: String, appId: String, languageDesired: SDLLanguage)

Parameters

appName

The mobile application’s name

appId

An appId used to validate app with policy table entries

languageDesired

The language the application intends to use for user interaction

Return Value

A SDLRegisterAppInterface object

-initWithAppName:appId:languageDesired:isMediaApp:appTypes:shortAppName:

Convenience init for registering the application.

Objective-C

- (nonnull instancetype)initWithAppName:(nonnull NSString *)appName
                                  appId:(nonnull NSString *)appId
                        languageDesired:(nonnull SDLLanguage)languageDesired
                             isMediaApp:(BOOL)isMediaApp
                               appTypes:
                                   (nonnull NSArray<SDLAppHMIType> *)appTypes
                           shortAppName:(nullable NSString *)shortAppName;

Swift

init(appName: String, appId: String, languageDesired: SDLLanguage, isMediaApp: Bool, appTypes: [SDLAppHMIType], shortAppName: String?)

Parameters

appName

The mobile application’s name

appId

An appId used to validate app with policy table entries

languageDesired

The language the application intends to use for user interaction

isMediaApp

Indicates if the application is a media or a non-media application

appTypes

A list of all applicable app types stating which classifications to be given to the app

shortAppName

An abbreviated version of the mobile application’s name

Return Value

A SDLRegisterAppInterface object

-initWithAppName:appId:languageDesired:isMediaApp:appTypes:shortAppName:ttsName:vrSynonyms:hmiDisplayLanguageDesired:resumeHash:

Convenience init for registering the application.

Objective-C

- (nonnull instancetype)
          initWithAppName:(nonnull NSString *)appName
                    appId:(nonnull NSString *)appId
          languageDesired:(nonnull SDLLanguage)languageDesired
               isMediaApp:(BOOL)isMediaApp
                 appTypes:(nonnull NSArray<SDLAppHMIType> *)appTypes
             shortAppName:(nullable NSString *)shortAppName
                  ttsName:(nullable NSArray<SDLTTSChunk *> *)ttsName
               vrSynonyms:(nullable NSArray<NSString *> *)vrSynonyms
hmiDisplayLanguageDesired:(nonnull SDLLanguage)hmiDisplayLanguageDesired
               resumeHash:(nullable NSString *)resumeHash;

Swift

init(appName: String, appId: String, languageDesired: SDLLanguage, isMediaApp: Bool, appTypes: [SDLAppHMIType], shortAppName: String?, ttsName: [SDLTTSChunk]?, vrSynonyms: [String]?, hmiDisplayLanguageDesired: SDLLanguage, resumeHash: String?)

Parameters

appName

The mobile application’s name

appId

An appId used to validate app with policy table entries

languageDesired

The language the application intends to use for user interaction

isMediaApp

Indicates if the application is a media or a non-media application

appTypes

A list of all applicable app types stating which classifications to be given to the app

shortAppName

An abbreviated version of the mobile application’s name

ttsName

TTS string for VR recognition of the mobile application name

vrSynonyms

Additional voice recognition commands

hmiDisplayLanguageDesired

Current app’s expected VR+TTS language

resumeHash

ID used to uniquely identify current state of all app data that can persist through connection cycles

Return Value

A SDLRegisterAppInterface object

-initWithAppName:appId:fullAppId:languageDesired:isMediaApp:appTypes:shortAppName:ttsName:vrSynonyms:hmiDisplayLanguageDesired:resumeHash:dayColorScheme:nightColorScheme:

Convenience init for registering the application with all possible options.

Objective-C

- (nonnull instancetype)
          initWithAppName:(nonnull NSString *)appName
                    appId:(nonnull NSString *)appId
                fullAppId:(nullable NSString *)fullAppId
          languageDesired:(nonnull SDLLanguage)languageDesired
               isMediaApp:(BOOL)isMediaApp
                 appTypes:(nonnull NSArray<SDLAppHMIType> *)appTypes
             shortAppName:(nullable NSString *)shortAppName
                  ttsName:(nullable NSArray<SDLTTSChunk *> *)ttsName
               vrSynonyms:(nullable NSArray<NSString *> *)vrSynonyms
hmiDisplayLanguageDesired:(nonnull SDLLanguage)hmiDisplayLanguageDesired
               resumeHash:(nullable NSString *)resumeHash
           dayColorScheme:(nullable SDLTemplateColorScheme *)dayColorScheme
         nightColorScheme:(nullable SDLTemplateColorScheme *)nightColorScheme;

Swift

init(appName: String, appId: String, fullAppId: String?, languageDesired: SDLLanguage, isMediaApp: Bool, appTypes: [SDLAppHMIType], shortAppName: String?, ttsName: [SDLTTSChunk]?, vrSynonyms: [String]?, hmiDisplayLanguageDesired: SDLLanguage, resumeHash: String?, dayColorScheme: SDLTemplateColorScheme?, nightColorScheme: SDLTemplateColorScheme?)

Parameters

appName

The mobile application’s name

appId

An appId used to validate app with policy table entries

fullAppId

A full UUID appID used to validate app with policy table entries.

languageDesired

The language the application intends to use for user interaction

isMediaApp

Indicates if the application is a media or a non-media application

appTypes

A list of all applicable app types stating which classifications to be given to the app

shortAppName

An abbreviated version of the mobile application’s name

ttsName

TTS string for VR recognition of the mobile application name

vrSynonyms

Additional voice recognition commands

hmiDisplayLanguageDesired

Current app’s expected VR+TTS language

resumeHash

ID used to uniquely identify current state of all app data that can persist through connection cycles

dayColorScheme

The color scheme to be used on a head unit using a light or day color scheme.

nightColorScheme

The color scheme to be used on a head unit using a dark or night color scheme

Return Value

A SDLRegisterAppInterface object

syncMsgVersion

The version of the SDL interface

Required

Objective-C

@property (readwrite, strong, nonatomic)
    SDLSyncMsgVersion *_Nonnull syncMsgVersion;

Swift

var syncMsgVersion: SDLSyncMsgVersion { get set }

appName

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 SmartDeviceLink.

  1. Needs to be unique over all applications. Applications with the same name will be rejected.
  2. May not be empty.
  3. May not start with a new line character.
  4. May not interfere with any name or synonym of previously registered applications and any predefined blacklist of words (global commands).

Required, Max length 100 chars

Objective-C

@property (readwrite, strong, nonatomic) NSString *_Nonnull appName;

Swift

var appName: String { get set }

ttsName

TTS string for VR recognition of the mobile application name.

@discussion Meant to overcome any failing on speech engine in properly pronouncing / understanding app name.

  1. Needs to be unique over all applications.
  2. May not be empty.
  3. May not start with a new line character.

Optional, Array of SDLTTSChunk, Array size 1 - 100

@since SDL 2.0

See

SDLTTSChunk

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    NSArray<SDLTTSChunk *> *ttsName;

Swift

var ttsName: [SDLTTSChunk]? { get set }

ngnMediaScreenAppName

A String representing an abbreviated version of the mobile application’s name (if necessary) that will be displayed on the media screen.

@discussion If not provided, the appName is used instead (and will be truncated if too long)

Optional, Max length 100 chars

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    NSString *ngnMediaScreenAppName;

Swift

var ngnMediaScreenAppName: String? { get set }

vrSynonyms

Defines additional voice recognition commands

@discussion May not interfere with any app name of previously registered applications and any predefined blacklist of words (global commands).

Optional, Array of Strings, Array length 1 - 100, Max String length 40

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    NSArray<NSString *> *vrSynonyms;

Swift

var vrSynonyms: [String]? { get set }

isMediaApplication

Indicates if the application is a media or a non-media application.

@discussion Only media applications will be able to stream audio to head units that is audible outside of the BT media source.

Required, Boolean

Objective-C

@property (readwrite, strong, nonatomic)
    NSNumber<SDLBool> *_Nonnull isMediaApplication;

Swift

var isMediaApplication: NSNumber & SDLBool { get set }

languageDesired

A Language enumeration indicating what language the application intends to use for user interaction (TTS and VR).

@discussion If there is a mismatch with the head unit, the app will be able to change this registration with changeRegistration prior to app being brought into focus.

Required

Objective-C

@property (readwrite, strong, nonatomic) SDLLanguage _Nonnull languageDesired;

Swift

var languageDesired: SDLLanguage { get set }

hmiDisplayLanguageDesired

An enumeration indicating what language the application intends to use for user interaction (Display).

@discussion If there is a mismatch with the head unit, the app will be able to change this registration with changeRegistration prior to app being brought into focus.

Required

@since SDL 2.0

Objective-C

@property (readwrite, strong, nonatomic)
    SDLLanguage _Nonnull hmiDisplayLanguageDesired;

Swift

var hmiDisplayLanguageDesired: SDLLanguage { get set }

appHMIType

A list of all applicable app types stating which classifications to be given to the app.

Optional, Array of SDLAppHMIType, Array size 1 - 100

@since SDL 2.0

See

SDLAppHMIType

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    NSArray<SDLAppHMIType> *appHMIType;

Swift

var appHMIType: [SDLAppHMIType]? { get set }

hashID

ID used to uniquely identify current state of all app data that can persist through connection cycles (e.g. ignition cycles).

@discussion 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.).

Optional, max length 100 chars

Objective-C

@property (readwrite, strong, nonatomic, nullable) NSString *hashID;

Swift

var hashID: String? { get set }

deviceInfo

Information about the connecting device

Optional

Objective-C

@property (readwrite, strong, nonatomic, nullable) SDLDeviceInfo *deviceInfo;

Swift

var deviceInfo: SDLDeviceInfo? { get set }

appID

ID used to validate app with policy table entries

Required, max length 100

See

fullAppID

@since SDL 2.0

Objective-C

@property (readwrite, strong, nonatomic) NSString *_Nonnull appID;

Swift

var appID: String { get set }

fullAppID

A full UUID appID used to validate app with policy table entries.

Optional

@discussion The fullAppId is used to authenticate apps that connect with head units that implement SDL Core v.5.0 and newer. If connecting with older head units, the fullAppId can be truncated to create the required appId needed to register the app. The appId is the first 10 non-dash (-) characters of the fullAppID (e.g. if you have a fullAppId of 123e4567-e89b-12d3-a456-426655440000, the appId will be 123e4567e8).

Objective-C

@property (readwrite, strong, nonatomic, nullable) NSString *fullAppID;

Swift

var fullAppID: String? { get set }

appInfo

Information about the application running

Optional

Objective-C

@property (readwrite, strong, nonatomic, nullable) SDLAppInfo *appInfo;

Swift

var appInfo: SDLAppInfo? { get set }

dayColorScheme

The color scheme to be used on a head unit using a light or day color scheme. The OEM may only support this theme if their head unit only has a light color scheme.

Optional

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    SDLTemplateColorScheme *dayColorScheme;

Swift

var dayColorScheme: SDLTemplateColorScheme? { get set }

nightColorScheme

The color scheme to be used on a head unit using a dark or night color scheme. The OEM may only support this theme if their head unit only has a dark color scheme.

Optional

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    SDLTemplateColorScheme *nightColorScheme;

Swift

var nightColorScheme: SDLTemplateColorScheme? { get set }
View on GitHub.com
Previous Section Next Section