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:

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.

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:

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.

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:

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[] {@"domaincontact"});
      //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.

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 = @"DOMAINuser";

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

    //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(@"domaincontactuser",
                                      true, true);
    }
    catch(SoapException MyException)
    {
     //Process exceptions here
     . . .
    }

As a Location Server user, you may be worried about your privacy—specifically, 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.

    //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(@"DOMAINcontactuser",
                                                 false, false);
    }
    catch(SoapException MyException)
    {
     //Your exception processing goes here
     . . .
    }

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

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

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

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.

Microsoft Location Server provides the Server Management APIs to build applications to automate administrative tasks such as adding users, managing contacts for users, and managing find nearby categories. All of the Server Management APIs are provided via the ServerAPI class in the Microsoft.MapPoint.LocationServer.Types.dll assembly; this class provides a set of methods that enables you to develop applications in four major categories:

Table 10-2 shows the methods exposed by the ServerAPI class .

Figure 10-2 shows the methods and their categorization.

The server management APIs provide everything that the Location Server Web Service provides except for the real-time location APIs. In this section, let’s look at each of the categories in detail.

Before getting into the details of user management, let’s take a brief look at how the users are organized within Microsoft Location Server. All enterprise users provisioned within the Microsoft Location Server are represented using the ProvisionedUser class. The ProvisionedUser class acts as a base class for locatable users and contacts. A locatable user is essentially a provisioned user with a valid locatable phone number; along the same lines, a locatable contact is a provisioned user with a valid contact relationship. Figure 10-3 shows this relationship pictorially.

Figure 10-2. Server management API categorization

Figure 10-3. User object model in Location Server

In essence, the previous discussion can be summarized as:

    Locatable User = Provisioned User + Locatable Phone Number
    Locatable Contact = Provisioned User + Contact Relationship

With this introduction, let’s look at user management API in the Location Server APIs.

    //Create a new instance of the ServerAPI class.
    ServerAPI serverAPI = new ServerAPI( );
    try
    {
     //Create a new instance of the LocatableUser class.
     LocatableUser newUser = new LocatableUser( );
     //Set the domain and alias.
     newUser.DomainAlias = @"domainuser";
     //Set the culture name.
     newUser.CultureName = "en-US";
     //Set the locatable endpoint (the user's mobile device number).
     newUser.LocatableEndpoint =
            new LocatablePhoneNumber("001", "111", "1111111");
     //Set the location provider name
     newUser.LocationProviderName = "Your Location Provider Name";
     //Set the notification provider name
     newUser.NotificationProviderName =
                    "Your Notification Provider Name";
     //Set the notification endpoint
     newUser.NotificationEndpoint = "user email address";
     //Initialize the database connection for ServerAPI operations.
        serverAPI.Initialize("SQL Server Name", "LocationServerDB");
     //Add the new domain user to Microsoft Location Server.
        serverAPI.AddUser(newUser);
    }
    catch(Exception exception)
    {
     //Process exceptions
     . . .
    }

    //Create a new instance of the ServerAPI class 
 

    ServerAPI serverAPI = new ServerAPI( );
    try
    {
      //Create a LocatableUser instance
      LocatableUser user = new LocatableUser( );
      //Set the domain alias
      user.DomainAlias = @"DOMAINuser";
      //Update the culture name
      user.CultureName = "de-DE";
      //Update the Locatable end point - This is the user's new mobile device number
      user.LocatableEndpoint = new LocatablePhoneNumber("001", "425", "2222222");

      //Initialize the database connection for ServerAPI operations
         serverAPI.Initialize("SQL Server Name", "MSLocationServer");
      //Now Update the domain user profile
         serverAPI.UpdateUser(user);
    }
    catch(Exception MyException)
    {
      //Process your exceptions
      . . .
    }

If you recall from our earlier discussions, Location Server Web Service can only update privacy settings for the logged-in user; however, the ServerAPI class can be used in administrative mode to update the privacy settings of any provisioned users in the Microsoft Location Server, including enabling and disabling contact relationships and visibility for any given provisioned user. You can use the ServerAPI.GetVisibility and ServerAPI.SetVisibility methods to set the user level visibility settings.

