Section 10.2. Programming with the Location Server Management API


10.2. Programming with the Location Server Management API

You use the Microsoft Location Server management API to develop server-side applications for Microsoft Location Server. Server-side applications include applications for provisioning users within an enterprise, automating the addition and removal of contact lists for provisioned users, removing provisioned users, and so on. Note that the management API does not expose a real-time location API. To program with the management API, you need to add the following assemblies as references to your project:


Microsoft.MapPoint.LocationServer.Types.dll

Contains Microsoft Location Server data types.


Microsoft.MapPoint.LocationServer.Management.dll

Contains classes that provide methods for managing Microsoft Location Server. In this assembly, the type ServerAPI exposes methods to manage Microsoft Location Server.


Microsoft.MapPoint.LocationServer.Core.dll

Contains classes required by the management API types. This assembly should be used only to add as a reference to your project; do not use types from this assembly directly in your source code.

In the following sections, we'll look at the Microsoft Location Server management API in detail.

10.2.1. Anatomy of Location Server Management APIs

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:


User management

Enables you to develop applications to add new users and update existing users in the Microsoft Location Server.


Contact management

Enables you to develop applications to add, update, and remove the contacts for the provisioned users.


Privacy management

Enables you to develop applications to modify provisioned user privacy settings.


Find nearby category management

Enables you to develop applications to add, update and remove find nearby categories.

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

Table 10-2. ServerAPI class methods

Method

Description

Initialize

Initializes a connection to the MapPoint Location Server database. Call this method on a ServerAPI instance.

GetContacts

Returns a list of contacts as an array of LocatableContact objects for the user represented by the domain and alias.

AddContact

Adds a new contact for a given user.

UpdateContact

Updates a specified contact in a given user's contacts list.

DeleteContact

Deletes the specified contact from the contacts list of a given user.

FindProvisionedUser

Allows partial input of LocatableUser object properties or an email address of a user to search provisioned MapPoint Location Server users and returns contact information as an array of LocatableContact instances.

GetdefaultCulture

Retrieves the default culture for a given user, in string format (e.g., "en-US" for English, United States).

SetDefaultCulture

Sets the default culture for a given user.

AddUser

Adds a new user to MapPoint Location Server. Adding a user is also called provisioning a user.

UpdateUser

Updates an existing user (a user that has already been provisioned) in MapPoint Location Server.

DeleteUser

Deletes an existing (provisioned) user from the MapPoint Location Server.

GetAllUsers

Returns all provisioned users as an array of strings in MapPoint Location Server.

GetLocatableUser

Searches for a provisioned user by domain and alias.

GetNewContactNotification

Gets the NotifyOnNewContact property of the LocatableUser object for the user identified by the domain and alias.

SetNewContactNotification

Sets the NotifyOnNewContact property of the LocatableUser object for the user identified by the domain and alias.

GetVisibility

Gets the Visible property of the LocatableUser object that represents the user identified by the domain and alias.

SetVisibility

Determines whether the user is visible to other users or contacts.

GetNearbyCategories

Gets the Find Nearby categories as an array of FindNearbyCategory objects based on the culture name.

AddNearbyCategory

Adds a Find Nearby category to MapPoint Location Server.

UpdateNearbyCategory

Updates an existing nearby category in the MapPoint Location Server.

DeleteNearbyCategory

Deletes an existing Find Nearby category from the MapPoint Location Server.


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.

If you are using the ServerAPI class to develop applications for Microsoft Location Server, make sure to invoke the Initialize method before calling any other methods of the ServerAPI class. This method call is required to establish a connection to the Microsoft Location Server database.


10.2.2. Programming User Management

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.

10.2.2.1. Adding users

The ServerAPI class in the Microsoft.MapPoint.LocationServer.Management.dll assembly exposes the method AddUser, which is used to provision users for Microsoft Location Server. This method takes a LocatableUser instance as an input parameter. A LocatableUser instance is an object representation of a domain user with a unique locatable endpoint (a phone number). The following code shows how to provision a user:

     //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 = @"domain\user";      //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      . . .     }

In this code, a user with the domain alias "domain\user" has been added to the Microsoft Location Server. Note that the LocatableEndPoint (phone number), LocationProviderName, NotificationEndPoint (email address or SMS number), and NotificationProviderName are optional parameters; however, domain alias and default culture name are mandatory to add a new user. Also note that any newly added provisioned user will be visible by default.

10.2.2.2. Managing provisioned users

Similar to the AddUser method, the ServerAPI class also provides methods for managing users who are already provisioned. You can use the DeleteUser method to delete a provisioned user from Microsoft Location Server, and the UpdateUser method to update the properties of a provisioned user. The following code shows how to update a provisioned user's locatable phone number:

     //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 = @"DOMAIN\user";       //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       . . .     } 

In this code, both the default culture and phone number are updated using the ServerAPI.UpdateUser method. Note that you cannot update the user's domain alias using the UpdateUser method.

10.2.3. Programming Privacy Management

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 DOMAIN\user       //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(@"DOMAIN\user", 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.

10.2.4. Programming Contact Management

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 = @"domain\user";     //Contact domain alias     string contactAlias = @"domain\newcontact";     try     {         LocatableContact locatableContact =                   serverAPI.AddContact(userAlias, contactAlias, true, true);      . . .     }     catch(Exception exception)     {      //Process exceptions      . . .     }

In this code, a new contact, "domain\newcontact" has been added to the provisioned user "domain\user" 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 = @"domain\user";     //Contact domain alias     string contactAlias = @"domain\newcontact";     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.

10.2.5. Programming Find Nearby Category Management

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:

  1. Find nearby category name.

  2. Find nearby category culture and distance unit.

  3. Find nearby category localized names (to display them in different cultures).

  4. Find the entity type that defines the find nearby category.

  5. Apply this to a MapPoint Web Service data source name that contains the entity type specified in item 4.

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.




Programming MapPoint in  .NET
Programming MapPoint in .NET
ISBN: 0596009062
EAN: 2147483647
Year: 2005
Pages: 136
Authors: Chandu Thota

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net