Merge pull request #45 from smartdevicelink/release/4.3.0

Release/4.3.0

docs/BasicCommunication/OnAppRegistered/index.md

@@ -17,7 +17,7 @@ SDL will send `OnAppRegistered`:
 
 Regarding data resumption:
 
-Data resumption means that an app may request to restore data used in the previous ignition cycle after an `Unexpected Disconnect`.
+Data resumption means that an application may request to restore data used in the previous ignition cycle after an `Unexpected Disconnect`.
 
 
   * For data resumption purposes, SDL must store application-related data such as commands, application global properties, and show data for the past three ignition cycles after an `Unexpected Disconnect` or `Ignition Off`. On the fourth  `Ignition On`, SDL clears all corresponding application-related data used for resumption.
@@ -35,43 +35,43 @@ If the application resumes data successfully:
     * `SubscribeButton`
     * `SubscibeVehicleData`
 
-If the application does not resume data successfully:
+If the application does NOT resume data successfully:
 
   * SDL will provide `OnAppRegistered` with `resumeVrGrammars`:`false` or no resume parameter at all.
   * SDL cleans up all previously stored application data for the application that failed to resume. The HMI must also clean up previously compiled `VRGrammars` for the application.
   * The application will send new data to start SDL operations. In this event, SDL and the HMI should restart the cycle of collecting application data for resumption.
 
 !!! MUST
 
-  1. HMI must update its list of registered applications.
-  2. HMI must store the application data sent in the `applications` parameter.
-  3. HMI must compile and store `VRGrammars` for the `vrSynonyms` parameter, and arrange them for the user to be able to use via voice recognition. Note: The VR commands to activate an application must be accessible when viewing a different active application or the list of registered applications.
-  4. HMI must provide the user with the possibility to choose an application among a list of registered applications.
-  5. HMI must send an `OnAppActivated` notification to SDL when the user activates an app via the `UI` or `VR`.
-
+  1. Update its list of registered applications.
+  2. Store the application data sent in the `applications` parameter.
+  3. Compile and store `VRGrammars` for the `vrSynonyms` parameter, and arrange them for the user to be able to use via voice recognition. Note: The VR commands to activate an application must be accessible when viewing a different active application or the list of registered applications.
+  4. Provide the user with the possibility to choose an application among a list of registered applications.
+  5. Send an `OnAppActivated` notification to SDL when the user activates an app via the `UI` or `VR`.   
+  6. Manage application events by priority. HMI gets proirity information from _OnAppRegistered_, _UpdateAppList_, _ActivateApp_ HMI API.
 !!!
 
-!!! NOTE
-
-If a device is connected over USB and registers an application, SDL will send `OnAppRegistered` with a hash of the usb serial number as the device id.
-
-If a device is connected over Bluetooth or Wi-Fi and registers an application, SDL will send `OnAppRegistered` with a hash of the device's mac address as the device id.
-
+!!! NOTE   
+   * If a device is connected over USB and registers an application, SDL will send `OnAppRegistered` with a hash of the usb serial number as the device id.
+   * If a device is connected over Bluetooth or Wi-Fi and registers an application, SDL will send `OnAppRegistered` with a hash of the device's mac address as the device id.
+   * When the application is registered for the first time (no records in PT) PoliciesManager should not initiate prompting the User about the event.
 !!!
 
-
-
 ### Notification
 
 #### Parameters
 
 |Name|Type|Mandatory|Additional|
 |:---|:---|:--------|:---------|
