Create your own Intents

Introduction

This documentation describes how you can communicate with the NIMMSTA App and the HS-50 scanner without using our Intent Library.

Android Manifest

The following needs to be added to the Android Manifest File in order to be able to send Intents to the NIMMSTA App.

AndroidManifest.xml

<!-- Permission to send intents to NIMMSTA App -->
<uses-permission android:name="com.nimmsta.intent.SERVICE" />

<!-- Android 11+ requires query entries to use intents -->
<queries>
  <package android:name="com.nimmsta" />
  <package android:name="com.nimmsta.core.android.intents.NIMMSTAIntentService" />
  <intent>
    <action android:name="com.nimmsta.intent.SEND" />
  </intent>
</queries>

Bind NIMMSTA Intent Service (Supported from NIMMSTA App v7+)

Before you can send intents to the NIMMSTA App you have to bind the NIMMSTA Intent Service.

KotlinJava

class MainActivity : Activity() {
    /* ... */

    private fun bindIntentService() {
        val intent = Intent()
        // com.nimmsta might be replaced with com.nimmsta.intent or your custom package name
        intent.component =
            ComponentName("com.nimmsta", "com.nimmsta.core.android.intents.NIMMSTAIntentService")
        applicationContext.bindService(intent, object : ServiceConnection {
            override fun onServiceConnected(name: ComponentName, service: IBinder) {
                // connected
            }

            override fun onServiceDisconnected(name: ComponentName) {
                // disconnected
            }
        }, BIND_AUTO_CREATE)
    }
}

public class MainActivity extends Activity {
    /* ... */

    private void bindIntentService() {
        Intent intent = new Intent();
        // com.nimmsta might be replaced with com.nimmsta.intent or your custom package name
        intent.setComponent(new ComponentName("com.nimmsta", "com.nimmsta.core.android.intents.NIMMSTAIntentService"));
        getApplicationContext().bindService(intent, new ServiceConnection() {
            @Override
            public void onServiceConnected(ComponentName name, IBinder service) {
                // connected
            }

            @Override
            public void onServiceDisconnected(ComponentName name) {
                // disconnected
            }
        }, BIND_AUTO_CREATE);
    }
}

Start NIMMSTA Intent Service (Deprecated from v7 of NIMMSTA App)

Before you can send intents to the NIMMSTA App you have to start the NIMMSTA Intent Service.

Note

Please make sure you install the NIMMSTA App before you install your app. Otherwise, the permissions are not correctly obtained.

KotlinJava

private fun startNIMMSTAIntentService() {
  val intent = Intent()
  intent.component = ComponentName("com.nimmsta", "com.nimmsta.core.android.intents.NIMMSTAIntentService")
  val serviceName = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    startForegroundService(intent)
  } else {
    startService(intent)
  }
  if (serviceName == null) {
    Toast.makeText(
      this,
      "Could not start NIMMSTA Intent service. Is the NIMMSTA APP installed?",
      Toast.LENGTH_LONG
    ).show()
    throw Throwable("Could not start NIMMSTA Intent service. Is the NIMMSTA APP installed?")
  }
}

private void startNIMMSTAIntentService() {
  Intent intent = new Intent();
  intent.setComponent(new ComponentName("com.nimmsta", "com.nimmsta.core.android.intents.NIMMSTAIntentService"));
  ComponentName serviceName;
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    serviceName = startForegroundService(intent);
  } else {
    serviceName = startService(intent);
  }
  if (serviceName == null) {
    Toast.makeText(
      this,
      "Could not start NIMMSTA Intent service. Is the NIMMSTA APP installed?",
      Toast.LENGTH_LONG
    ).show();
    throw new Throwable("Could not start NIMMSTA Intent service. Is the NIMMSTA APP installed?");
  }
}

Create Intent

To send Intents to the NIMMSTA App an intent has to be created the following way. The json in the extra called "data" needs to follow the same structure as the json that is used by the websocket communication. To learn more about the json structure head over to Protocol Overview.

KotlinJava

val intent = Intent("com.nimmsta.intent.RECEIVE")
intent.putExtra("data", json.toString())
this.sendBroadcast(intent)

Intent intent = new Intent("com.nimmsta.intent.RECEIVE");
intent.putExtra("data", json.toString());
this.sendBroadcast(intent);

Receive Responses

A BroadcastReceiver hast to be registered the following way to receive responses from your sent intents.

KotlinJava

val intentFilter = IntentFilter()
intentFilter.addAction("com.nimmsta.intent.SEND")
val receiver = YourBroadcastReceiver(this)
registerReceiver(receiver, intentFilter)

IntentFilter intentFilter = new IntentFilter();
intentFilter.addAction("com.nimmsta.intent.SEND");
YourBroadcastReceiver receiver = new YourBroadcastReceiver(this);
registerReceiver(receiver, intentFilter);

The responses can be received by the BroadcastReceiver the following way. The structure of the responses is also discussed in Protocol Overview.

KotlinJava

override fun onReceive(context: Context?, intent: Intent?) {
  // There is an extra in the intent called data which has a json string as it's content
  val data = intent.extras?.getString("data")
}

@Override
public void onReceive(Context context, Intent intent) {
  // There is an extra in the intent called data which has a json string as it's content
  String data = intent.getExtras().getString("data");
  try {
    JSONObject json = new JSONObject(data);
  } catch (JSONException e) {
    e.printStackTrace();
  }
}