Export (0) Print
Expand All

Step by Step: Develop a Location-Based Application on a Pocket PC Phone Edition by Using Microsoft MapPoint Location Server 1.0

 

Microsoft Corporation

February 2005

Applies to:
   Microsoft Visual Studio .NET 2003
   Windows Mobile-based Pocket PC Phone Editions
   Microsoft .NET Compact Framework version 1.0
   Microsoft Visual C#
   Microsoft MapPoint Location Server version 1.0

Summary: The objective of this exercise is for you to use the Microsoft .NET Compact Framework to create an application that will run on a Pocket PC Phone Edition. Through MapPoint Location Server, the application will get the real-time location of one of your contact's mobile devices and present a map of the location. This exercise should take 30 – 40 minutes to complete. (17 printed pages)


Download Developing Location-based Apps Using MapPoint Location Server.msi from the Microsoft Download Center.

Contents

Introduction
Part 1: Creating a New Project in Visual Studio
Part 2: Creating the UI
Part 3: Implementing the Code to Fetch a Contact List from MapPoint Location Server
Part 4: Implementing the Code to Get a Contact's Location
Part 5: Implementing the Code to Draw a Map of the Location
Part 6: Handling Zooming the Map In and Out
Summary
Appendix A: Configuring the Pocket PC Emulator for Internet Access
Appendix B: Using .NET Compact Framework 1.0 SP2

To complete this exercise, you will need:

  • Microsoft .NET Framework version 1.1
  • Microsoft .NET Compact Framework version 1.0*
  • ASP.NET version 1.1
  • Windows Mobile 2003-based Pocket PC emulator
  • Internet connection

*If your computer is using Compact Framework 1.0 SP2, please see Appendix B.

Introduction

Microsoft MapPoint Location Server is a new server product from Microsoft that enables developers to easily access multiple wireless operator networks to acquire the real-time locations of mobile phones. Developers acquire this information through the simple MapPoint Location Server application programming interface (API), which is consistent across all supported networks. For instance, a taxi company can install MapPoint Location Server and give each of its drivers a phone. This technology would enable the company to enhance its dispatch system by keeping track of drivers' locations in real time.

You will need to install MapPoint Location Server to run this exercise. MapPoint Location Server is available for download from the Microsoft Download Center.

Domain: mls
Username: bjohnson
Password: Password1!

If you do not have time to complete the exercise, but you want to view the completed application (and its code), see the accompanying download. Feel free to browse the application code and to build and run it.

Part 1: Creating a New Project in Visual Studio

In this part of the exercise, you will create a new smart device project in Microsoft Visual Studio .NET 2003. You will also add a Web reference to MapPoint Location Server.

To create a new project

  1. Create a folder named Labs on drive C of your computer.
  2. Copy the CompletedLabforMLS zipped file from the download, and then paste it into the Labs folder on drive C of your computer.
  3. Extract the files from this zipped file to C:\Labs.
  4. Start Visual Studio .NET 2003.
  5. On the File menu, point to New, and then click Project.
  6. Under Project Type, select Visual C#.
  7. Under Template, select Smart Device Application.
  8. Specify a name for the project: MyFirstMLSApp.
  9. Change the location to C:\Labs\CompletedLabForMLS, and then click OK. The Smart Device Project Wizard appears.
  10. Select the Pocket PC platform and Windows Application project type, and then click OK. Visual Studio opens Form1 in design view.
  11. In Solution Explorer (press CTRL+ALT+L if it is not visible), right-click the References folder, and then click Add Web Reference.
  12. In the Add Web Reference dialog box, in the URL box, specify the path to the Web Services Description Language (WSDL) file in MapPoint Location Server like this:

    https://mls.connectedinnovation.com/mmlsservice/locationserver.wsdl

  13. You are prompted for credentials to add the Web reference. Type your domain\username as the user name and your password, and then click OK. If you are prompted for a domain name, leave that field blank. You may be prompted a second time for your credentials and warned that they will be transmitted in plain text. Type them again, and then click OK.
  14. After the WSDL file has been retrieved, type MLSService as the name of the Web reference, and then click Add Reference.

Your project is now set up and the MapPoint Location Server reference is in place.

Part 2: Creating the UI

In this part of the exercise, you will add all of the user interface (UI) elements to the form. You will use a tab control with two tabs to hold your controls. The first tab will have text boxes to collect logon information and a drop-down list that will contain your locatable contacts. The second tab will have a picture box to hold the map and two buttons for zooming in and out.

Some of the illustrations in this part of the exercise are thumbnails. You can click the thumbnails for larger images.

