Intent Manager

Note: To display only the features present on a particular device, select one or more filters from the SmartDocs bar below.

StageNow - 2.10

Overview

The Intent CSP allows an application to communicate with other applications using Android Intents, which provide a facility for performing late runtime binding between applications. This general-purpose mechanism includes a rich set of methods in the Android Intent Class to customize the Intent to meet the requirements of the application to which it is being sent. The most common use of Intents is to launch application Activities.

Highly complex Intents can be created using Java code, but it would be impractical for the Intent to attempt to describe every possible Intent. Instead, the most common use cases (of launching application Activities) are supported along with a modest capability to attach data items to cover other common use cases.

In Android, an Intent is an abstract description of an operation to be performed. Intents must be created and sent using one of the following APIs:

  • StartActivity launches an Activity within an application. This is usually used to perform a particular function of the user interface, such as selecting a contact name, and in such cases could return a result (the contact).
  • BroadcastIntent notifies one or more listener applications about the occurrence of some event, such as an external power supply being connected.
  • StartService starts a Service, which can continue to run in the background even after the component that started it is destroyed.

An Intent can be defined as a data structure that specifies an operation to be performed, and the data required to perform that operation. An Intent may consist of an action to specify the operation to be performed, data to be operated upon, and extra data items of various types to qualify the operation to be performed. Intents are defined by indicating how the Intent should be sent, specifying an Android action name, URI and MIME type of the primary data, and by attaching extra data items.

Note: The Intent feature is not designed to create and send highly complex Intents, especially those that require numerous extra data items or those with complex data types. If complex Intents are required, Zebra recommends creating and packaging them as a Java app, and launching that application using a simpler Intent.

Intent Types

Explicit Intents

An Explicit Intent is directed to a specific application. It requests that application--and only that application--to perform the requested operation. An Explicit Intent can be sent using any of the available methods, but most commonly use the startActivity or startService methods to direct it to an Activity or Service within a specific application.

If an Intent specifies a Package Name and Class Name, it is considered an Explicit Intent because it will be sent only to the specific application identified by the Package Name and Class Name. An Explicit Intent will fail if an application with the specified Package Name and Class Name is not installed. An Explicit Intent can, but is not required to, specify additional information to tell the receiving application how to perform the requested operation.

Implicit Intents

An Implicit Intent is a generic request to perform an operation that does not specify which application or applications should perform that operation. An Implicit Intent may be sent using any of the available methods, but is most commonly sent using broadcastIntent to request an unspecified number of registered receivers to perform an operation.

If an Intent does not specify a Package Name and Class Name, it is considered an Implicit Intent because it does not specify a specific application to which it will be sent. An Implicit Intent may fail if there are no suitable registered receiver(s). An Implicit Intent must specify at least some information to tell the receiving application(s) about the operation to perform and how to perform it.

**Important: Implicit Intents will no longer be supported by the Intent CSP beginning with Andriod 7.0 Nougat. Use explicit Intents only on devices running Android N and higher.

Main Functionality

  • Specify how the Intent will be sent:
    • StartActivity
    • BroadcastIntent
    • StartService
  • Enroll a Device Owner
  • Specify the Android Action name of the operation to be performed
  • Specify the URI and MIME Type of the primary data
  • Attach up to 5 extra data items, of the following data types:
    • Standard Integer
    • Character
    • Character Sequence
    • Floating Point
    • Long Integer
    • Boolean
    • Short
    • Double Precision Floating Point
    • String
    • Single Byte Integer

Action

Used to specify the Action to be invoked in other application(s) by the Intent.

Parm Name: Action

Option Name Description Note Requires
1 StartActivity Sends an Intent using startActivity to invoke an Activity within an application.

MX: 4.1+

Android API: 1+

2 StartService Sends an Intent using startService to initiate operation of a background Service within an application.

MX: 4.1+

Android API: 1+

3 Broadcast Sends an Intent using broadcastIntent to invoke registered broadcast receivers (listeners) within one or more applications.

MX: 4.1+

Android API: 1+

4 EnrollDeviceOwner Sends an Intent to enroll the Device Owner (specified using Package and Class parameters) for provisioning and device management. Useful for bypassing the Android Setup Wizard and GMS welcome screens; also works with non-GMS devices.

MX: 6.5+

Android API: 24+

Action Name