-|application|[Common.HMIApplication](../../common/structs/#hmiapplication)|true||
-|ttsName|[Common.TTSChunk](../../common/structs/#ttschunk)|false|array: true<br>minsize: 1<br>maxsize: 100|
+|application|[Common.HMIApplication]|true||
+|ttsName|[Common.TTSChunk]|false|array: true<br>minsize: 1<br>maxsize: 100|
 |vrSynonyms|String|false|array: true<br>minsize: 1<br>maxsize: 100<br>maxlength: 40|
 |resumeVrGrammars|Boolean|false||
-|priority|[Common.AppPriority](../../common/enums/#apppriority)|false||
+|priority|[Common.AppPriority]|false||
+
+[Common.HMIApplication]: ../../common/structs/#hmiapplication
+[Common.TTSChunk]: ../../common/structs/#ttschunk
+[Common.AppPriority]: ../../common/enums/#apppriority
 
 ### Sequence Diagrams
 |||

docs/BasicCommunication/OnSystemRequest/index.md

@@ -4,47 +4,52 @@ Type
 : Notification
 
 Sender
-: HMI
+: SDL
 
 Purpose
-: A request from the HMI to download data via a connected application.
+: A request from SDL to download data via a connected application.
 
-An `OnSystemRequest` is a notification that can be used for a couple of different purposes:
+**HTTP flow**
 
-  * As an asynchronous request from the HMI/Core for specific data from the mobile device or cloud.
-  * As a response to a request from the device or cloud. In this case binary data could be included in the hybrid part of the message to the mobile device.
-  * As a request to the mobile side to stop a current upload/data transfer via a `PutFile`.
+* SDL sends the PTS snapshot as binary data via an `OnSystemRequest` mobile request from the system to the backend. Both the "url" that the PTS will be forwarded to and the "timeout" must be taken from the Local Policy Table.
+    * If no "url" is provided in the Local Policy Table, it is supposed that the mobile application will send the Policy Table Update data back to SDL.
 
 `RequestType` defines the type of the requested data from a mobile device or the cloud. The HMI may request this data, but it's SDL's responsibility to block a `SystemRequest` in case the request intends to transfer a data type not allowed by the policy table.
 
-The HMI is informed about `requestTypes` that are allowed by policies via [OnAppPermissionChanged](../../sdl/onapppermissionchanged) and [OnAppRegistered](../onappregistered).
-
-!!! NOTE
-
-If the HMI sends `OnSystemRequest` with a request type disallowed by the policy table, SDL will ignore it.
+HMI is informed about `requestTypes` that are allowed by policies via [OnAppPermissionChanged](../../sdl/onapppermissionchanged) and [OnAppRegistered](../onappregistered).
 
+!!! NOTE   
+  1. If HMI sends `OnSystemRequest` with a request type disallowed by the policy table, SDL will ignore it.   
+  2. If HMI sends 'url' parameter within BasicCommunication.OnSystemRequest, SDL resends the 'url' parameter to mobile app via OnSystemRequest.   
+  3. If HMI(SyncP) doesn't send any URLs to SDL, it is supposed that mobile application will sent Policy Table Update data back to SDL.
 !!!
 
-!!! MUST
-
-HMI must send `OnSystemRequest` if specific data is requested from the mobile device/cloud, or binary data needs to be sent to the mobile device.
+_**SyncP NOTE**_   
+ 1. It's SyncP responsibility to encrypt and encode PTS file and provide it to SDL via OnSystemRequest HMI API ("filename") parameter.      
+ 2. It's SyncP responsibility to choose an application for sending PTU and start timer (for future retry strategy) after sending OnSystemRequest to SDL.
 
+!!! MUST   
+HMI must send `OnSystemRequest`, if specific data is requested from the mobile device/cloud, or binary data needs to be sent to the mobile device.
 !!!
+
 ### Notification
 
 #### Parameters
 
 |Name|Type|Mandatory|Additional|
 |:---|:---|:--------|:---------|
-|requestType|[Common.RequestType](../../common/enums/#requesttype)|true||
+|requestType|[Common.RequestType]|true||
 |url|String|false|minlength: 1<br>maxlength: 1000|
-|fileType|[Common.FileType](../../common/enums/#filetype)|false||
+|fileType|[Common.FileType]|false||
 |offset|Integer|false|minvalue: 0<br>maxvalue: 100000000000|
 |length|Integer|false|minvalue: 0<br>maxvalue: 100000000000|
 |timeout|Integer|false|minvalue: 0<br>maxvalue: 2000000000|
 |fileName|String|true|minlength: 1<br>maxlength: 255|
 |appID|String|false|minlength: 1<br>maxlength: 50|
 
+[Common.RequestType]: ../../common/enums/#requesttype
+[Common.FileType]: ../../common/enums/#filetype
+
 ### Sequence Diagrams
 |||
 System Requests File Download
@@ -56,6 +61,11 @@ BC.OnSystemRequest in "Proprietary" Policy Table Update Flow
 ![Proprietary PTU](./assets/OnSystemRequest_in_Proprietary_PTU_flow.png)
 |||
 
+|||
+BC.OnSystemRequest in External Proprietary Policy Table Update Flow
+![EXTERNAL proprietary](../policyupdate/assets/diagram_PolicyUpdate_external_proprietary.png)
+|||
+
 #### JSON Example Notification
 ```json
 {

docs/BasicCommunication/PolicyUpdate/index.md

@@ -1,4 +1,5 @@
 ## PolicyUpdate
+
 Type
 : Function
 
@@ -8,57 +9,75 @@ Sender
 Purpose
 : Inform HMI about the Policy Table Update (PTU) mechanism is triggered on SDL
 
+In case SDL is built with **"-DEXTENDED_POLICY: HTTP" flag**, SDL supports PolicyTableUpdate flow **without HMI-related logic**. 
 ### Request
-
 ``BC.PolicyUpdate`` represents SDL-generated request to start the PTU sequence.
 
-!!! must
+!!! MUST
+**Proprietary Policies**:
 
-1. Encrypt the Snapshot PT (path from ``file`` parameter) _in case_ and by the scheme required by Policies Server
+* Encrypt the Snapshot PT (path from ``file`` parameter) _in case_ and by the scheme required by Policies Server
 * Request Policies Server url via the next ``SDL.GetURLs`` from SDL
 * Provide the path defined by ``file`` parameter in the next ``BC.OnSystemRequest`` that SDL will forward to mobile application
 * Recognize the PTU status notifications of ``SDL.OnStatusUpdate`` from SDL and display them in the appropriate UI menu
-
 !!!
 
-!!! note
-
+!!! NOTE
 1. ``BC.PolicyUpdate`` dependencies:
-   * SDL sends ``BC.PolicyUpdate`` _only in case_ it's built with ``"-DEXTENDED_POLICY: ON"`` flag. _Otherwise_ SDL handles the entire PTU flow by itself.
+   * SDL sends ``BC.PolicyUpdate`` _only in case_ it's built with "-DEXTENDED_POLICY: PROPRIETARY" flag or without this flag. _Otherwise_ SDL handles the entire PTU flow by itself.
    * If HMI fails to respond ``BC.PolicyUpdate`` or responds with error, PTU sequence will _not_ be continued.  
 2. Triggers for sending ``BC.PolicyUpdate`` (whichever comes first):
-   * Days since previous successful PTU (``"exchange_after_x_days"`` value in local PolicyTable (PT))
+   * Days since previous successful PTU (``"exchange_after_x_days"`` value in local PolicyTable (PT)
    * Kilometers since previous successful PTU (``"exchange_after_x_kilometers"`` value in local PT)
    * Ignition cycles since previous successful PTU (``"exchange_after_x_ignition_cycles"`` value in local PT)
-   * Expired module's certificate (stored in ``"certificate"``field of local PT)
+   * 24 hours prior to module's certificate expiration date:
+a. The triggers for checking the cert expiration status are:
+Ignition On
+TLS handshake
    * New application (that is, not-yet existing in local PT) registration
+   * In case the status of PTU is UPDATE_NEEDED due to failed retry stratery at previous ignition cycle
 3. Parameters values origin:
    * ``file`` - is the path to the Snapshot of local PolicyTable (Snapshot PT final destination is Policies Server)
    * ``timeout`` - value taken from ``"timeout_after_x_seconds"`` field of local PT
    * ``retry`` - array of values from ``"seconds_between_retries"`` field of local PT. SDL handles the PTU retry sequence (re-requesting update if fails to receive during timeout) by itself.
-
+4. When SDL  is built with EXTERNAL_PROPRIETARY flow, SDL _PoliciesManager_ must change the status to “UPDATING” and notify HMI with OnStatusUpdate("UPDATING") right after SnapshotPT is sent out to to mobile app via OnSystemRequest() RPC.   
 !!!
 
 #### Parameters
 
-|Name|Type|Mandatory|Additional|
-|:---|:---|:--------|:---------|
-|file|String|true|minlength: 1<br>maxlength: 255|
-|timeout|Integer|true|minvalue: 0<br>maxvalue: 65535|
-|retry|Integer|true|array: true<br>minsize: 1<br>maxsize: 5<br>minvalue: 0<br>maxvalue: 65535|
+|Name|Type|Mandatory|Additional|Description|
+|:---|:---|:--------|:---------|:----------|
+|file|String|true|minlength: 1<br>maxlength: 255|Location of policy table snapshot. It’s defined in smartDeviceLink.ini as  “PathToSnapshot” parameter|
+|timeout|Integer|true|minvalue: 0<br>maxvalue: 65535|Send attempt timeout in seconds, it’s a value from the Policy Table.|
+|retry|Integer|true|array: true<br>minsize: 1<br>maxsize: 5<br>minvalue: 0<br>maxvalue: 65535|Array of delays to wait after failed atempts, it’s a value from the Policy Table|
 
 ### Response
 
-!!! must
-
-1. Respond with ``SUCCESS`` resultCode to continue the PTU flow.
-
+!!! MUST   
+Respond with ``SUCCESS`` resultCode to continue the PTU flow.
 !!!
 
 #### Parameters
 
 This RPC has no additional parameter requirements
 
+### Sequence Diagrams
+
+|||
+BC.PolicyUpdate in EXTERNAL PROPRIETARY Policy Table Update Flow
+![External proprietary](./assets/diagram_PolicyUpdate_external_proprietary.png)
+|||
+
+|||
+BC.PolicyUpdate in PROPRIETARY Policy Table Update Flow
+![Proprietary PTU](./assets/Proprietary_PTU_flow.png)
+|||
+
+|||
+BC.PolicyUpdate in "HTTP" Policy Table Update Flow
+![HTTP PTU](./assets/PolicyUpdate_in_HTTP_PTU_flow.png)
+|||
+
 ### Example Request
 
 ```json
@@ -107,10 +126,3 @@ This RPC has no additional parameter requirements
 }
 
 ```
-
-### Sequence Diagrams
-
-|||
-BC.PolicyUpdate in "Proprietary" Policy Table Update Flow
-![Proprietary PTU](./assets/PolicyUpdate_in_Proprietary_PTU_flow.png)
-|||

docs/Common/Enums/index.md

@@ -802,3 +802,9 @@
 |OFF|1||
 |ON|2||
 
+### EntityStatus
+|Name|Value|Description|
+|:---|:----|:----------|
+|ON|||
+|OFF||| 
+

docs/Common/Structs/index.md

@@ -411,6 +411,14 @@
 |imageTypeSupported|Common.FileType|false|array: true<br>minsize: 1<br>maxsize: 100||
 |imageResolution|Common.ImageResolution|false|||
 
+### ExternalConsentStatus
+
+|Name|Type|Mandatory|Additional|Description|
+|:---|:---|:--------|:---------|:----------|
+|entityType|Integer|true|minvalue: 0<br>maxvalue: 128|The entityType which status is informed by "status" param.|
+|entityID|Integer|true|minvalue: 0<br>maxvalue: 128|The corresponding ID of entityType which status is informed by "status" param.|
+|status|[Common.EntityStatus](../Enums/index.md#entitystatus)|true|-|Status of External User Consent Settings entity: "ON" or "OFF"|
+
 ### ModuleData
 
 |Name|Type|Mandatory|Additional|Description|