Using Microsoft Tag API

Introduction

Microsoft tag is a 2D barcode which is developed by Microsoft. The idea behind Microsoft Tag is reading tags from your mobile phone and accessing the information on the internet. For doing this, you only need a phone with a camera and to download the tag software which can be found at http://gettag.mobi/. Microsoft Tag can read from the environments which other barcode readers cannot read such as monitors, televisions. It will not be surprising to see tags on business cards, ads or in supermarkets in a close time period.

Using the Code

Since Microsoft Tag also uses colors to encode data, it can store more information from typical 2D barcodes. This information can be a web site address, a contact card, a text or a phone number. When you scan a tag, your phone's default browser will open a website, add a contact to your contacts, show text message or dial a number according to the tag type you scanned. Also all this information can be secured by using a password and can be accessed in a valid time period that can be determined by the publisher of tag.

For using Microsoft tag, you should visit and register at http://tag.microsoft.com. Since it has a user friendly interface, I'll mostly mention about using the API.

For using the API, first of all you should enter http://tag.microsoft.com/ws/accessrequest.aspx?wa=wsignin1.0 and fill the form below.

After filling this form and submitting your application, you'll receive an email that contains the webservice address and a token. You can start using the webservice after you received this mail. I'll not be able to share my token with you so from this point I'll assume the token is "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00" .

First of all, let's add the reference of the web service to our application.

Now we are diving deep into how we can call tag API.

Creating a new category:

try
{
    TagService.MIBPContractClient insMIBPContractClient = 
		new MicrosoftTagAPISample.TagService.MIBPContractClient();
    TagService.UserCredential insUserCredential = 
		new MicrosoftTagAPISample.TagService.UserCredential();
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00";
    TagService.Category insCategory = new MicrosoftTagAPISample.TagService.Category();
    insCategory.Name = "Dummy_Category";
    insCategory.UTCStartDate = DateTime.Now;
    insCategory.UTCEndDate = DateTime.Now.AddDays(10);
    bool result = insMIBPContractClient.CreateCategory(insUserCredential, insCategory);
    if (result)
    {
        MessageBox.Show("Category Successfully Created");
    }
    else
    {
        MessageBox.Show("An Error Occurred While Creating Category");
    }
}
catch (Exception ex)
{          
    MessageBox.Show(ex.ToString());
} 

For using Microsoft Tag's API, first of all you should get an instance of MIBPContractClient object. And after that, we should send the token in every request by assigning it to AccessToken property of an instance of UserCredential object. And to create the category, we should create an instance of a Category object and assign appropriate values to its properties. The important point is that we should not assign a value to the UTCEndDate property if we don't want our category to expire. And to create a category, we need to call the CreateCategory method of the MIBPContractClient object by passing Category and UserCredential. This method returns a boolean value that represents the success of creation of category.

Updating a category:

try 
{ 
    TagService.MIBPContractClient insMIBPContractClient = 
		new MicrosoftTagAPISample.TagService.MIBPContractClient(); 
    TagService.UserCredential insUserCredential = 
		new MicrosoftTagAPISample.TagService.UserCredential(); 
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00"; 
    TagService.Category insCategory = new MicrosoftTagAPISample.TagService.Category(); 
    insCategory.Name = "Dummy_Category_New"; 
    insCategory.UTCStartDate = DateTime.Now; 
    insCategory.UTCEndDate = DateTime.Now.AddDays(10);
    bool result = insMIBPContractClient.UpdateCategory
			(insUserCredential,"Dummy_Category", insCategory); 
    if (result) 
    { 
        MessageBox.Show("Category Successfully Updated"); 
    } 
    else 
    { 
        MessageBox.Show("An Error Occurred While Updating Category"); 
    } 
} 
catch (Exception ex) 
{   
    MessageBox.Show(ex.ToString()); 
}

The logic of updating a category is the same as creating one. The important part is that you should also pass the current name of the category you want to update as a parameter to UpdateCategory method of MIBPContractClient object as well as Category and UserCredential.

Making a category passive or active:

try
{
    TagService.MIBPContractClient insMIBPContractClient = 
		new MicrosoftTagAPISample.TagService.MIBPContractClient();
    TagService.UserCredential insUserCredential = 
		new MicrosoftTagAPISample.TagService.UserCredential();
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00";
    bool result = insMIBPContractClient.PauseCategory
		(insUserCredential, "Dummy_Category_New");
    if (result)
    {
        MessageBox.Show("Category Successfully Paused");
    }
    else
    {
        MessageBox.Show("An Error Occurred While Pausing Category");
    }
}
catch (Exception ex)
{
    MessageBox.Show(ex.ToString());
}
try
{
    TagService.MIBPContractClient insMIBPContractClient = 
		new MicrosoftTagAPISample.TagService.MIBPContractClient();
    TagService.UserCredential insUserCredential = 
		new MicrosoftTagAPISample.TagService.UserCredential();
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00";
    bool result = insMIBPContractClient.ActivateCategory
		(insUserCredential, "Dummy_Category_New");
    if (result)
    {
        MessageBox.Show("Category Successfully Activated");
    }
    else
    {
        MessageBox.Show("An Error Occurred While Activating Category");
    }
}
catch (Exception ex)
{
    MessageBox.Show(ex.ToString());
}

You should send the category name and UserCredentials to the PauseCategory or ActivateCategory method of the MIBPContractClient object.

Creating a new tag:

try
{
    TagService.MIBPContractClient insMIBPContractClient = 
		new MicrosoftTagAPISample.TagService.MIBPContractClient();
    TagService.UserCredential insUserCredential = 
		new MicrosoftTagAPISample.TagService.UserCredential();
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00";
    TagService.URITag insURITag = 
	new MicrosoftTagAPISample.TagService.URITag();//DialerTag, 
						//FreeTextTag, VCardTag 
    insURITag.Title = "New_URI_Tag";
    insURITag.MedFiUrl = "http://www.tameroz.com";
    insURITag.UTCStartDate = DateTime.Now;
    insURITag.UTCEndDate = DateTime.Now.AddDays(10);
    bool result = insMIBPContractClient.CreateTag
		(insUserCredential, "Dummy_Category_New", insURITag);
    if (result)
    {
        MessageBox.Show("Tag Successfully Created");
    }
    else
    {
        MessageBox.Show("An Error Occurred While Creating Tag");
    }
}
catch (Exception ex)
{
    MessageBox.Show(ex.ToString());
}

To create a tag, we should create an instance of the tag type we will create. These types can be DialerTag, FreetextTag, VCardtag or URITag. After filling the appropriate properties of the object that we created, we should call the CreateTag method of MIBPContractClient object by passing UserCredential object, Category name of the tag that will be created and the tag object that we created. Also as in creating the category, we should not assign value to the UTCEndDate property if we don't want our tag to expire.

Updating a tag:

try
{
    TagService.MIBPContractClient insMIBPContractClient = 
		new MicrosoftTagAPISample.TagService.MIBPContractClient();
    TagService.UserCredential insUserCredential = 
		new MicrosoftTagAPISample.TagService.UserCredential();
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00";
    TagService.URITag insURITag = 
	new MicrosoftTagAPISample.TagService.URITag();//DialerTag, 
						//FreeTextTag, VCardTag 
    insURITag.Title = "New_URI_Tag";
    insURITag.MedFiUrl = "http://www.tameroz.com";
    insURITag.UTCStartDate = DateTime.Now;
    insURITag.UTCEndDate = DateTime.Now.AddDays(10);
    bool result = insMIBPContractClient.UpdateTag
		(insUserCredential, "Dummy_Category_New", "New_URI_Tag", insURITag);
    if (result)
    {
        MessageBox.Show("Tag Successfully Updated");
    }
    else
    {
        MessageBox.Show("An Error Occurred While Updating Tag");
    }
}
catch (Exception ex)
{
    MessageBox.Show(ex.ToString());
} 

The logic of updating a tag is the same as creating one. The important part is you should also pass the current name of the tag you want to update as a parameter to UpdateTag method of MIBPContractClient object as well as Tag object itself and UserCredential.

Making a tag passive or active:

try
{
    TagService.MIBPContractClient insMIBPContractClient = 
		new MicrosoftTagAPISample.TagService.MIBPContractClient();
    TagService.UserCredential insUserCredential = 
		new MicrosoftTagAPISample.TagService.UserCredential();
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00";
    bool result = insMIBPContractClient.PauseTag
		(insUserCredential, "Dummy_Category_New", "New_URI_Tag");
    if (result)
    {
        MessageBox.Show("Tag Successfully Paused");
    }
    else
    {
        MessageBox.Show("An Error Occurred While Pausing Tag");
    }
}
catch (Exception ex)
{
    MessageBox.Show(ex.ToString());
}
try
{
    TagService.MIBPContractClient insMIBPContractClient = 
		new MicrosoftTagAPISample.TagService.MIBPContractClient();
    TagService.UserCredential insUserCredential = 
		new MicrosoftTagAPISample.TagService.UserCredential();
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00";
    bool result = insMIBPContractClient.ActivateTag
		(insUserCredential, "Dummy_Category_New", "New_URI_Tag");
    if (result)
    {
        MessageBox.Show("Tag Successfully Activated");
    }
    else
    {
        MessageBox.Show("An Error Occurred While Activating Tag");
    }
}
catch (Exception ex)
{
    MessageBox.Show(ex.ToString());
}

You should send the tag name and UserCredentials to the PauseTag or ActivateTag method of the MIBPContractClient object.

Displaying a tag in a Windows Application :

try 
{ 
    TagService.MIBPContractClient insMIBPContractClient = 
		new MicrosoftTagAPISample.TagService.MIBPContractClient(); 
    TagService.UserCredential insUserCredential = 
		new MicrosoftTagAPISample.TagService.UserCredential(); 
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00"; 
    byte[] b=insMIBPContractClient.GetBarcode
	(insUserCredential, "Main", "Tamer Vcard",
	MicrosoftTagAPISample.TagService.ImageTypes.jpeg, 2, 
	MicrosoftTagAPISample.TagService.DecorationType.HCCBRP_DECORATION_FRAMEPLAIN,
	false); 
    MemoryStream ms = new MemoryStream(b); 
    Image i=Image.FromStream(ms); 
    PictureBox pb = new PictureBox(); 
    pb.SizeMode = PictureBoxSizeMode.Zoom; 
    this.Controls.Add(pb); 
    pb.Dock = DockStyle.Fill; 
    pb.Image = i; 
} 
catch (Exception ex) 
{   
    MessageBox.Show(ex.ToString()); 
} 

To get a tag image by using the API, we can use GetBarcode method of MIBPContractClient object. This method accepts UserCredential object, name of the category that tag belongs to, name of the tag, the type of the image that will be generated (such as JPG, GIF, PDF, PNG, etc.), the size of the tag in inches and the display type of the tag. I'll give some samples of display types at the end of the article.

Displaying a tag in a Web Application :

try 
{ 
    Response.Clear(); 
    TagService.MIBPContractClient insMIBPContractClient = 
			new TagService.MIBPContractClient(); 
    TagService.UserCredential insUserCredential = new TagService.UserCredential(); 
    insUserCredential.AccessToken = "00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00";
    byte[] b = insMIBPContractClient.GetBarcode
	(insUserCredential, "Main", "Tamer Vcard", TagService.ImageTypes.jpeg, 
	2, TagService.DecorationType.HCCBRP_DECORATION_DOWNLOAD, false); 
    Response.BinaryWrite(b); 
    Response.ContentType = "Image/JPEG"; 
} 
catch (Exception ex) 
{   
    Response.Write(ex.ToString()); 
}

Here are some samples about display types of a tag.

DecorationType.HCCBENCODEFLAG_STYLIZED

DecorationType.HCCBRP_DECORATION_DOWNLOAD

DecorationType.HCCBRP_DECORATION_FRAMEPLAIN

DecorationType.HCCBRP_DECORATION_NONE

Contact

For bug reports and suggestions, feel free to contact me at oztamer@hotmail.com.

History

• 16^th April, 2010: Initial post