Used to specify the name of the action to be performed by the receiver(s) of the Intent. Whenever possible, the specified Action Name should be chosen from among those known to be supported by the intended receiver(s). While many Android action names are predefined, new action names can be added, making the set of possible action names effectively unlimited. Any given receiver might honor only a small subset of action names.

Note: Since the set of possible Action Names is extensible, the Intent does not put specific restrictions on the Action Names that can be specified. However, Android rejects an Intent for which there is no suitable receiver. In addition, certain receivers might require permissions to be held by an application before sending Intents with certain Action Names. If an attempt is made to send an Intent that is rejected by the Android system or by a specific receiver, an error will be returned in the Result XML.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: The Action is NOT "Enroll Device Owner"

Parm Name: ActionName

Requires:

  • MX: 4.1+
  • Android API: 1+

Category

Used to specify the Android Category of the application to which the Intent will be sent. A Category and Action Name combine to form a "channel" to which an app can listen for intents that use the same combination. This has the effect of filtering out the "chatter" of other intents using different value pairs. An app's intent Category is defined in its AndroidManifest.xml file.

Parm value input rules:

  • String containing the Category of the target app

Shown if: The Action is NOT "Enroll Device Owner"

Parm Name: Category

Requires:

  • MX: 8.0+
  • Android API: 23+

Type

Used to specify the Package Type of the application to which the Intent will be sent. Specifying this parameter classifies the Intent as Explicit, and will result in a failure if no application with the specified Package Type is installed.

Parm value input rules:

  • String from 0 - 255 characters containing the Package Type of the target app

Shown if: The Action is NOT "Enroll Device Owner"

Parm Name: Type

Requires:

  • MX: 4.1+
  • Android API: 1+

Package

Used to specify the Package Name of the application to which the Intent will be sent. Specifying this parm classifies the Intent as Explicit, and will result in a failure if no application with the specified Package Name is installed. The Package Name and Class Name parms should always be used together to specify a class within an application.

Parm value input rules:

  • String from 1 - 255 characters containing the Package Name of the target app

Shown if: The Action is NOT "Broadcast"

Parm Name: Type

Requires:

  • MX: 4.1+
  • Android API: 1+

Class

Used to specify a Class Name, within the application identified by the specified Package Name, to which the Intent will be sent. Specifying this parm classifies it as Explicit, and will result in a failure if no such Class exists within the specified application. The Package Name and Class Name parms should always be used together to specify a class within an application.

Parm value input rules:

  • String from 1 - 255 characters containing the Class Name of the target app

Shown if: The Action is NOT "Broadcast"

Parm Name: Type

Requires:

  • MX: 4.1+
  • Android API: 1+

URI

Used to specify a Uniform Resource Identifier (URI) to identify the primary data for the Intent. A URI parm is not required unless there is some primary data to be processed by the operation requested by the Intent, typically a resource on a remote server. In most cases, a MIME Type also should be specified to define the type of the data referenced by the URI.

Parm value input rules:

  • String from 0 - 255 characters containing a URI

Shown if: The Action is "StartActivity" or "StartService"

Parm Name: Uri

Requires:

  • MX: 4.1+
  • Android API: 1+

File

Used to specify a path and file name that identifies the primary data for the Intent. A File parm is not required unless there is some primary data to be processed by the operation requested by the Intent. In some cases, a MIME Type also should be specified to define the type of the data in the file.

Parm value input rules:

  • String from 1 - 255 characters containing a path and file name

Shown if: The Action is "StartActivity" or "StartService"

Parm Name: File

Requires:

  • MX: 4.1+
  • Android API: 1+

Device Owner JSON File

Used to specify the JSON file, which must reside on the device and be executed to set the Device Owner.

Parm value input rules:

  • String containing the name of the JSON file on the device

Shown if: The Action is "Enroll Device Owner"

Parm Name: DOJsonFileData

Requires:

  • MX: 8.0+
  • Android API: 23+

Extra Type

Used to specify the data type of data to be attached to an Intent as an Extra Data Item. Intents allow as many as five extra data items to be attached and sent using the set prompts, parameter names and data types documented below. Specify multiple Extra Types as ExtraType, Extra1Type, Extra2Type, Extra3Type and Extra4Type.

Parm Name: ExtraType

Option Name Description Note Requires
none None This value (or the absence of this parm from the XML) will cause no change to the corresponding extra data item to be attached to the Intent; any previously selected setting will be retained.

