App Service Provider Guide

Terms and Abbreviations

App Service RPCs

There are currently four RPCs related to app services which must be supported by every ASP:

PublishAppService

Direction: ASP -> Core

This request is sent by the ASP to initially create the service. This is where the service's manifest is defined, which includes the type of data provided by the service as well as what RPCs can be handled by the service.

GetAppServiceData

Direction: ASC -> Core -> ASP

Note

The ASP can receive this message only when its service is active.

This request is sent to the ASP when an ASC sends this message. The ASP is expected to respond to this message with its most recent service data.

OnAppServiceData

Direction: ASP -> Core -> ASC

Note

The ASP is expected to send this message only when its service is active.

This notification is expected to be sent by the ASP whenever there are any significant changes to its service data or if its service becomes active. Core will forward this message to any ASCs that have subscribed to data for this service type.

PerformAppServiceInteraction

Direction: ASC -> Core -> ASP

Note

This ASP can receive this message regardless of whether its service is active, since it is directed at a specific service.

This request is sent to the ASP when an ASC sends this message with the ASP's specific service ID. This indicates that the ASC wishes to perform a service-specific function on the ASP. The API for such interactions must be defined by the ASP separately. The ASP is expected to process this message and respond with SUCCESS or return an error response if the interaction was not successful.

RPC Passing

There are a number of existing RPCs which are allowed to be handled by the ASP based on service type:

MEDIA

• ButtonPress with the following values for buttonName
  • OK
  • PLAY_PAUSE
  • SEEKLEFT
  • SEEKRIGHT
  • TUNEUP
  • TUNEDOWN
  • SHUFFLE
  • REPEAT

WEATHER

N/A

NAVIGATION

• SendLocation
• GetWayPoints

Flow

When RPC passing is performed with a request which relates to several components (such as ButtonPress), not all uses of this RPC will be intended for this service. As such, it is expected that the ASP will indicate when they are unable to process a specific instance of an RPC by responding with an UNSUPPORTED_REQUEST response code. This informs Core that it should pass this specific request to another component or app service that handles this RPC.

This "Waterfall" flow used by Core during RPC passing is defined as follows:

1. App1 sends an RPC request to Core
2. Core checks if there is an active service which handles this RPC's function ID (ignoring any services which have already received this message)
   • If found, go to step 3
   • If not found, go to step 4
3. Core passes the raw message to the ASP, waits for a response
   • If the request times out before receiving a response, return to step 2
   • If the ASP responds with result code UNSUPPORTED_REQUEST (indicating that it cannot handle some part of the request), return to step 2
   • If the ASP responds with a normal result code, go to step 5
4. Core handles the RPC normally, generates a response
5. Core sends the RPC response to App1

Validation

When Core passes an RPC to a ASP according to its handledRPCs list, it performs no additional processing on the message. This means that there is no guarantee that this message is valid according to the RPC Spec. This approach is taken specifically for forward-compatibility reasons, in case the ASP supports a newer version of the RPC Spec than Core (which could include breaking changes). As a consequence, the ASP will need to perform validation on this message itself.

Validation steps for existing passthrough RPCs:

1. Validate bounds and types of existing parameters against the RPC spec
2. Verify that mandatory parameters are present
3. For ButtonPress, verify that the buttonName is correctly tied to the moduleType

Policies

With regards to permission handling during RPC passing:

• For RPCs which are known to Core (determined by its RPC spec version), they are checked normally against the policy table. As such, the ASP can assume in this case that the app specifically has permissions to use the this RPC in its current HMI level.
• For RPCs unknown to Core, an ASC needs to be granted specific permissions by the OEM (controlled by the allow_unknown_rpc_passthrough policy field) to send this message, even if it is handled by the ASP.