Section 10.1. Programming with Location Server Web Service

10.1. Programming with Location Server Web Service

Microsoft Location Server Web Service provides APIs for functionalities such as finding real-time locations, finding nearby points of interest, finding contacts, and adding and removing contacts. Because this web service is hosted within your enterprise, you need your network domain credentials to access it. In the following sections of this chapter, we will examine the Microsoft Location Server Web Service APIs in detail.

10.1.1. Anatomy of Location Web Service APIs

As you learned in Chapter 9, Location Server Web Service is hosted within your enterprise and not hosted by Microsoft. So, in order to develop with the Location Server Web Service, you need to access the WSDL (Web Service Description Language) document for the Location Server Web Service. If your enterprise's Location Server is installed on a domain (www.YourFullDomainName.com), your Location Server Web Service WSDL can be accessed using the following URL:

https://www.YourFullDomainName.com/mmlsservice/locationserver.wsdl

Note that the Location Server Web Service is only accessible to valid provisioned domain user accounts; to access the above WSDL, you must be a domain user on your enterprise's network and provisioned in the Microsoft Location Server as a user.

The previous WSDL contains only one SOAP endpoint (LocationService.asmx) which translates into the LocationServiceSoap class when added to your current project as a web reference. The LocationServiceSoap class provides all the necessary functionalities, such as getting real-time location, adding, updating and removing contacts, and changing personal privacy settings. Table 10-1 shows the methods offered by the LocationServiceSoap class. In this table, the current user is the original submitter of the request.

Table 10-1. LocationServiceSoap class methods
Method	Description
`GetPositions`	Returns the user's or contact's positions synchronously as an instance of the `PositionResults` class.
`GetPositionsAsync`	Returns the user's or contact's positions asynchronously. This method is an asynchronous version of the `GetPositions` method. However, you must call the `GetPositionsAsyncResults` method to complete the process of getting positions.
`GetPositionsAsyncResults`	Completes the asynchronous request invoked by the `GetPositionsAsync` method. This method returns the positions that correspond to the domain and alias pairs as an instance of the `PositionResults` class. This method must be called with a valid token obtained by calling the `GetPositionsAsync` method.
`GetNearbyCategories`	Gets Find Nearby categories based on the current user's culture.
`GetVisibility`	Gets the status for the current user's `Visible` property.
`SetVisibility`	Sets the status for the current user's `Visible` property.
`GetNewContactNotification`	Gets the value of the `NotifyOnNewContact` property for the current locatable user.
`SetNewContactNotification`	Sets the value of the "Notify on Contact" option for the current user.
`GetdefaultCulture`	Returns the default culture for the current user in string format; for example: "en-US" for English, United States.
`SetDefaultCulture`	Sets the default culture for the current user.
`GetUserInfo`	Returns the current user's information as an instance of the `LocatableUser` class.
`AddContact`	Adds a contact to the current user's list of contacts.
`UpdateContact`	Updates the specified contact in the current user's contact list.
`DeleteContact`	Deletes the specified contact entry from the current user's list of contacts.
`FindProvisionedUser`	Allows partial input of the `LocatableUser` object properties or a user's email address to search the provisioned users on the location server and returns contact information as an array of `LocatableContact` class instances.
`GetContacts`	Returns a list of contacts for the current user as an array of `LocatableContact` objects.

The categorizations of various methods provided by the LocationServiceSoap class are shown in Figure 10-1.

Figure 10-1. LocationServiceSoap method categorization

The methods available on the LocationServiceSoap type fall into three main categories:

Real-Time Location APIs: Provide core functionality to get real-time location based on mobile phone numbers; the methods in this category are GetPositions and GetPositionsAsync.
Privacy Management APIs: Provide core functionality to manage self privacy, including the GetVisibility, SetVisibility, GetNewContactNotification, and SetNewContactNotification methods.
Contact Management APIs: Provide core functionality to add new contacts and delete or update existing contacts. The methods in this category include GetContacts, AddContact, and DeleteContact.

