1# Interacting with Nanoapps from Client Code 2 3[TOC] 4 5Code that interacts with a nanoapp, for example within an Android app, is known 6as the *client* of the nanoapp. There are two ways to interact with nanoapps 7from the host (application processor): (1) Java (above the Context Hub HAL, from 8the Android framework or an APK), and (2) native vendor code (beneath the 9Context Hub HAL). Most clients, especially those with a UI component, should use 10the Java method, unless a vendor-partition native implementation is required 11(e.g. if interacting with a nanoapp is used to implement a different HAL, or if 12communication with other beneath-HAL modules is required). 13 14Interaction between nanoapps and clients occur through a flexible message 15passing interface. Refer to the Nanoapp Developer Guide for recommendations on 16how to design a protocol for use with a nanoapp. 17 18## Java APIs 19 20CHRE is exposed to Android apps holding the appropriate permissions through the 21[ContextHubManager](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/hardware/location/ContextHubManager.java) 22and the associated 23[ContextHubClient](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/hardware/location/ContextHubClient.java) 24system APIs. 25 26To use the above APIs, your application must have access to the 27`ACCESS_CONTEXT_HUB` permission, which is restricted to `signature|privileged`. 28This permission must be declared in the app’s [Android 29Manifest](https://developer.android.com/guide/topics/manifest/uses-permission-element), 30and is only granted to APKs that are signed with the same key as the platform 31(“signature” scope) or are preinstalled in the privileged apps folder *and* are 32present on the [privileged permission 33whitelist](https://source.android.com/devices/tech/config/perms-whitelist). 34 35The recommended flow for Java nanoapp client code is as follows: 36 371. Retrieve the ContextHubManager object via 38 `Context.getSystemService(ContextHubManager.class)` - this will produce a 39 valid handle if the device supports `FEATURE_CONTEXT_HUB` as indicated by 40 `PackageManager.hasSystemFeature()` 412. Retrieve a reference to a Context Hub via 42 `ContextHubManager.getContextHubs()` 433. Confirm that the nanoapp is loaded and retrieve its version number by calling 44 `ContextHubManager.queryNanoApps()` 454. If the nanoapp was found, create a `ContextHubClient` object through 46 `ContextHubManager.createClient()`. This can be used to communicate with your 47 nanoapp, and receive notifications of system events like reset. Note that the 48 `createClient()` API supports two modes of operation, which define how events 49 and data are passed to the client: direct callback with 50 `ContextHubClientCallback` (requires a persistent process), or 51 `PendingIntent` with `ContextHubIntentEvent` (can start an app’s process when 52 an event occurs). To send messages to the nanoapp, use 53 `ContextHubClient.sendMessageToNanoApp()`. 54 55## Vendor Native 56 57Depending on the details of the platform implementation, you may also be able to 58interact with CHRE directly, beneath the Context Hub HAL, by using socket IPC as 59exposed by the CHRE daemon reference implementation. This approach has some 60advantages, like being able to interact with system nanoapps that are not 61exposed at the Java level, and it can be used with other low-level beneath-HAL 62code. However, it is not suitable for use from native code within an Android 63app. 64 65See `host/common/test/chre_test_client.cc` for an example of how to use this 66interface. Note that SELinux configuration is generally required to whitelist 67access to the CHRE socket. 68 69