To create the UI

  1. Drag a tab control onto the form from the toolbox (press CTRL+ALT+X to make the toolbox visible if it is not already). Name the control tabcontrol, and then resize it to fill the entire form.
  2. Right-click tabcontrol, and then click Properties. Scroll to the TabPages property, click the current value, and then click the ellipsis button, as shown in the following illustration.

  3. In the Collection editor, create a TabPage by clicking Add. Change the Name value to tpSearch, and then set its Text property to Search. Click OK.
  4. In Properties, click the current TabPages property value, and then click the ellipsis button.
  5. In the Collection editor, create another TabPage by clicking Add. Change the Name value to tpMap, and then set its Text property to Map. Click OK.
  6. Add three text box controls to the Search tab of your form. Name them txtUsername, txtPassword, and txtDomain.
  7. Clear the Text property for all three text boxes.
  8. Set the PasswordChar field for the txtPassword text box to an asterisk (*) so that your password is not displayed.
  9. Add a label above each of the text boxes to indicate the purpose of each text box. Change the Name and Text properties of these three text boxes to Username, Password, and Domain, respectively.
  10. Add a button near these three text boxes on the form. Set its Name property to btnRefresh and its Text property to Refresh Buddies.
  11. Add a combo box control to the form, and set its Name property to cmbWho.
  12. Add a label near the combo box, and set its Text property to Who do you want to find?.
  13. Add a button at the bottom of the form. Set its name to btnSearch and its Text property to Go!.

    The Search tab of your form should now look something like the following illustration.

    Click here for larger image

  14. Click the Map tab on the Form1 design. On the Map tab, add a button. Name it btnZoomin, and then set its Text property to Zoom in.
  15. Add another button to this tab, name it btnZoomout, and then set its Text property to Zoom out.
  16. Drag a picture box control (which you will use to draw your map) onto the form. Change its Name property to pbMap, and then resize it to fill as much of the form as you can.

    The Map tab of your form should now look like the following illustration.

    Click here for larger image

Your UI is complete.

Part 3: Implementing the Code to Fetch a Contact List from MapPoint Location Server

In this part of the exercise, you will begin adding code. More specifically, you will make a call to MapPoint Location Server to populate the list of locatable contacts.

Some of the illustrations in this part of the exercise are thumbnails. You can click the thumbnails for larger images.

To get a contact list from MapPoint Location Server

  1. On the Search tab, double-click the Refresh Buddies button. The Code view of the click handler for this button appears. Add the following code to the handler.
        try
        {
            //Declare an array of contacts to hold the 
            //results from the server. 
            LocatableContact[] myContacts ;
            
            //Set credentials by using the values that the user
            //provides on the form.
            SetCredentials();
    
            //Make the call to MapPoint Location Server.
            myContacts = locService.GetContacts();
    
            //Step through the results and put each one
            //in the combo box of locatable contacts.
            cmbWho.Items.Clear();
            foreach (LocatableContact who in myContacts )
            {
                cmbWho.Items.Add(who.DomainAlias);
            }
        }
        catch(Exception ex)
        {
            MessageBox.Show("Unable to get buddies." + ex.ToString());
        }
    
    
  2. The preceding code calls the SetCredentials method to get the form fields and set credentials to access the MapPoint services. Add this method now by scrolling down after the button handler, and then adding the following code.
    private void SetCredentials()
    {
        //Get the form fields and create a NetworkCredential object.
        string username  = txtUsername.Text ;
        string password = txtPassword.Text ;
        string domain = txtDomain.Text ;
    
        System.Net.NetworkCredential cred = 
            new System.Net.NetworkCredential(username,password,domain);
    
        //Apply these credentials to the two MapPoint services.
        locService.Credentials = cred;
        myRenderService.Credentials =  cred;
    
        //Set each service's URL manually.
        locService.Url = "https://mls.connectedinnovation.com/MMLSService/LocationService.asmx";
        myRenderService.Url = "https://mls.connectedinnovation.com/MMLSService/RenderService.asmx";
    }
    
    
  3. You are almost ready to compile and run this code, but first you need to declare a few variables and add a using clause to reference MapPoint Location Server. Scroll to the top of form1.cs, and add the following statement.
    using MyFirstMLSApp.MLSService;
    
    
  4. Scroll down just inside the declaration of public class Form1, and then add the following declarations. (Note that you will not need some of these declarations until you render a map in a later task.)
        //These are the three MapPoint services you will use.
        public RenderServiceSoap myRenderService = new RenderServiceSoap() ;
        public LocationServiceSoap locService = new LocationServiceSoap();
    
        // International settings. Can also be set for Europe and 
        // European languages.
        public string myDataSourceName  = "MapPoint.NA";
        public string myCountryRegion = "United States";
        public string myLanguage = "en";
    
        // Size of the map in pixels. This will be used for rendering
        // in addition to handling map click events (for re-centering).
        public int PixelWidth;
        public int PixelHeight; 
    
        // A MapView object is used for rendering the map. 
        // This object is set after doing a search, and is then 
        // used by the renderer.
        public ViewByHeightWidth[] myViews = new ViewByHeightWidth[1];
    
        // A collection of pushpins to draw on the map. 
        // In this application, a pushpin is created for 
        // each coffee shop found.
        public Pushpin[] POIPins ;
    
        // After finding a contact, this object is set with a new
        // value used to render a map. 
        public LatLong CenterPoint =new LatLong();
    
    
  5. At this point, you should be able to compile and run the application. On the Build menu, click Build Solution (or press CTRL+SHIFT+B). If you get any compile errors, fix your code and then recompile.
  6. To run the application, press F5. In the Deploy dialog box, select the emulator you want, and then click Deploy.

    The Emulator window opens, and your application starts.

    Note   If this is the first time you have run the emulator on this computer, you may need to configure it for Internet connectivity before the application will function properly. For information about configuring Internet connectivity for the emulator, see Appendix A at the end of this exercise.
  7. Specify the user name, password, and domain that you used previously, and then click the Refresh Buddies button.

    In a few moments, the combo box is populated with a list of your locatable contacts. Your screen then looks something like the following illustration.

    Click here for larger image

  8. Return to Visual Studio and exit the application by pressing SHIFT+F5.