All these methods that run from LocationServiceSoap run the context of a provisioned user; in other words, LocationServiceSoap methods cannot be used to manipulate the privacy settings or contact management for users other than the logged-in user. Since Location Server depends on the Active Directory-based domain accounts to provision users within an enterprise, the authentication to the Location Server Web Service is performed using the enterprise domain account credentials:

     //Create an instance of the LocationServiceSoap proxy class     LocationServiceSoap locationService = new LocationServiceSoap( );     //Create an instance of the NetworkCredential class     //and add the credentials required to access the Web service        NetworkCredential credentials =            new NetworkCredential("user", "password", "domain");     locationService.Credentials = credentials;

Next, let's look at various tasks that can be performed using the Location Server Web Service.

10.1.2. Finding a Real-Time Location

MapPoint Location Server Web Service exposes the GetPositions method, which you can use to request a real-time location of yourself or your contacts (such as your colleagues within the same enterprise).

If you are requesting your own location, pass your domain alias as an argument to the GetPositions method; however, you must be a valid provisioned user to successfully request your location.

If you are requesting the location of your contacts, you need to pass the following criteria:

You must be a valid provisioned user.
Your contacts must be valid provisioned users.
Your contacts have granted you permission to locate them.
Your contacts have their status set to visible (not in stealth mode).

Once you meet the above criteria, you can pass the domain aliases of the contact users whose location you want to find as an argument to this method. If you fail to meet any of the above criteria, your request to locate your contact results in a failure. The third and fourth bullets act as layers of defense to protect your contacts' privacy.

When a location request succeeds, GetPositions returns an instance of the PositionResults class, which contains the positions for the domain aliases passed to the method. The PositionResults class instance contains a property that exposes an array of Position class instances that contain the position information expressed as latitude and longitude coordinates. The order of the Position array elements corresponds to the order of the domain aliases passed to this method. The following code snippet shows how to invoke the GetPositions method:

      //Create an instance of the LocationServiceSoap proxy class     LocationServiceSoap locationService = new LocationServiceSoap( );     //Create an instance of the NetworkCredential class     //and add the credentials required to access the Web service     NetworkCredential credentials =            new NetworkCredential("user", "password", "domain");     locationService.Credentials = credentials;     try      {          //Get the positions from the GetPositions method       PositionResults positionResults =          locationService.GetPositions(new string[] {@"domain\contact"});       //Process the positions       foreach(Position position in positionResults.Positions)       {        //Get each contact's lat/long        LatLong ll = position.LatLong;       }        }     catch(System.Web.Services.Protocols.SoapException MyException)      {       //Process exceptions here      }

Once a location is obtained as latitude/longitude coordinates, you can display it on a map using the MapPoint Web Service Rendering Service .

Microsoft Location Server Web Service also exposes the GetPositionsAsync method and a corresponding GetPositionsAsyncResults method for invoking asynchronous location requests. The difference between these methods and the proxy-generated asynchronous methods (BeginGetPositions and EndGetPositions) generated by Visual Studio .NET is that the Visual Studio .NET-generated methods run the invocation process on a background thread to free up the UI thread, which keeps the HTTP connection open until the response from Microsoft Location Server Web Service is complete. The GetPositionsAsync method closes the HTTP connection as soon as the request is complete, making the request and response truly asynchronous. The GetPositionsAsync method may be required with mobile operators that cannot locate a mobile device when an HTTP connection is open. If you are working with a mobile operator that does not have this issue and you are developing your client application using the asynchronous model, use the asynchronous methods generated by Visual Studio .NET.

10.1.3. Adding and Removing Contacts

MapPoint Location Web Service offers two methods, AddContact and DeleteContact, which can be used to add and remove contacts for provisioned users. You can use the FindProvisionedUser method to look up the provisioned users within your enterprise so that you can to add them to your contact list. Note that although you can add a contact to your contacts list, you can locate that contact only if he grants you permission to do so. This explicit opt-in model is an important privacy feature of Microsoft Location Server.

The following code snippet shows how to add a contact to your contact list. First, find a provisioned user using his phone number:

     //Create a LocationService Proxy.     LocationServiceSoap locationService = new LocationServiceSoap( );     //Define and add credentials to the proxy     . . .     //Create a ProvisionedUser instance and     //assign the search value.     ProvisionedUser provisionedUser = new ProvisionedUser( );     provisionedUser.DomainAlias = @"DOMAIN\user";     //Create a locatable device instance and assign the value.     LocatablePhoneNumber phone = new LocatablePhoneNumber( );     phone.CountryCode = "001";     phone.LocalCode = "111";     phone.ShortNumber = "1111111";     //Find out if this user is provisioned     try      {       LocatableContact[] users = locationService.FindProvisionedUser(                                      provisionedUser, phone,  -1);       foreach(LocatableContact user in users)       {        //Process found provisioned users        . . .       }      }     catch(SoapException exception)      {       //Your exception process goes here      }

