Switch to Profile

SWITCH_TO_PROFILE

Used to switch an application's association to a specified Profile. An app cannot be associated to more than one Profile, and the specified Profile must not already be associated with another app. Zebra recommends registering for profile switch notifications to identify when the profile switch is complete. This API will not function if the specified Profile does not exist or is already associated with an application.

CAUTION: Switching to a disabled Profile is not allowed if the GET_IGNORE_DISABLED_PROFILES API returns "true."

Profiles Recap

DataWedge operates using Profiles and Plug-ins. A Profile contains information about how DataWedge interacts with a specific application and includes:

• Associated application
• Input plug-in configurations
• Process plug-in configurations
• Output plug-in configurations

DataWedge includes a default Profile, Profile0, automatically created the first time DataWedge runs. Profiles allow each application to have a tailored DataWedge configuration. For example, each user application can have a Profile that outputs scanned data in the required format when that application is active in the foreground. DataWedge can be configured to process the same captured data differently based on the requirements of each application.

Note: A single Profile can be associated with one or more activities or apps, but an activity can only be associated with one Profile. DataWedge enforces a one-to-one relationship between Profiles and activities; a Profile can only be associated with a single activity. When a Profile is created, it is not associated with any application and will not activate until it is associated to an app. This allows the creation of multiple unassociated Profiles. This API function is used to activate such Profiles.

Usage Scenario

Consider an application with two activities: ActivityA, which requires scanning EAN13 barcodes, and ActivityB, which requires MSR card data. ProfileA is configured for EAN13 barcodes and is unassociated. ProfileB is configured for MSR input and is also left unassociated. When ActivityA launches, it uses SWITCH_TO_PROFILE to activate ProfileA. Similarly, when ActivityB launches it uses SWITCH_TO_PROFILE to activate ProfileB.

When another activity or app becomes active in the foreground, DataWedge automatically switches to the appropriate Profile, either default or associated. When ActivityA (or ActivityB) returns to the foreground, it will use SWITCH_TO_PROFILE to return the Profile to ProfileA (or ProfileB), respectively.

For example, if ProfileA is unassociated and ProfileB is associated with activity B, using SWITCH_TO_PROFILE to switch to ProfileA will keep it active while activity A is in the foreground. When activity B becomes active in the foreground, DataWedge automatically switches to ProfileB. When activity A resumes, the app must use SWITCH_TO_PROFILE in the onResume method to switch back to ProfileA.

Notes

• Since DataWedge automatically switches Profile when an activity is paused, Zebra recommends calling this API from the onResume method of the activity.
• After switching to a Profile, an unassociated Profile remains unassigned and can be used by other apps/activities later.
• For backward compatibility, DataWedge’s automatic Profile switching unaffected by the these API commands, which is the reason why the commands work only with unassociated Profiles and apps.
• DataWedge's automatic Profile switching functions as follows, every second:
  • Sets newProfileId to the Profile ID associated with the current foreground activity.
  • If no associated Profile is found, sets newProfileId to the Profile ID associated with the current foreground app.
  • If no associated Profile is still found, sets newProfileId to the current default Profile (which MAY NOT be Profile0).
  • Compares newProfileId with currentProfileId. If they differ:
    • Deactivates the current Profile
    • Activates the new Profile (newProfileId)
    • Sets currentProfileId to newProfileId

Function Prototype

Intent i = new Intent();
i.setAction("com.symbol.datawedge.api.ACTION");
i.putExtra("com.symbol.datawedge.api.SWITCH_TO_PROFILE", "<profile name>");

Parameters

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

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

<profile name>: The Profile name (a case-sensitive string) to set as the active 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.

• PROFILE_HAS_APP_ASSOCIATION - FAILURE
• PROFILE_NOT_FOUND - FAILURE
• PROFILE_ALREADY_SET - FAILURE
• PROFILE_NAME_EMPTY - FAILURE
• DATAWEDGE_DISABLED - FAILURE

Also see the Result Codes guide for more information.

Example Code

// define action and data strings
String switchToProfile = "com.symbol.datawedge.api.ACTION";
String extraData = "com.symbol.datawedge.api.SWITCH_TO_PROFILE";

public void onResume() {
        super.onResume();

        // create the intent
        Intent i = new Intent();

        // set the action to perform
        i.setAction(switchToProfile);

        // add additional info
        i.putExtra(extraData, "myProfile");

        // send the intent to DataWedge
        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.

// send the intent
    Intent i = new Intent();
    i.setAction(ACTION);
    i.putExtra("com.symbol.datawedge.api.CREATE_PROFILE", "Profile1");

// 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