Part 4: Implementing the Code to Get a Contact's Location

In this part of the exercise, you will write the code that runs when a user presses the Go! button. You will get the unique user identifier from the combo box, and then pass it to MapPoint Location Server. You will then receive information about the user, including his or her real-time location.

To get a contact's location

  1. On the Search tab, double-click the Go! button. Code view for the click handler for this button appears.
  2. Add the following code.
    //Set credentials.
    SetCredentials();
    
    //Initialize center point.
    CenterPoint = null;
    
    //Try to get the selected user's location from MapPoint Location Server
        try
        {
            PositionResults posRes = 
                locService.GetPositions(new string[] 
                {cmbWho.SelectedItem.ToString()});
    
            //If you find a position...
            if(posRes != null && posRes.PositionsFound > 0)
            {
                CenterPoint = posRes.Positions[0].LatLong;
    
                //Set MyViews. You will use this later to draw a map.
                myViews = new ViewByHeightWidth[1];
                myViews[0] = new ViewByHeightWidth();
                myViews[0].CenterPoint = new LatLong();
                myViews[0].CenterPoint = CenterPoint;
                myViews[0].Height = 1.0;
                myViews[0].Width = 1.0;
    
                //Create a pushpin at the found location.
                Pushpin pp = new Pushpin();
                pp.LatLong = this.CenterPoint;
                pp.Label = cmbWho.SelectedItem.ToString();
                pp.IconName = "1";
                pp.IconDataSource = "MapPoint.Icons";
                POIPins = new Pushpin[] {pp};
    
                //Set the tab control to the second tab (map).
                tabcontrol.SelectedIndex = 1;
    
                // Update the map to show the found location.
                refreshMap();
            }
        }
        catch(Exception ex)
        {
            MessageBox.Show("Unable to find the contact" + ex.ToString() , 
                "Locate Message");
            return;
        }
    
    
  3. Try to compile the application. You should get one error indicating that refreshMap does not exist. Scroll up and add a comment to the refreshMap call. You should then be able to compile and run the application.
  4. Set a breakpoint in the Go! button's handler on the call to GetPositions, and then run the application.
  5. After specifying your credentials and refreshing the contact list, select a contact, and then click Go!.
  6. Step through the code. When you reach your breakpoint, you should see that CenterPoint is set and a pushpin is created. You will use these items in the next task, when you draw a map.
  7. Remove the breakpoint in the Go! button's handler.
  8. For now, remove the comment you added to the refreshMap call.

Part 5: Implementing the Code to Draw a Map of the Location

In this task, you will make a call to the Map Render Service of the MapPoint Location Server to draw a map of the user's real-time location.

Some of the illustrations in this part of the exercise are thumbnails. You can click the thumbnails for larger images.

