Using DataWedge APIs - Zebra Technologies TechDocs

Overview

DataWedge APIs operate primarily through Android intents--specific commands that can be used by other applications to control data capture without the need to directly access the underlying hardware APIs. This guide describes the functionality of the intents supported by DataWedge and their effects on data capture and DataWedge Profiles and settings.

In DataWedge versions prior to 6.2, applications access DataWedge APIs by broadcasting an intent, and use the primary pieces of information in the intent (action and data) to specify which API function to perform. DataWedge 6.2 and later implement intents as extras of an action intent, permitting multiple API calls to be sent as extras using a single intent action.

To learn more about DataWedge APIs, read an excellent DataWedge APIs - Benefits & Usage Scenarios by Zebra engineer Darryn Campbell.

Requirements

The use of DataWedge APIs requires experience with Java programming and familiarity with Android Intents. It also requires knowledge of DataWedge usage, features and terminology. For more information about DataWedge, see the DataWedge Setup Guide and the Architecture Overview. It also might be helpful to read the DataWedge section of the Integrator Guide included with Zebra devices.

Sending Intents

The new syntax defined in DataWedge 6.2 permits multiple DataWedge API calls as extras on a single intent action. The syntax is as follows:


// Send multiple intents as extras

    Intent i = new Intent();
    i.setAction("com.symbol.datawedge.api.ACTION");
    String[] profiles = {"MainInventory"};
    i.putExtra("com.symbol.datawedge.api.DELETE_PROFILE", profiles);
    i.putExtra("com.symbol.datawedge.api.GET_VERSION_INFO", "");

Receiving Results

For intents that query DataWedge for information (such as in "GET_ACTIVE_PROFILE"), the app must register to receive the result with a filter that identifies the action and category of the result intent. The code below shows how to register the broadcast receiver to receive the results:


// Register broadcast receiver and filter results

    void registerReceivers() {
        IntentFilter filter = new IntentFilter();
        filter.addAction("com.symbol.datawedge.api.RESULT_ACTION");
        filter.addCategory("android.intent.category.DEFAULT");
        registerReceiver(mybroadcastReceiver, filter);
    }

//Receiving the result

    private BroadcastReceiver myBroadcastReceiver = new BroadcastReceiver(){

    @Override
        public void onReceive(Context context, Intent intent){

            Bundle extras = getIntent().getExtras();
            if (intent.hasExtra("com.symbol.datawedge.api.RESULT_GET_ACTIVE_PROFILE")){
                String activeProfile = extras.getString("com.symbol.datawedge.api.RESULT_GET_ACTIVE_PROFILE");

Important: DataWedge API commands are not queued, and might be ignored if sent while DataWedge is busy processing an earlier intent. When an API command is sent, DataWedge executes the command only if it is not busy doing something else. Exceptions:

STOP_SCANNING - immediately interrupts a scan operation
DISABLE_PLUGIN - immediately disables the current scanner input plug-in

To help ensure proper execution, Zebra recommends inserting delay code prior to critical commands. See the SoftScanTrigger API for an example.

Nested Bundles

DataWedge 6.3 implements the concept of nested bundles, which allows a "bundle" of values to be included as one value in another bundle. Bundles also can be multiple layers deep. For example, the image below illustrates a PARAM_LIST bundle nested within the PLUGIN_CONFIG[0] bundle nested within the API call SET_CONFIG. Nesting is required to configure with intents the many parameters contained in a Profile.

The image further illustrates that the SET_CONFIG API call can implement a second nested bundle, PLUGIN_CONFIG[n], which can contain its own PARAM_LIST.

Example

The Java code below implements a nested bundle.

//Using the SET_CONFIG API and a nested bundle.


Bundle bMain = new Bundle();
bMain.putString("PROFILE_NAME","Profile2");
bMain.putString("PROFILE_ENABLED", "true");
bMain.putString("CONFIG_MODE","CREATE_IF_NOT_EXIST");
bMain.putString("RESET_CONFIG", "true");


Bundle bundleApp1 = new Bundle();
bundleApp1.putString("PACKAGE_NAME","com.symbol.emdk.simulscansample1");
bundleApp1.putStringArray("ACTIVITY_LIST", new String[]{
        "com.symbol.emdk.simulscansample1.DeviceControl",
        "com.symbol.emdk.simulscansample1.MainActivity",
        "com.symbol.emdk.simulscansample1.ResultsActivity.*",
        "com.symbol.emdk.simulscansample1.ResultsActivity2",
        "com.symbol.emdk.simulscansample1.SettingsFragment1"});


Bundle bundleApp2 = new Bundle();
bundleApp2.putString("PACKAGE_NAME","com.example.intents.datawedgeintent");
bundleApp2.putStringArray("ACTIVITY_LIST", new String[]{
        "com.example.intents.datawedgeintent.DeviceControl",
        "com.example.intents.datawedgeintent.MainActivity",
        "com.example.intents.datawedgeintent.ResultsActivity",
        "com.example.intents.datawedgeintent.SettingsFragment1"});

Bundle bundleApp3 = new Bundle();
bundleApp3.putString("PACKAGE_NAME","*");
bundleApp3.putStringArray("ACTIVITY_LIST", new String[]{"*"});


Bundle bundleApp4 = new Bundle();
bundleApp4.putString("PACKAGE_NAME","com.symbol.myzebraapp");
bundleApp4.putStringArray("ACTIVITY_LIST", new String[]{"*"});

bMain.putParcelableArray("APP_LIST", new Bundle[]{
        bundleApp1
        ,bundleApp2
        ,bundleApp3
        ,bundleApp4
});

Intent i = new Intent();
i.setAction("com.symbol.datawedge.api.ACTION");
i.putExtra("com.symbol.datawedge.api.SET_CONFIG", bMain);
this.sendBroadcast(i);

Related Guides:

SEE ALSO:

Zebra Support Central | Integrator Guides, Product Manuals, Software Downloads and Support

LaunchPad | Zebra Developer Community

Intent | Android Developers

Intents and Intent Filters | Android Developers

Android Intents | Tutorial