This document contains step by step instructions for using EMDK Api's in a new Xamarin application from scratch. It covers adding the component to the project, using profile manager, using basic APIs
Create a new project
When creating a project for this tutorial use the project name GettingStartedTutorial
Follow this guide to create a new project in Visual Studio.
Follow this guide to create a new project in Xamarin Studio.
Add Symbol EMDK Component
Follow this guide to add the needed component you your project.
Build a Profile
In this project we will perform a simple task to demonstrate how to use the ProfileManager Wizard to create a profile and then submit that profile via the ProfileManager API.
Lets begin by creating a Profile that will set the Date and Time on our device.
- Open the ProfileManger Wizard by selecting EMDK > Profile Manager
- Create a new Profile by clicking the
Create
Button. - In the Create a New Profile Dialog, enter ClockProfile as the Name, and then click
Create
- Once the Profile Editor loads, select the Clock feature in the Available Features pane, and then click the
Right Arrow
(greater than symbol) to add the clock feature to the selected features list. - Select the Clock feature in the selected features list, and Clock feature parameters will load in the far left pane.
- Click in the Date: field, and notice the instructions for that field at the bottom left of the Wizard. In this field lets enter a date that follows the formatting instructions for that field.
- Click in the Time: field, In this field lets enter a time that follows the formatting instructions for that field.
- Now click
Apply
and thenFinish
- Now click the
Close
on the Profile Manger
The ProfileManager Wizard will generate the needed xml in a file call EMDKConfig.xml and place it in the Assets folder of our project. Now lets move on and write some code to submit the profile.
Setup AndroidManifest.xml
In order to use the Symbol EMDK for Xamarin in your project we first need to add a few items to the AndroidManifest.xml in your project.
Perform the following steps to setup your AndroidManifest
Open the AndroidManifest.xml in your project from the Solution pane > "Project Name" > Properties
Replace the
<uses-sdk />
line with<uses-sdk android:minSdkVersion="19" />
Add a new android permission directly below the
uses-sdk
line.<uses-permission android:name="com.symbol.emdk.permission.EMDK" />
Now add a
uses-library
tag inside theapplication
node.<uses-library android:name="com.symbol.emdk" />
Your completed AndroidManifest.xml should resemble the following:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="GettingStartedTutorial.GettingStartedTutorial" android:versionCode="1" android:versionName="1.0">
<uses-sdk android:minSdkVersion="19" />
<uses-permission android:name="com.symbol.emdk.permission.EMDK" />
<application android:label="GettingStartedTutorial" android:icon="@drawable/Icon">
<uses-library android:name="com.symbol.emdk" />
</application>
</manifest>
Setup User Interface
Now lets build our User Interface by opening our main layout file and dragging a dropping some UI elements into our Form.
- Open our main layout by selecting Solution pane > "Project Name" > Resources > layout > Main.axml
- After the layout loads in the Form Builder we can begin adding and modifying UI elements.
- Select the HELLO WORLD, CLICK ME! button, and set its
text
property to the following value in the Properties pane.
- MyButton set text to
Apply Profile
- Add a new textview widget to the form directly below MyButton .
- Select the new textview textView1, and set its
id
andtext
properties to the following values in the Properties pane.
- textView1 set id to
@+id/textViewStatus
and set text toStatus:
- Select the HELLO WORLD, CLICK ME! button, and set its
Your completed Main.axml should resemble the following:
NOTE: To veiw layout in as xml, switch from Design to Source view by selecting
Source
in the bottom left corner of the Form Builder
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="fill_parent">
<Button
android:id="@+id/MyButton"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:text="Apply Profile" />
<TextView
android:text="Status:"
android:textAppearance="?android:attr/textAppearanceSmall"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:id="@+id/textViewStatus" />
</LinearLayout>
Add Some Code
Now lets add some code to our project.
Start by opening up our MainActivity, select Solution pane > "Project Name" > MainActivity.cs
Add a
using
directive that references the Symbol EMDK for Xamarinusing Symbol.XamarinEMDK;
Now lets add some global variables to the MainActivity class for later use.
private EMDKManager emdkManager = null; private ProfileManager profileManager = null; private String profileName = "ClockProfile"; private TextView tvStatus = null;
When our OnCreate Activity lifecycle method is called, we call the Activity's SetContentVeiw() method, which will pull in the layout we created previously in Main.axml. We now need to initialize our User Interface global variables so they can be referenced anywhere in the MainActivity class. We will do that inside our OnCreate method just below where SetContentVeiw() is called.
tvStatus = FindViewById<TextView>(Resource.Id.textViewStatus);
While we are initializing the User Interface lets modify setup our button call a method that will submit our profile. When we crated the profile from the Android Blank template, it added a few lines for us, but we need to modify one of them.
- Change the line that finds the button, so it will find the button
Change:
button.Click += delegate { button.Text = string.Format("{0} clicks!", count++); };
To:
button.Click += delegate { ApplyProfile(); };
Note: We will add the ApplyProfile() method later in this tutorial.
Also in our OnCreate method, we will call the EMDKManager.GetEMDKManger() method to start the EMDKManger initialization process. Then we will check the result of the method and alert the user by updating the Status TextView.
EMDKResults results = EMDKManager.GetEMDKManager(Android.App.Application.Context, this); if (results.StatusCode != EMDKResults.STATUS_CODE.Success) { tvStatus.Text = "Status: EMDKManager object creation failed ..."; } else { tvStatus.Text = "Status: EMDKManager object creation succeeded ..."; }
Next we will need to add and interface to our Activity that notifies the client ( MainActivity ) that the EMDKManager object is ready to use
OnOpened
or is no longer available for useOnClosed
.Add the the interface to our MainActivity
public class MainActivity : Activity, EMDKManager.IEMDKListener
Add the IEMDKListener methods OnOpened and OnClosed to the MainActivity class
void EMDKManager.IEMDKListener.OnOpened(EMDKManager emdkManager) { } void EMDKManager.IEMDKListener.OnClosed() { }
When the OnOpened method is called, an instance of the EMDKManger is passed as its only argument. We will use this instance of the EMDKManger to initialize our global EMDKManager object. We will also alert the user that EMDKManager was successfully Opened and is ready for use. This is also a good time to initialize the ProfileManager global variable, and alert the user if there are any issues while doing so.
void EMDKManager.IEMDKListener.OnOpened(EMDKManager emdkManager) { tvStatus.Text = "Status: EMDK Opened successfully ...";
}this.emdkManager = emdkManager; try { profileManager = (ProfileManager)emdkManager.GetInstance(EMDKManager.FEATURE_TYPE.Profile); } catch (Exception e) { tvStatus.Text = "Status: Exception <" + e.Message + ">"; }
We also need to make sure we clean up the EMDKManger references when they can no longer be used. We will do this in the OnClosed method.
void EMDKManager.IEMDKListener.OnClosed() { tvStatus.Text = "Status: EMDK Open failed unexpectedly. Please close and restart the application ...";
}if (emdkManager != null) { emdkManager.Release(); emdkManager = null; }
We need a way to pass the Profile to the ProfileManager to be processed, for this we will add a method to our MainActivity class called ApplyProfile.
void ApplyProfile() { if (profileManager != null) { EMDKResults results = profileManager.ProcessProfile(profileName, ProfileManager.PROFILE_FLAG.Set, new String[] { "" }); if (results.StatusCode == EMDKResults.STATUS_CODE.Success) { tvStatus.Text = "Status: Profile applied successfully ..."; } else if (results.StatusCode == EMDKResults.STATUS_CODE.CheckXml) { //Inspect the XML response to see if there are any errors, if not report success using (XmlReader reader = XmlReader.Create(new StringReader(results.StatusString))) { String checkXmlStatus = "Status:\n\n"; while (reader.Read()) { switch (reader.NodeType) { case XmlNodeType.Element: switch (reader.Name) { case "parm-error": checkXmlStatus += "Parm Error:\n"; checkXmlStatus += reader.GetAttribute("name") + " - "; checkXmlStatus += reader.GetAttribute("desc") + "\n\n"; break; case "characteristic-error": checkXmlStatus += "characteristic Error:\n"; checkXmlStatus += reader.GetAttribute("type") + " - "; checkXmlStatus += reader.GetAttribute("desc") + "\n\n"; break; } break; } }
}if (checkXmlStatus == "Status:\n\n") { tvStatus.Text = "Status: Profile applied successfully ..."; } else { tvStatus.Text = checkXmlStatus; } } } else { tvStatus.Text = "Status: Profile initialization failed ... " + results.StatusCode; } } else { tvStatus.Text = "Status: profileManager is null ..."; }
Lastly we need to make sure and clean up our references to ProfileManager and EMDKManager before our application exits.
protected override void OnDestroy() { base.OnDestroy();
}if (profileManager != null) { profileManager = null; } if (emdkManager != null) { emdkManager.Release(); emdkManager = null; }
Running the application
Now that we are finish with our first EMDK for Xamarin application, lets see how it runs.
NOTE: Make sure the device is connected to your development system via a USB cable, and that Developer Mode/USB debugging is enabled on the device.
Make note of the current Time and Date on the device.
Start the application by pressing the "Play" button on the toolbar in your IDE. The IDE will install the new application on the device and run it.
If all goes well, you should eventually see your application start and the status message change to
EMDK Opened successfully ...
Now press the
Apply Profile
button.The Status Message should now read
Profile applied successfully ...
. You should see the Time on the devices Notification Bar change to the time you set the Clock profile. You can also pull the Notification Bar down and see that the Date has changed to the Date you set in the Clock profile.