Skip to content

Installed App Webservice Connection

Use NIMMSTAWebServiceConnection when your Android app should bind to the WebService of an installed NIMMSTA app on the same device.

This is useful when:

  • your app wants local Web Library or Websocket access without embedding the Core Android webservice itself
  • you already use the Intent Library and want the same installed-app package resolution for the webservice
  • you want one helper that supports Standard App, Intent App, Webserver App, and an optional preferred custom package

Resolution Order

NIMMSTAWebServiceConnection.bindServiceToContext(...) tries these packages in order:

  1. Preferred custom package, if configured
  2. Standard App: com.nimmsta
  3. Intent App: com.nimmsta.intent
  4. Webserver App: current builds also use com.nimmsta

You can configure the preferred package once through NIMMSTAService.preferredPackageName.

NIMMSTAService.preferredPackageName = "custom"
// or use the full package:
// NIMMSTAService.preferredPackageName = "com.nimmsta.custom"

NIMMSTAService.setPreferredPackageName("custom");
// or:
// NIMMSTAService.setPreferredPackageName("com.nimmsta.custom");

Manifest Notes

The Intent Library manifest already queries com.nimmsta and com.nimmsta.intent. Current Webserver App builds also use com.nimmsta.

If you use a custom package, add it to your app manifest as well:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <queries>
        <package android:name="com.nimmsta.custom" />
    </queries>
</manifest>

Basic Usage

class MainActivity : AppCompatActivity() {
    private var webServiceConnection: NIMMSTAWebServiceConnection? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        webServiceConnection = NIMMSTAWebServiceConnection
            .bindServiceToContext(applicationContext)
            .onSuccess { connection ->
                // connected to the installed app's WebService
            }
            .onError { throwable ->
                Toast.makeText(this, throwable.message, Toast.LENGTH_LONG).show()
            }
    }

    override fun onDestroy() {
        webServiceConnection?.close()
        super.onDestroy()
    }
}

public class MainActivity extends AppCompatActivity {
    private NIMMSTAWebServiceConnection webServiceConnection;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        webServiceConnection = NIMMSTAWebServiceConnection
            .bindServiceToContext(getApplicationContext())
            .onSuccess(connection -> {
                // connected to the installed app's WebService
            })
            .onError(throwable -> {
                Toast.makeText(this, throwable.getMessage(), Toast.LENGTH_LONG).show();
            });
    }

    @Override
    protected void onDestroy() {
        if (webServiceConnection != null) {
            webServiceConnection.close();
        }
        super.onDestroy();
    }
}

Inspect the Connected Target

If you need to know which installed app was selected, inspect connectedCandidate.

webServiceConnection = NIMMSTAWebServiceConnection
    .bindServiceToContext(applicationContext)
    .onSuccess { connection ->
        val packageName = connection.connectedCandidate?.packageName
        val appType = connection.connectedCandidate?.appType
    }

webServiceConnection = NIMMSTAWebServiceConnection
    .bindServiceToContext(getApplicationContext())
    .onSuccess(connection -> {
        String packageName = connection.getConnectedCandidate() != null
            ? connection.getConnectedCandidate().getPackageName()
            : null;
        NIMMSTAInstalledAppType appType = connection.getConnectedCandidate() != null
            ? connection.getConnectedCandidate().getAppType()
            : null;
    });