As you can see, FindProvisionedUser takes either a partially-defined ProvisionedUser instance or a LocatablePhoneNumber instance to look up the provisioned users to match from the Active Directory within an enterprise. It is important to note that at least one of these two arguments is required. When both are present, both arguments are used for the lookup. The rules detailed in the following sections must be followed for the partially defined ProvisionedUser instance used for the lookup.

10.1.3.1. If lookup is based on domain alias

Partial domain alias searching is permitted. For example, if there is a user "John Doe" in domain "XYZ" with an user alias "jdoe," the following searches return valid results:

"jdoe" returns an exact match for "XYZ\jdoe".
"XYZ\jdoe" returns an exact match for "XYZ\jdoe".
"XYZ/jdoe" returns an exact match for "XYZ\jdoe".

The following searches fail to return the provisioned user:

"Doe" will fail. (This case assumes that the alias "Doe" does not belong to another valid user.)
Searching for "jdo" will fail. (This case assumes that the alias "jdo" does not belong to another valid user.)

10.1.3.2. If lookup is based on display name

Partial display name searching is allowed. This search is performed using a "starts-with" condition . For example, if the display name is "Mr. Jon Doe," searching for "John" will yield "Mr. Jon Doe" as one of the results.

The minimum number of characters that needs to be supplied for a display name partial search is two.

10.1.3.3. If lookup is based on first name and last name

Partial searching is allowed for first and last name searches. The only rule is that the sum of the characters from both first name and last name together must be greater than or equal to two. The following searches return results for "John Doe:"

Searching for "John" as the first name and "Doe" as the last name will return "John Doe" as one of the matches.
Searching for "J" as the first name and "Doe" as the last name will return "John Doe" as one of the matches.
Searching for "John" as the first name and "D" as the last name will return "John Doe" as one of the matches.
Searching for "Jon" as the first name and "" (empty) as the last name will return "John Doe" as one of the matches (or may fail due to too many matches).
Finally, searching for "J" as the first name and "D" as the last name may fail due to too many matches.

10.1.3.4. If lookup is based on phone number

The locatablePhonenumber parameter is optional and can be null; however, when provided, an exact match is returned if its match is in the database. When a phone number is provided, the short number (last seven digits of the phone number) must be provided to be considered for the search.

10.1.3.5. If lookup is based on email address

Email address searches allow a "starts-with" partial search. If you provide a complete email address including a @ sign, however, an exact match is returned if its match is in the database.

The third argument for the FindProvisionedUser method indicates the number of provisioned users to return that match the input query; value -1 indicates the Location Server Web Service to return all found provisioned users. When the requested number of provisioned users does not match the matched provisioned user count, an exception is thrown.

Once a provisioned user is found using a query such as the one shown previously, you can add her as your contact:

     //Create an instance of the LocationServiceSoap proxy class     LocationServiceSoap MyLocationService = new LocationServiceSoap( );     //Create an instance of the NetworkCredential class     //and add the credentials required to access the Web service     NetworkCredential MyCredentials =           new NetworkCredential("user", "password", "domain");     MyLocationService.Credentials = MyCredentials;      try     {      //Add a new contact for the current user         LocatableContact MyLocatableContact =          MyLocationService.AddContact(@"domain\contactuser",                                       true, true);     }     catch(SoapException MyException)     {      //Process exceptions here      . . .     }

As you can see, the AddContact method takes three arguments:

contact user domain alias: Indicates the domain alias of the contact that is being added
isActive flag: Indicates whether the contact relationship is active; you may add someone as a contact but block her from locating you by setting this flag to false. If you set this value to TRue, it means that the contact can locate you.
notifyOnLocate flag: Indicates via an SMS message or email that you are being located by your contact when this flag is set to TRue. This flag works as a record of all locate attempts made by your contacts.

Note that if you try to add a contact that you already have in your contact list, this method throws an exception. Along similar lines, the methods DeleteContact and UpdateContact take the contact domain alias to either remove the contact relationship or modify the existing contact relationship respectively.