The following code snippet shows how to set visibility for a provisioned user within Microsoft Location Server:

    //Create a new instance of the ServerAPI class 
 
 
 

    ServerAPI serverAPI = new ServerAPI( );
    try
    {
      //Initialize the database connection for ServerAPI operations
      serverAPI.Initialize("SQL Server Name", "MSLocationServer");

      //Now Set the Visibility flag for the domain alias DOMAINuser
      //false means that the user is not visible and others can not
      //locate this user even if he/she is on their contact list
         serverAPI.SetVisibility(@"DOMAINuser", false);

    }
    catch(Exception exception)
    {
      //Process your exceptions
      . . .
    }

The only difference between the SetVisibility of the ServerAPI and the LocationServiceSoap is that you need to pass the domain alias that you want to modify the privacy settings for; this makes sense since you are running ServerAPI in administrator mode; Location Server Web Service, however, implicitly assumes the logged-in user’s settings.

Using the ServerAPI class, you can add, remove, and update contacts for provisioned users. The capability to manage contacts is extremely useful if you are setting up a standard contact list for all provisioned users within your enterprise. The ServerAPI class exposes the methods AddContact, UpdateContact, and DeleteContact for adding, updating, and deleting contacts, respectively. As mentioned earlier, the primary difference between the Microsoft Location Server Web Service methods and the ServerAPI class methods is that the web service method calls run in the current user’s context and the ServerAPI methods calls run under the administrator’s context. Therefore, when you call the AddContact method using the Microsoft Location Server Web Service, you are adding a contact to your own contact list, whereas when you call the AddContact method of the ServerAPI class, you are adding a contact for the provisioned user whom you specify as an argument to this method.

The following code snippet shows how to call the AddContact method to add a contact for a provisioned user.

    //Create a new instance of the ServerAPI class.
    ServerAPI serverAPI = new ServerAPI( );

    //Call the Initialize method.
     serverAPI.Initialize("sql server name", "LocationServerDB");

    //Original user to whom the contact is being added
    string userAlias = @"domainuser";
    //Contact domain alias
    string contactAlias = @"domain
ewcontact";
    try
    {
        LocatableContact locatableContact =
                  serverAPI.AddContact(userAlias, contactAlias, true, true);
     . . .
    }
    catch(Exception exception)
    {
     //Process exceptions
     . . .
    }

In this code, a new contact, "domain ewcontact" has been added to the provisioned user "domainuser" using the ServerAPI.AddContact method; the two boolean flags passed to this method indicate whether the contact relationship is active and whether the user wants to be notified when the contact tries to locate him, respectively.

Along the same lines, you can also update an existing contact relationship using the ServerAPI.UpdateContact method:

    //Original user to whom the contact is being added
    string userAlias = @"domainuser";
    //Contact domain alias
    string contactAlias = @"domain
ewcontact";
    try
    {
        LocatableContact locatableContact =
                  serverAPI.UpdateContact(userAlias, contactAlias, false, true);
     . . .
    }
    catch(Exception exception)
    {
     //Process exceptions
     . . .
    }

This call updates the contact relationship to be a “non-active” relationship (due to the flag isActive being set to false), and as a result, the provisioned user newcontact cannot locate the provisioned user user.

Using the ServerAPI class you can add, update, and delete find nearby categories that are appropriate for your enterprise. The ServerAPI class exposes the methods AddNearbyCategory, UpdateNearbyCategory, and DeleteNearbyCategory for adding , updating, and removing find nearby categories.

Find nearby categories are logical groupings of points of interest; they directly map to the entity model presented in the MapPoint Web Service. If you plan to define a find nearby category by the name “dining places,” you need to specify the exact entity type name and the associated data source name that corresponds to the find nearby category in MapPoint Web Service. In this case, if you plan to use NavTeq’s provided yellow page listing categories to define the “dining places” category, you need to specify the entity type name as “SIC3578” and the data source name as “NavTech.NA.”

So, to add a find nearby category, you need to complete the following steps:

Use the method AddNearbyCategory to add a nearby category; this method takes a valid instance of the FindNearbyCategory class as an argument to add the nearby category; a valid FindNearbyCategory object defines the aforementioned five properties for the ServerAPI to be able to add a nearby category successfully.