To draw a map of the user's location

  1. Insert the following code in form1.cs. You can place it after the Search button's click handler.
    private void refreshMap()
    {
        //Here a new map is requested from the server and displayed 
        //to the user on the Map tab of the tab control.
        try 
        {
    
            //Set credentials.
            SetCredentials();
    
            //Create a MapSpecification object to be passed to 
            //the renderer.
            //This object will hold all of the MapOptions and parameters.
            MapSpecification mapSpec  = new MapSpecification();
            mapSpec.DataSourceName = myDataSourceName;
    
            mapSpec.Views = myViews;
            
            //If you have pushpins or a route, include them.
            mapSpec.Pushpins = POIPins;
    
            //Request the map the exact same size as the picture box
            //it is going to be displayed in.
            PixelWidth = pbMap.Width;
            PixelHeight = pbMap.Height;
    
            mapSpec.Options = new MapOptions();
            mapSpec.Options.Format = new ImageFormat();
            mapSpec.Options.Format.Height = PixelHeight;
            mapSpec.Options.Format.Width = PixelWidth;
    
            //Request the map from MapPoint.
            MapImage[] mapImages = myRenderService.GetMap(mapSpec);
    
            //Display the resulting map in the picture box.
            System.IO.Stream streamImage;
            streamImage = 
                new System.IO.MemoryStream(mapImages[0].MimeData.Bits);
            Bitmap bitmapImage = new Bitmap(streamImage);
            pbMap.Image= bitmapImage;
    
        }    
        catch (  Exception ex) 
        {
            MessageBox.Show(ex.Message);
    
        }
    }
    
    
  2. Read through the comments in this block of code to understand what is happening.
  3. Press F5 to compile and run your application as before.
  4. Enter the appropriate information in the UI, and then click Refresh Buddies.
  5. Select mls/mblack from the drop-down list, and then click Go!.

    The emulator changes to the Map tab, and it displays a map centered at the found location, as shown in the following illustration.

    Click here for larger image

Congratulations! You have made a Simple Object Access Protocol (SOAP) call to an instance of MapPoint Location Server and retrieved the real-time location of a mobile phone.

Part 6: Handling Zooming the Map In and Out

In this part of the exercise, you will add a few lines of code to each of the zoom buttons on the Map tab to let the user zoom in and out. You will not implement panning in this exercise, but it takes only a few more lines of code to enable the user to re-center the map or to provide links for panning north, south, east, or west.

To enable zooming functionality

  1. Double-click the Zoom in button to display its click event handler in Code view.
  2. Add the following code to the event.
            // When they zoom in, take half of the current 
            //map zoom and refresh the display.
    
            myViews[0].Height = myViews[0].Height/2;
            myViews[0].Width = myViews[0].Width /2;
    
            refreshMap();
    
    
  3. Press SHIFT+F7.
  4. Double-click the Zoom out button to display its click event handler in Code view.
  5. For the Zoom out button, add the following code.
// Take the current map
        // zoom and double it, and then refresh the display.
        myViews[0].Height = myViews[0].Height* 2;
        myViews[0].Width = myViews[0].Width * 2;

        refreshMap();

  1. Press F5 to run your application one more time. After finding a contact, try the Zoom in and Zoom out buttons.

Summary

In this exercise, you performed the following activities:

  • Created a new project in Visual Studio
  • Created the UI
  • Implemented the code to fetch a contact list from MapPoint Location Server
  • Implemented the code to get a contact's location
  • Implemented the code to draw a map of the location
  • Handled zooming the map in and out

You built a Microsoft Visual C# application on the .NET Compact Framework that uses real-time location information from MapPoint Location Server. Although the scenario presented was simplistic, you should now see how simple it is to integrate real-time location into your own business applications, from fleet management and dispatch scenarios to mobile customer relationship management and sales force automation.

Appendix A: Configuring the Pocket PC Emulator for Internet Access

The easiest way to test Internet connectivity in the Pocket PC emulator is to run Microsoft Pocket Internet Explorer and browse to a public Web site. If you can browse to the site just as if you were using your desktop computer, you have Internet connectivity and can run the exercise application successfully.

If you receive an error when trying to browse, you need to configure the emulator.

To configure the emulator for Internet access

  1. On the emulator, click Start, click Settings, click Connections, and then click Connections.
  2. Set the settings to look like the following illustration.

    Click here for larger image

  3. Under Work Settings, click Modify.
  4. On the Proxy Settings tab, clear the check boxes, as shown in the following illustration.

    Click here for larger image

  5. Click OK to save your changes.
  6. Go back to Internet Explorer and browse again.

Appendix B: Using .NET Compact Framework 1.0 SP2

If your computer has .NET Compact Framework 1.0 SP2 installed and you have not updated the netcf.core.ppc3.ARM.cab and netcf.core.ppc3.x86.cab files in .NET Compact Framework 1.0, you need to update these files prior to beginning this task. The installation of SP2 does not automatically update these cabinet files for you.

To update the netcf.core.ppc3.ARM.cab and netcf.core.ppc3.x86.cab files in .NET Compact Framework 1.0

  1. Open two instances of My Computer.
  2. In the first instance, browse to C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\wce300\arm.
  3. In the second instance, browse to C:\Program Files\Microsoft .NET Compact Framework 1.0 SP2.
  4. Copy the netcf.core.ppc3.ARM.cab file from the second instance and paste it into the first instance.
  5. Click Yes to replace the existing file.
  6. Change the location of the first instance of My Computer to C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\wce300\x86.
  7. In the second instance, copy the netcf.core.ppc3.x86.cab file, and then paste it into the first instance.
  8. Click Yes to replace the existing file.
Show:
© 2014 Microsoft