10.1.4. Programming Privacy Settings

As a Location Server user, you may be worried about your privacyspecifically, you don't want to be tracked all the time even if you give permission to your contacts to track you. For situations like this, Location Server gives you the flexibility to control the privacy settings so that you can enable who can track you; it even gives you a way to go into stealth mode by becoming completely invisible to your contacts.

10.1.4.1. Managing contact privacy settings

Using the LocationServiceSoap.UpdateContact method, you can enable or disable the ability for your contacts to locate you. Similar to the AddContact method, this method takes three arguments that indicate the contact user, locatable permissions flag (isActive), and notification on the locate flag. To disable a contact from locating you, set the isActive flag to false:

     //Create a LocationServiceSoap proxy instance     LocationServiceSoap locationService = new LocationServiceSoap( );     //Create and add the credentials required to access the Web service     NetworkCredential credentials =                 new NetworkCredential("user", "password", "DOMAIN");     locationService.Credentials = credentials;     try     {      //Update the contact - turn off their ability to locate you         LocatableContact locatableContact =                  MyLocationService.UpdateContact(@"DOMAIN\contactuser",                                                  false, false);     }     catch(SoapException MyException)     {      //Your exception processing goes here      . . .     }

To enable the same contact to be able to locate you, you just need to call the same method with the isActive flag set to true:

     //Update the contact - turn on their ability to locate you     LocatableContact locatableContact =                  MyLocationService.UpdateContact(@"DOMAIN\contactuser",                                                  true, true);

10.1.4.2. Going into stealth modebecoming invisible to all contacts

Using the LocationServiceSoap.SetVisibility method, you can become completely invisible to all of your contacts, meaning that even if your contacts have permission to locate you, they will be not be able to if you set your visibility to false. The following code snippet shows how to turn off your visibility completely using the SetVisibility method:

     //Create a LocationServiceSoap proxy instance     LocationServiceSoap locationService = new LocationServiceSoap( );     //Create and add the credentials required to access the Web service     NetworkCredential credentials =               new NetworkCredential("user", "password", "DOMAIN");     locationService.Credentials = credentials;     try     {      //Set the visibility for the current user - Go Stealth mode         locationService.SetVisibility(false);     }     catch(SoapException MyException)     {      //Your exception processing goes here      . . .     }

Similarly, you can set your visibility to true so that your contacts can locate you:

     //Set the visibility for the current user - Become visible     locationService.SetVisibility(true);

If your visibility is set to false and your contacts try to locate you, they get an error indicating that you are not locatable; however, it does not indicate that you chose to be invisible to your contacts.

10.1.5. Finding Nearby Points of Interest

To find nearby points of interest, MapPoint Location Web Service exposes the LocationServiceSoap.GetNearbyCategories method, which returns find nearby categories. Find nearby categories are groups of points of interest of the same type; for example, banks, ATMs, pizza shops, and pubs could belong to these categories. You can use this list of categories to search for points of interest that are close to your location. The following code shows how to retrieve find nearby categories.

     //Create an instance of the LocationServiceSoap proxy class     LocationServiceSoap locationService = new LocationServiceSoap( );     //Create an instance of the NetworkCredential class     //and add the credentials required to access the Web service     NetworkCredential credentials =             new NetworkCredential("user", "password", "domain");     locationService.Credentials = MyCredentials;     //Get the Find Nearby categories     try     {         FindNearbyCategory[] findNearbyCategories =                   locationService.GetNearbyCategories( );      foreach(FindNearbyCategory findNearbyCategory in                                             findNearbyCategories)      {        //Process find nearby category        . . .      }     }     catch(SoapException exception)     {      //Process exceptions here      . . .     }

Once you retrieve the find nearby categories using this method, you can call the FindServiceSoap.FindNearby method to retrieve the actual points of interest. So, why do you need this layer of abstraction from the huge yellow page categories and listings available in MapPoint Web Service? Enterprise customization! As an enterprise, you may have business requirements to make specific find nearby categories available to your employees. In this case, a system administrator can define specific find nearby categories that are useful for provisioned users that can later be exposed to your enterprise users via the Location Server client, enabling them to find the specific groups of points of interest around their current location.