The following code shows adding a find nearby category called Dining Places and maps the entity type SIC3578 from the data source NavTech.NA:

    //Create a new instance of the ServerAPI class
    ServerAPI serverAPI = new ServerAPI( );

    //Initialize the database connection for ServerAPI operations
    serverAPI.Initialize("SQL Server Name", "LocationServerDB");

    //Step 1 & 2

    //Create a new instance of the FindNearbyCategory class 

    FindNearbyCategory category = new FindNearbyCategory( );
    //Set the default culture.
    category.DefaultCulture = "en-US";
    //Set the distance units.
    category.DistanceUnit = DistanceUnit.Mile;
    //Set the key name.
    category.KeyName = "DiningPlaces";

    //Step 3

    //Set the localized names.
    //In this case we have two localized names
    //Set the name for English (US)
    FindNearbyCategoryName[] findNearbyCategoryNames
                          = new FindNearbyCategoryName[2];

    findNearbyCategoryNames[0] = new FindNearbyCategoryName( );
    findNearbyCategoryNames[0].Culture = "en-US";
    findNearbyCategoryNames[0].DisplayName
                       = "Dining Places";
    findNearbyCategoryNames[0].DisplayDescription
                       = "Dining Places related to my enterprise.";
    //Set the name for German (Germany) Culture.
    findNearbyCategoryNames[1] = new FindNearbyCategoryName( );
    findNearbyCategoryNames[1].Culture = "de-DE";
    findNearbyCategoryNames[1].DisplayName
                         = "Speisenden Pl?tze";
    findNearbyCategoryNames[1].DisplayDescription
                         = "Speisenden Pl?tze";

    //Assign the localized names to the instance
    //of the FindNearbyCategory class
    category.Names = findNearbyCategoryNames;


    //Step 4 & 5

    //Create a new instance of the FindNearbySpecification class
    FindNearbySpecification findNearbyCategorySpecification =
                                         new FindNearbySpecification( );
    //Define the data source
    findNearbyCategorySpecification.DataSourceName = "NavTech.NA";

    //Define the entity type
    findNearbyCategorySpecification.Filter = new FindFilter( );
    findNearbyCategorySpecification.Filter.EntityTypeName = "SIC3578";

    //Assign the FindNearbySpecification to the category
    category.FindNearbySpecification = findNearbyCategorySpecification;

    //Finally . . .
    //Add the find nearby category
       serverAPI.AddNearbyCategory(category);
    . . .

Note that the find nearby category key name (DiningPlaces, in this example) is a required field and should not exceed 128 characters in length. Also, the default culture must be always defined, along with an associated localized name. For example, if you define the default culture as “fr-FR” with no associated localized French name for your find nearby category, the AddNearbyCategory throws an exception.

Along similar lines, you can also update a find nearby category using the ServerAPI.UpdateNearbyCategory method. To update the entity type and data source mapping to a find nearby category that you have already defined, use the UpdateNearbyCategory method. The following code snippet shows updating the entity type and data source mapping for the dining places nearby category that we created previously:

    //Create an instance of the ServerAPI and initialize
    . . .

    //Create a FindNearbySpecification
    FindNearbySpecification findNearbyCategorySpecification
                     = new FindNearbySpecification( );
    //Update this value from NavTech.NA to Acxiom.US.SIC_G.58
       findNearbyCategorySpecification.DataSourceName = "Acxiom.US.SIC_G.58";

    findNearbyCategorySpecification.Filter = new FindFilter( );

    //Update this value from SIC3578 to SIC5813
       MyFindNearbyCategorySpecification.Filter.EntityTypeName = "SIC5813";

    //Assign the FindNearbySpecification to the category
    category.FindNearbySpecification = MyFindNearbyCategorySpecification;

    //Now update the category
    serverAPI.UpdateNearbyCategory(category);

The find nearby category data source and entity type mapping have been changed from NavTech.NA and SIC3578 to Acxion.US.SIC_G.58 and SIC5813, respectively.

Finally, you can use the ServerAPI.DeleteNearbyCategory method to delete the existing nearby category definitions in the Microsoft Location Server. The DeleteNearbyCategory method takes the nearby category key name as an argument to delete the existing nearby category method. To delete the nearby category, dining places, call the DeleteNearbyCategory method:

    //Delete the category using the keyname value
    serverAPI.DeleteNearbyCategory("DiningPlaces");

The key name of the nearby category is the primary key within an instance of the Microsoft Location Server.