Scanner Input Plug-in

DataWedge 14.1

SCANNER_INPUT_PLUGIN

Used to enable/disable the Barcode Input Plug-in being used by the currently active Profile to scan barcodes. Disabling the Barcode Input Plug-in effectively disables scanning for that Profile, even if the Profile is associated with an app. This API is only functional when Barcode Input is enabled in the active Profile and only affects the runtime status of the scanner; it does not make persistent changes to the Profile.

Note: Zebra recommends using SUSPEND_PLUGIN and RESUME_PLUGIN for apps that require rapid toggling of barcode scanning across different activities within the same app.

Function Prototype

Intent i = new Intent();
i.setAction("com.symbol.datawedge.api.ACTION");
i.putExtra("com.symbol.datawedge.api.SCANNER_INPUT_PLUGIN", "<parameter>");

Parameters

ACTION [String]: "com.symbol.datawedge.api.ACTION"

EXTRA_DATA [String]: "com.symbol.datawedge.api.SCANNER_INPUT_PLUGIN"

<parameter>: The parameter as a string, using either of the following:

  • SUSPEND_PLUGIN - suspends the scanner so it is temporarily inactive when switching from the WAITING or SCANNING state. SCANNER_STATUS notification broadcasts IDLE state.
  • RESUME_PLUGIN - resumes the scanner when changing from the SUSPEND_PLUGIN suspended state. SCANNER_STATUS notification broadcasts WAITING and SCANNING states, rotating between each depending on whether scanning is taking place. In the WAITING state it is expecting an action from the user such as a trigger press. In the SCANNING state it is actively performing a scan resulting from an action such as a trigger press.
  • ENABLE_PLUGIN - enables the plug-in; scanner becomes active. SCANNER_STATUS notification broadcasts WAITING and SCANNING states, rotating between each depending on whether scanning is taking place.
  • DISABLE_PLUGIN - disables the plug-in; scanner becomes inactive. SCANNER_STATUS notification broadcasts DISABLED state.

Using SUSPEND_PLUGIN/RESUME_PLUGIN: This is useful when an app requires the scanner to be suspended or temporarily de-activated. When the scanner is activated (for example from a profile configuration or from RESUME_PLUGIN or ENABLE_PLUGIN intent API), SCANNER_STATUS notification broadcasts the WAITING and SCANNING states, rotating between each depending on whether scanning is taking place. For the app to suspend scanning, act only when in the SCANNING and WAITING states - when these states are broadcasted, use SUSPEND_PLUGIN parameter to remain in the suspended state and keep the scanner unusable. Once scanning is suspended, SCANNER_STATUS broadcasts the IDLE state. Use RESUME_PLUGIN to re-activate the scanner.

Important: To avoid the unnecessary use of enable/disable scanner API calls, Zebra recommends that apps register to be notified of changes in scanner status using GET_SCANNER_STATUS API or SCANNER_STATUS from REGISTER_FOR_NOTIFICATION API. This enables apps to receive scanner status change notifications immediately rather than having to query and wait for the result - therefore the app is aware of the current status prior to making any status change. Status change notifications include the active Profile name, which permits an app to use the enable/disable scanner API calls only when status changes affect a relevant profile.

Result Codes

DataWedge returns the following error codes if the app includes the intent extras SEND_RESULT and COMMAND_IDENTIFIER to enable the app to get results using the DataWedge result intent mechanism. See Example, below.

  • SCANNER_ALREADY_SUSPENDED - An intent was received to suspend the scanner which is already suspended.
  • PLUGIN_DISABLED - The scanner plug-in is disabled so the suspend/resume action cannot be executed.
  • SCANNER_ALREADY_RESUMED - A resume intent is received but the scanner is not in a suspended state.
  • SCANNER_RESUME_FAILED - The scanner resume is unsuccessful.
  • SCANNER_ALREADY_DISABLED - The scanner is in a disabled state, preventing any further action.
  • DATAWEDGE_DISABLED - The action to disable DataWedge is unsuccessful.
  • PARAMETER_INVALID - An invalid parameter is received.
  • PROFILE_DISABLED - The action to to disable profile is unsuccessful.
  • SCANNER_ALREADY_DISABLED - An intent was received to disable the scanner which is already disabled.
  • SCANNER_ALREADY_ENABLED - An intent was received to enable the scanner which is already enabled.
  • SCANNER_DISABLE_FAILED - The scanner disable is unsuccessful.
  • SCANNER_ENABLE_FAILED - The action to enable the scanner is unsuccessful.

Also see the Result Codes guide for more information.

Example Code

Send suspend and resume intents:

private void suspendScanner() {
    Intent i = new Intent();
    i.setAction("com.symbol.datawedge.api.ACTION");
    i.putExtra("com.symbol.datawedge.api.SCANNER_INPUT_PLUGIN", "SUSPEND_PLUGIN");
    i.putExtra("SEND_RESULT", "true");
    i.putExtra("COMMAND_IDENTIFIER", "MY_SUSPEND_SCANNER");  //Unique identifier
    this.sendBroadcast(i);
}

