Invoking the Android System Service API

The Android system service application provides an API for the external applications to know the device firmware upgrade package status, download progress and to check if a new firmware upgrade is available. It also initiates new firmware upgrades and enables/disables Automatic Retry for firmware upgrades. To invoke these APIs, external applications should invoke the service exposed by the system service application and implement a BroadcastReceiver to receive results. Let's take a look at how it's done by following the subsections.

Configure the external application

Follow the steps given below to configure the external application:

1. In order to use this API, you need to sign the android application with the same key, which you have used to signed the EMM agent and the System service.
2. Add the uses-permission entry to the org.wso2.emm.system.service.permission.ACCESS to the manifest.xml file of the application.
3. Add the receiver to receive broadcasts from the Android system service application.

Take a look at the sample given below to understand how the above entries need to be added to your applications manifest.xml file.

<manifest ...>
    ...
    <uses-permission android:name="org.wso2.emm.system.service.permission.ACCESS"/>
    ...
    <application ...>
        ...
        <receiver android:name=.UpgradeServiceResponseReceiver>
            <intent-filter>
                <action android:name="org.wso2.emm.system.service.MESSAGE_PROCESSED"/>
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
        </receiver>
        ...
    </application>
</manifest>

Receiving the Broadcasts

Follow the steps given below to receive broadcasts from system service application.

1. Configure the BroadcastReceiver.

   UpgradeServiceResponseReceiver.java

   public class UpgradeServiceResponseReceiver extends BroadcastReceiver {
      @Override
      public void onReceive(Context context, Intent intent) {
            String operation = intent.getStringExtra(“operation”); //The operation result broadcast belongs
            String code = intent.getStringExtra(“code”); //Status code (200 for success, 300 for pending and 400 for failures)
            String status = intent.getStringExtra(“status”); //Sub status of the broadcast for more details.
            //Optional message or stringified JSON data related to the sub status.
            String payload = intent.getStringExtra(“payload”); 
            //Your result manipulation code goes here
      }
   }

2. Register a receiver in your activity or service to listen to the service results. 

   IntentFilter filter = new IntentFilter(“org.wso2.emm.system.service.MESSAGE_PROCESSED”);
   filter.addCategory(Intent.CATEGORY_DEFAULT);
   UpgradeServiceResponseReceiver receiver = new UpgradeServiceResponseReceiver();
   registerReceiver(receiver, filter);

Supported broadcasts

The Systems Service uses the following broadcast codes to indicate success, pending and failure status.

The following states are defined in the broadcasts to identify specific sub status related to the above status codes.

Broadcast operations, code, and the status descriptions.

{
"progress":<PROGRESS VALUE>
}

{
"progress":<PROGRESS VALUE>
}

{
"buildDate":<UTC DATE & TIME>
}

{  
   "size":<UPGRADE PACKAGE SIZE>,
   "release":<RELEASE CODE>,
   "version":<VERSION CODE>,
   "description":<DESCRIPTION>
}

Invoking the API

Follow the steps given below to invoke the API by starting the exposed service.

1. Create an explicit intent method.

   public static Intent createExplicitFromImplicitIntent(Context context, Intent implicitIntent) {
     //Retrieve all services that can match the given intent
     PackageManager pm = context.getPackageManager();
     List<ResolveInfo> resolveInfo = pm.queryIntentServices(implicitIntent, 0);
   
     //Make sure only one match was found
     if (resolveInfo == null || resolveInfo.size() != 1) {
        return null;
     }
   
     //Get component info and create ComponentName
     ResolveInfo serviceInfo = resolveInfo.get(0);
     String packageName = serviceInfo.serviceInfo.packageName;
     String className = serviceInfo.serviceInfo.name;
     ComponentName component = new ComponentName(packageName, className);
   
     //Create a new intent. Use the old one for extras and such reuse
     Intent explicitIntent = new Intent(implicitIntent);
   
     //Set the component to be explicit
     explicitIntent.setComponent(component);
   
     return explicitIntent;
   }

2. Call the service. 

   This should always happen after registering the receiver. Else, you will not receive the results of your API call from the systems service.

   Intent intent =  new Intent(“org.wso2.emm.system.service.START_SERVICE”);
   Intent explicitIntent = createExplicitFromImplicitIntent(context, intent);
   if (explicitIntent != null) {
     intent = explicitIntent;
   }
   intent.putExtra("operation", <Operation code>); //Operation code which need to perform
   intent.putExtra("command", <Commands for the operation>); //Optional command string which might required for the particular operation.
   startService(intent); //Start the service with intent

Supported operations by the API

After calling to below operations System Service will send a broadcast with the response. Please check the Broadcast operations, code, and the status descriptions section for the corresponding responses.

{  
   "schedule":<ISO 8601 DATA & TIME>,
   "server":<OTA SERVER URL>,
   "autoRetry":<TRUE or FALSE>
}

{
"server": <OTA server URL>
}