MX: 4.1+

Android API: 1+

int Standard Integer Causes the corresponding extra data item to be attached to the Intent with a data type of Standard Integer. The value provided must therefore be a string representing a valid standard integer value between -2^31 and 2^31 -1.

MX: 4.1+

Android API: 1+

char Character Causes the corresponding extra data item to be attached to the Intent with a data type of character. The value provided must therefore be a string containing a single character.

MX: 4.1+

Android API: 1+

charsequence Character Sequence Causes the corresponding extra data item to be attached to the Intent with a data type of Character Sequence. The value provided must therefore be a string containing a sequence of characters. This data type is can be used to supply values comparable to the String data type and should be used if the receiver explicitly requires a Character Sequence instead of a String.

MX: 4.1+

Android API: 1+

float Floating Point Causes the corresponding extra data item to be attached to the Intent with a data type of Single Precision Floating Point. The value provided must therefore be a string representing a valid single-precision 32-bit IEEE 754 floating point number.

MX: 4.1+

Android API: 1+

long Long Integer Causes the corresponding extra data item to be attached to the Intent with a data type of Long Integer. The value provided must therefore be a string representing a valid long integer value between -2^63 and 2^63-1.

MX: 4.1+

Android API: 1+

boolean Boolean Causes the corresponding extra data item to be attached to the Intent with a data type of Boolean. The value provided must therefore be a string representing a valid boolean ("true" or "false") value.

MX: 4.1+

Android API: 1+

char Character Causes the corresponding extra data item to be attached to the Intent with a data type of character. The value provided must therefore be a string containing a single character.

MX: 4.1+

Android API: 1+

short Short Causes the corresponding extra data item to be attached to the Intent with a data type of Short Integer. The value provided must therefore be a string representing a valid short integer value between -2^15 and 2^15-1.

MX: 4.1+

Android API: 1+

double Double Precision Floating Point Causes the corresponding extra data item to be attached to the Intent with a data type of Double Precision Floating Point. The value provided must therefore be a string representing a valid double-precision 64-bit IEEE 754 floating point number.

MX: +

string String Causes the corresponding extra data item to be attached to the Intent with a data type of character sequence. The value provided must therefore be a string containing a sequence of characters. This data type is can be used to supply values comparable to the Character Sequence data type and should be used if the receiver explicitly requires a String instead of a Character Sequence.

MX: 4.1+

Android API: 1+

byte Single Byte Integer Causes the corresponding extra data item to be attached to the Intent with a data type of Single Byte Integer. The value provided must therefore be a string representing a valid single-byte integer value between -2^7 and 2^7-1.

MX: 4.1+

Android API: 1+

Extra Name

Used to specify the extra-data item name(s) to be attached for any extra data item(s) for which a data type other than "none" was specified. Specify multiple Extra Names as ExtraName, Extra1Name, Extra2Name, Extra3Name and Extra4Name.

Note: The Intent framework does not impose specific restrictions on names that can be specified for extra data items. However, Zebra recommends verifying exact Extra Names as expected by the Intent receiver to achieve the desired result.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: The Extra Type is not "none"

Parm Name: ExtraName

Requires:

  • MX: 4.1+
  • Android API: 1+

Extra Value

Used to specify the value of the extra data item to be attached to the Intent for the corresponding name for which a data type other than "none" was specified. Specify multiple Extra Values as ExtraValue, Extra1Value, Extra2Value, Extra3Value and Extra4Value.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: The Extra Type is not "none"

Parm Name: ExtraName

Requires:

  • MX: 4.1+
  • Android API: 1+

Examples

Launch the Main Activity for an Application


<wap-provisioningdoc>
    <characteristic type="Intent" version="4.3" >
        <parm name="Action" value="StartActivity"/>
        <parm name="ActionName" value="android.intent.action.MAIN"/>
        <parm name="Package" value="com.sample.myapp"/>
        <parm name="Class" value="com.sample.myapp.MainActivity"/>
    </characteristic>
</wap-provisioningdoc>

Enroll a Device Owner


<wap-provisioningdoc>
    <characteristic type="Intent" version="7.0" >
        <parm name="Action" value="EnrollDeviceOwner"/>
        <parm name="Package" value="com.symbol.osx.testdpc"/>
        <parm name="Class" value="com.symbol.osx.testdpc.AdminClass"/>
    </characteristic>
</wap-provisioningdoc>