private void resumeScanner() {
    Intent i = new Intent();
    i.setAction("com.symbol.datawedge.api.ACTION");
    i.putExtra("com.symbol.datawedge.api.SCANNER_INPUT_PLUGIN", "RESUME_PLUGIN");
    i.putExtra("SEND_RESULT", "true");
    i.putExtra("COMMAND_IDENTIFIER", "MY_RESUME_SCANNER");  //Unique identifier
    this.sendBroadcast(i);
}

Enable/Disable Scanner Input Plugin:

private void enableScanner() {
    Intent i = new Intent();
    i.setAction("com.symbol.datawedge.api.ACTION");
    i.putExtra("com.symbol.datawedge.api.SCANNER_INPUT_PLUGIN", "ENABLE_PLUGIN");
    i.putExtra("SEND_RESULT", "true");
    i.putExtra("COMMAND_IDENTIFIER", "MY_ENABLE_SCANNER");  //Unique identifier
    this.sendBroadcast(i);
}

private void disableScanner() {
    Intent i = new Intent();
    i.setAction("com.symbol.datawedge.api.ACTION");
    i.putExtra("com.symbol.datawedge.api.SCANNER_INPUT_PLUGIN", "DISABLE_PLUGIN");
    i.putExtra("SEND_RESULT", "true");
    i.putExtra("COMMAND_IDENTIFIER", "MY_DISABLE_SCANNER");  //Unique identifier
    this.sendBroadcast(i);
}

Generate and receive result codes

Command and configuration intent parameters determine whether to send result codes (disabled by default). When using SEND_RESULT, the COMMAND_IDENTIFIER is used to match the result code with the originating intent. Sample usage of these parameters is shown below.

Note: Modify this generic code to match the API being used.

Receive the suspend/resume command result:

//call in onResume() method
private void registerReceivers() {
    IntentFilter filter = new IntentFilter();
    filter.addAction("com.symbol.datawedge.api.RESULT_ACTION");
    filter.addCategory(Intent.CATEGORY_DEFAULT);
    registerReceiver(receiver, filter);
}

//call in onPause() method
private void unRegisterReceivers() {
    unregisterReceiver(receiver);
}

BroadcastReceiver receiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        //Get result of the suspend/resume API call
        String action = intent.getAction();
        if (action != null && action.equals("com.symbol.datawedge.api.RESULT_ACTION")) {
            Bundle extras = intent.getExtras();
            if (extras != null) {
                //user specified ID
                String cmdID = extras.getString("COMMAND_IDENTIFIER");
                if ("MY_RESUME_SCANNER".equals(cmdID) || "MY_SUSPEND_SCANNER".equals(cmdID)) {
                    //success or failure
                    String result = extras.getString("RESULT");
                    //Original command
                    String command = extras.getString("COMMAND");
                    if ("FAILURE".equals(result)) {
                        Bundle info = extras.getBundle("RESULT_INFO");
                        String errorCode = "";

                        if (info != null) {
                            errorCode = info.getString("RESULT_CODE");
                        }
                        Log.d(TAG, " Command:" + command + ":" + cmdID + ":" + result + ",Code:" + errorCode);
                    }
                    else {
                        Log.d(TAG, " Command:" + command + ":" + cmdID + ":" + result);
                    }
                }
            }
        }
    }
};

Receive the Enable/Disable Plug-in result:

// send the intent
Intent i = new Intent();
i.setAction("com.symbol.datawedge.api.ACTION");
// Use "ENABLE_PLUGIN" or "DISABLE_PLUGIN"
i.putExtra("com.symbol.datawedge.api.SCANNER_INPUT_PLUGIN", "ENABLE_PLUGIN");

// request and identify the result code
i.putExtra("SEND_RESULT","true");
i.putExtra("COMMAND_IDENTIFIER","123456789");
this.sendBroadcast(i);

// register to receive the result
public void onReceive(Context context, Intent intent){

    String command = intent.getStringExtra("COMMAND");
    String commandidentifier = intent.getStringExtra("COMMAND_IDENTIFIER");
    String result = intent.getStringExtra("RESULT");

    Bundle bundle = new Bundle();
    String resultInfo = "";
    if(intent.hasExtra("RESULT_INFO")){
        bundle = intent.getBundleExtra("RESULT_INFO");
        Set<String> keys = bundle.keySet();
        for (String key: keys) {
            resultInfo += key + ": "+bundle.getString(key) + "\n";
        }
    }

    String text = "Command: "+command+"\n" +
                      "Result: " +result+"\n" +
                      "Result Info: " +resultInfo + "\n" +
                      "CID:"+commandidentifier;

    Toast.makeText(context, text, Toast.LENGTH_LONG).show();

};

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