This documentation is archived and is not being maintained.

Introduction to the Visual C++ Annotated Travel Log Starter Kit

Visual Studio 2005

Microsoft Corporation

May 2006

Applies to:
   Visual Studio 2005
   Visual C++


Getting Started
GPS Driver Configuration
How the Annotated Travel Log Works
Extending the Annotated Travel Log

Summary: Describes how the Visual C++ Annotated Travel Log Starter Kit works, and provides guidance on how you can customize it using Visual C++. (31 printed pages)

Download the sample that accompanies this article, CPPAnnotatedTravelLogSK.msi.


The Visual C++ Annotated Travel Log Starter Kit is a travel planning and tracking application that comes ready to compile and run. The planning component allows users to plan their travel by selecting an area on a map, defining intermediate points en route, and provides functionality to add media (images and videos) at particular locations. The tracking component then enables the user to add media points, associate a number of media files with each of the media points, and track the user's current location within the travel plan.

This document describes how one can build and make use of both components to perform each of the tasks mentioned above. The document also provides an overview of the architecture of the sample, which will help acquaint you with the overall functionality of the component.

The project comes ready to compile and run, and is easy to customize with only a little extra C++ programming. The section Extending the Annotated Travel Log contains a list of customizations you might make. You are also free to use the accompanying source code as the basis for your own travel planning projects, and share your work with others or upload it to the Internet.

Note   This documentation assumes that you have a basic knowledge of C++ programming concepts and the Visual Studio 2005 environment.


After reading through this starter kit documentation you will understand how the Annotated Travel Log program works, and a few ways in which you can customize it using Visual C++.

Getting Started

The sample contains two solutions, TravelLog and Journey.

TravelLog is the planning component that contains two projects:

  • TravelLog—This is a Windows Forms desktop application used for planning a trip. It implements logic for managing travel plans and importing and exporting to a handheld device. It can also export your plan as HTML, which can assist in easy blogging. It depends on ActiveSync (described below) to synchronize with a handheld device.
  • ActiveSync—This is a Win32 (native) component and is responsible for copying files from your desktop/computer to your device and vice versa. The component makes extensive use of the RAPI library, which can be found in the installation folder of the Windows Mobile 5.0 Pocket PC SDK. The same can be downloaded from the Windows Mobile Web site.

Journey is the tracking component that contains one project:

  • Journey—This is a Win32 (native) component used for tracking a trip. It implements logic for managing a travel plan on a PDA device running on the Windows Mobile 5.0 Pocket PC operating system.

Building and Running an Annotated Travel Log

Both of the components should be compiled separately. The sample contains two components, the planning component and the tracking component.


Planning Component (TravelLog): Before you open the solution you need to have Windows Mobile 5.0 SDK for Pocket PC installed on your machine. Once you have installed the SDK, open the solution in Microsoft Visual Studio 2005. You need to configure include and library paths for rapi.h and rapi.lib files as follows:

  1. In Visual Studio 2005, go to Tools->Options.
  2. In the Options dialog navigate to Projects and Solutions, then select the VC++ Directories node.
  3. From the Platform drop-down menu select Win32.
  4. For configuring the include files in the Show Directory drop down, select Include Files. Add a new line and browse to the installation folder Windows Mobile 5.0 Pocket PC SDK and select the \ActiveSync\Inc folder.
  5. For configuring the library files in the Show Directory drop down, select Library Files. Add a new line and browse to the installation folder Windows Mobile 5.0 Pocket PC SDK and select the \ActiveSync\Lib folder.
  6. Click OK.

After creating these settings, you will be able to build your solution successfully.

The TravelLog project has a Web reference to the staging environment of MapPoint Web services, which is used for testing and evaluation. If you have a MapPoint Web service evaluation account, you can access only the staging environment. Before deploying the Web service reference can be changed from staging to a production environment (fully scaled). More information can be found at MSDN.

Note   If timing out is an issue for Web service calls (at the time of execution), then it can be configured at the source-code level in Resource.resx by changing the TIMEOUT (string resource) value. It takes an integer value in milliseconds. Modifying this value requires the solution to be rebuilt.

Tracking Component (Journey): Once the required prerequisites are installed, simply build the attached solution using Visual Studio 2005 with the target device set to Windows Mobile 5.0 Pocket PC Emulator and deploy it [Build->Deploy Solution]. The Framework will take care of launching the emulator.

Note   In order to port to a PDA device, build the application using Windows Mobile 5.0 Pocket PC Device as the target device. The application can be ported only to a device with Windows Mobile 5.0 installed on it.

Using the planning component

Typically, you can follow the sequence below in order to use most of the features provided by the application.

  1. Load the world map.
  2. The user finds his intended location using search functionality.
  3. The user navigates within the map (using Zoom, Move, Drag).
  4. Freeze the map.
  5. Create a route by defining waypoints on the map.
  6. A waypoint can have map and route, recursively.
  7. Data can be exported to an XML file (Map, Route Info).
  8. User can import data (visited route) from XML.
  9. User can add/edit media files to plan.
  10. Export to HTML for blogging.

The following is an explanation of these features.

MapPoint Settings

Running the application for the first time shows the Settings window as shown below. This is one-time activity that is required to be configured for the application to start. This setting can be changed later from File>Settings menu.

Here the MapPoint Subscription Details consist of the username and password for accessing MapPoint Web services. A free evaluation account can be obtained here. If you are accessing the Internet through a proxy server, configuration can be done from this dialog. The proxy server address and port should be entered as shown in the example. Remove saved info deletes any saved settings on that machine.


Main Screen

After the settings are successfully created, the application starts and the following window displays. Here users can search for a location, find a map for it. or navigate through maps for further details.


Search Functionality

The user inputs the location name in the search pane and clicks on the search button. The list box is populated with the results of the searched location. The number of results found is displayed in the status bar. Double-clicking a particular result in the list box in order to load the map for the clicked location.


Status Bar

Navigation functionality

The user can navigate through the loaded map using the navigation panel. It provides the functionality of moving the map in all four directions. You can also navigate through the map by dragging it in the desired direction. This pane also allows zooming in/out for the current view. The zoom in button zooms in by 30% of the current view.



After users have navigated to a desired location, they need to freeze the map (using the Freeze button in the left pane) before they can start creating the actual route. This is the first top-level map and should cover the entire plan. You cannot point outside this defined view. Unfreezing allows users to change or enlarge navigation functionality, provided that there are no waypoints or mediapoints defined. If so, the users need to manually delete those waypoints and mediapoints.

Add/Edit/Delete Waypoint

After freezing the map, users can create a route by defining intermediate points. These points are called waypoints. To define a waypoint on a particular location, simply right-click on a location on map and select Add waypoint.


The next dialog enables users to enter waypoint information such as name, description, arrival date, and departure date. A waypoint must have name and arrival and departure date-time, where arrival date-time must be less than departure date-time.


To edit an existing waypoint, right-click to enable the Edit waypoint option in the context menu and to invoke a dialog similar to that of Add waypoint.


When users select Remove waypoint they are asked for confirmation for doing the same.

Add/Edit/Delete Mediapoint

A mediapoint is a set of media files associated with a particular location on the map. The files might have been recorded by a user during her trip or may be files on her computer. To add a media point it, is necessary for the current view to be frozen.

Define a mediapoint on a particular location by right-clicking a location on the map and selecting Add mediapoint.


A media point must have a name and at least one media file. To add a file to a mediapoint users must provide a title, a file path, and its type (Image / Audio / Video) and then click Add. This file is copied to the current directory named Media in the base folder of application. A mediapoint is displayed in red on the map. When the user hovers the mouse over the mediapoint, a tool tip shows details for it.

Edit mediapoints in the same way as you edit waypoints: right-click and select Edit mediapoint from the context menu. When the user selects Remove mediapoint he is asked for confirmation for doing the same. Note that the files added to that mediapoint are not deleted from the disk.

Nested Waypoints

On double-clicking a waypoint user are asked whether they want to have waypoints within this waypoint. In other words, a waypoint can further contain a set of other waypoints. This is will create a parent-child (in a tree-like structure) relationship for these two waypoints. On selecting Yes the zoomed map for that location is displayed and the parent waypoint's location is centered. The Previous button in the left pane is enabled so that you can return to the parent map.

Note   When a waypoint is added to second level (or higher) map, its arrival and departure date and time must fit within the parent's schedule.

Default plan

Set the current plan as default: This functionality sets currently opened plan as default. The next time the user opens the application it loads at startup. After you set the default it displays the following dialog.



You can fetch the latest data from MapPoint Web services by choosing Refresh. The keyboard shortcut is F5.

Export to HTML

This feature exports the current plan to HTML to the specified folder. The file that initially opens is index.htm. On the HTML pages waypoints and mediapoints are authored with tooltips. If a waypoint has a detailed plan there is a link pointing to it. All mediapoints and files are linked in separate HTML file.



When the user selects Synchronize desktop from the menu, the application asks him for both the source folder on the computer and then the destination folder on the device/PDA. In this way you can copy files from the folder on your computer to the device.

Similarly, you can synchronize the destination folder on the computer and source folder on the device. It confirms successful synchronization.

Note   The PDA device must be connected for synchronize to work properly. When the PDA is connected for the first time on a computer, it should be configured first through the Microsoft ActiveSync 3.8 application.

Using the tracking component

Before we go ahead, let's first get acquainted with the basic screen of the application.


The various icons on the screen have been numbered. The following table gives an overview of their functionality:

1MediaAllows the addition of mediapoints. The mediapoints may be added at a location specified by the user or at the current location of the user.


Zoom in, Zoom outUsed for zooming in and out of the map image.


NavigatorUsed to go to the previous map of the current plan.


MenuProvides the following options:


5MediapointRepresents a mediapoint on the Plan. Provides options for mediapoint management.
6WaypointRepresents a waypoint and provides options for viewing waypoint details.
7Start TrackingMakes use of the GPS device to plot the actual route taken by the user during his travel.

Importing a Travel Plan

Once the PDA device has been synchronized with the desktop component, one can ensure that the Travel Plan made on the desktop is available on the PDA device by synchronizing the two using ActiveSync.

While using the Emulator, however, one will have to share folders between the desktop and the Emulator. Here is how this is done:

  1. Once the emulator is launched, select File, the click Configure.


  2. In the Emulator Properties dialog displayed after choosing to configure, one can select the General tab and browse to the folder on the desktop that one wishes to share with the emulator.


    By following the above-mentioned steps, one can ensure that the travel plans and media files present on the desktop are also found on the emulator, simply by sharing the appropriate desktop folder with the emulator.

    The travel plans can now be consumed by the PDA component simply by using the Import option under the Menu tab and selecting the required XML plan.


    If the image corresponding to the plan is present on the PDA device/emulator, the application takes care of loading the plan.

    Note   One can only import plans that have been made by the desktop or PDA component of Travel Log.


    Green pins: Waypoints placed during the planning phase.
    Red Pins: Mediapoints placed while planning or during travel
    Green Route: Route planned on the desktop component
    Red Route: Route plotted during travel after using the Start Tracking option

Adding a mediapoint

In order to add a mediapoint, choose the media option on the tool bar. The user is then provided with the following options:

  • Add to the current location: The current location is obtained from the GPS device or an internal file, depending on how the GPS intermediate driver is configured.
  • Add to a specified location: The user is expected to provide appropriate latitude and longitude values. The user has to ensure that the values specified lie within the range of the map provided.


Managing mediapoints

On selecting a mediapoint on the plan, the user is provided with an Update Media Point dialog. Here one will find the following options that enable one to manage media points:

  • Add File: To add a new file to the mediapoint
  • Remove File: To remove the media file from the mediapoint
  • Delete Point: To remove the mediapoint. Once this is done the point will no longer be visible on the plan.
  • Update Point: To change the mediapoint name or its description


    On selecting the Add File option, the user can browse and select a media file to be associated with the mediapoint.


    Similarly, one can remove media files by selecting the Remove File button on Update Media Point dialog and selecting the file to be removed.


Viewing waypoint details

On selecting a waypoint, the WayPoint Details dialog box is shown. This may be used for two purposes:

  • View details of a waypoint: name, description, and so on
  • View a detailed map associated with the waypoint, if one exists


Partial plan management

During travel, after having added a few mediapoints, the user may want to stop the Travel Log application and resume some time later. In such a situation, the user can save his partial plan and open it later. This is achieved by using the Open and Save options on the Menu tab.


The user can start tracking his route by clicking on the track icon on the toolbar. No dialog box is displayed but the user's path is traced every minute. Of course, the user can continue performing other tasks synchronously.

Note   In order to use this feature, it is required that the PDA be connected to a GPS device or that the device driver is configured for using a file instead. If not, the application will display an error message.

GPS Driver Configuration

In order to communicate with the GPS device, the application makes use of the GPS Intermediate Driver provided by the Windows Mobile 5.0 SDK. The GPS Intermediate Driver uses the registry for two basic types of configuration information:

  • Connecting the GPS Intermediate Driver to GPS hardware
  • Providing data to applications that use the GPS Intermediate Driver

Using a Local File as the Source of Data for the GPS Intermediate Driver

As mentioned earlier, the GPS Intermediate Driver can be configured to use a GPS device or a file as the source of data. This section of the document will describe how the driver can be configured for using a file. In order to configure the driver we need to provide appropriate registry settings. Note that here we are looking at the Emulator's registry settings and not those of your desktop. In order to access the registry editor of the emulator, use the following path:

Programs->Microsoft Visual Studio 2005->Visual Studio Remote Tools->Remote Registry Editor

Here select the appropriate emulator—Windows Mobile 5.0 Pocket PC Emulator, in our case:


The editor then takes care of connecting to the emulator. We can then use this editor just as we would use the desktop editor for configuring the driver. The following steps will guide you through the process.

Under HKEY_LOCAL_MACHINE->System->CurrentControlSet, you find the key GPSIntermediateDriver. Here's where we will start configuring our driver.

  1. Add the DWORD key IsEnabled to GPSIntermediateDriver. Let its value be 1. This indicates that the device is enabled.


    Under GPSIntermediateDrivers we have another key called Drivers. Here we will add a string value called CurrentDriver and assign any string value to it. In our example it is TestFile. We then add another key with this value (TestFile) to Drivers.


    Under this new key (TestFile) we will add the following values:

File1StringThe location where the file can be found on the emulator.
InterfaceTypeStringFile: Default value indicating that the source is of the type "File".
FriendlyNameStringAny string value indicating an alternate name to the file.
IterationsSwordAny number indicating the number of times the driver will iterate through the file.

Use GPS Intermediate Driver Registry Settings to configure the driver for use with the GPS hardware.

Sharing Your Version of Annotated Travel Log with Friends

You can customize this program and share it with your friends and family. Please note that this application uses the .NET Framework version 2.0, so any computer running it needs to have this version of the .NET Framework installed on it.

How the Annotated Travel Log Works

Annotated Travel Log Architecture


Planning Component Layer Details

MapPoint layer

This layer interacts with MapPoint Web services. It provides functionality for searching, fetching maps, and converting latitude and longitude to (x,y) points and vice versa.

Import/Export Layer

The Import/Export layer provides the following features:

  • After the user has created the plan it can be exported to XML so that the tracking component can consume it. Similarly, it provides import functionality.
  • Once the tracking has been done this plan can be exported to HTML format with all media files. These HTML files can be used for blogging purposes.

Application logic layer

This layer holds the core functionality of Travel Log, the Desktop Component. It provides classes and structures for storing and manipulating data. It interacts with the MapPoint layer and the UI layer.

UI layer

It interacts with the Application logic layer and displays data using UI controls. It contains classes for creating Windows forms and provides functionality for managing waypoints and mediapoints and displaying maps to the user.

Recording Component Layer Details

Import/Export layer

The Import/Export layer provides the following features:

  • Having finalized a plan on the desktop component of Travel Log, this layer allows one to consume that plan on the PDA component.
  • On extension of a plan on the PDA, this layer allows one to convert the plan into a form (XML) that can then be consumed by the desktop component.

Thus, after a user has decided his waypoints for a trip and finalized his plan on the desktop, he can use that plan on his PDA and after having added a few mediapoints to the plan during his journey, he can port the plan back to his desktop with the help of the Import/Export layer. In simpler words, this layer facilitates interaction between the desktop component and the PDA component of Travel Log.

Application logic layer

This layer holds the core functionality of Travel Log, the PDA Component. It provides the following features:

  • Addition, deletion, and updating of mediapoints
  • Addition and deletion of media files
  • Addition of actual route points
  • Tracking of the user's path

In order to perform the above-mentioned tasks, the layer interacts with the Import/Export layer, the UI layer, and the GPS layer.

GPS layer

This layer takes care of interaction with the GPS device. For this purpose it makes use of GPS APIs provided by Windows Mobile 5.0 Pocket PC SDK. However, in order to make use of this layer, it is important that the GPS Intermediate Driver be configured properly.

The basic functionality provided by this layer is to start up the GPS device and get the current location whenever required by the Business Logic layer.

UI layer

The UI layer is responsible for exposing the Travel Log, or the PDA Component features, to the user. It interacts with the Business Logic layer for the same. This layer allows the user to:

  • Import a travel plan
  • Export a travel plan
  • Save and Open a partial plan
  • View a plan
  • Add and remove mediapoints
  • Add and remove media files from a mediapoint
  • View waypoint details

Travel Log solution files (planning component):

This solution contains two projects containing C++ source-code and graphics used by the starter kit. The source-code files perform the following functions:

User Interface


Contains the Main( ) method—the location where the program begins execution. It loads MainForm windows.

MainForm.h / MainForm.resx

These files contain the definition and implementation of MainForm, which is the main window of the application.

WayPointDetails.h / WayPointDetails.resx

These files contain definition and implementation for the WayPoint dialog for adding and editing waypoint details.

MediaPointDetails.h / MediaWayPointDetails.resx

These files contain definition and implementation for the MediaPoint dialog for adding and editing mediapoint details.

Settings.h / Settings.resx

These files contain definition and implementation for the Settings dialog used to take input from users.

InputBox.h / InputBox.resx

These files contain definition and implementation for a customized input box that enables the user to enter a folder path on the device.
Application Logic Layer


Stores found results returned by the FindMap class.

MapController.h / MapController.cpp

Stores the entire travel plan. The class MapController defines the travel plan.

Route.h / Route.cpp

Stores the planned route containing waypoints.


Stores the actual route visited by the user. This route may have mediapoints.


Used for serializing/deserializing the MapController object to provide functionality for saving/opening the current plan.


Stores details of found results.


Stores latitude and longitude of a location on earth.

WayPoint.h / Waypoint.cpp

Stores an intermediate point en route.


Stores the view for a map. View in terms of latitude and longitude bounds and height/width.


Stores collection of media files associated with a certain location.


Stores details of a media file.


Thrown by MapController.Move() when MapController is already frozen.


Thrown by MapController.RefreshMapWithRoute() when MapController is already frozen.


Thrown by MapController.Freeze() if tries to unfreeze and route is not empty.


Thrown by MapController.Move() when parent waypoint is out of current view.


Thrown by MapController.Zoom() when current zoom level becomes less than parent's zoom level.


Thrown if fewer than 2 waypoints are created and route is finalized.


Holds all required constants.


Utility functions.
MapPoint Layer


The FindMap class is used to interact with MapPoint Web services for searching a particular location.
RenderMap.h / RenderMap.cpp
This class is used to interact with MapPoint Web services for fetching map and converting points for (x,y) to LatLog and vice versa.
Import Export Layer
This class provides functionality for importing and/or exporting from XML and HTML formats.
ActiveSync Layer
This file has the functionality for copying files from desktop to device and vice-versa.
Miscellaneous Files
Holds string table and image files as resources for assembly.
Explains classes and files in this project.

Journey Solution Files (tracking component)

Import/Export Layer
ImportExport.cpp / ImportExport.h
Contains code for interpreting details from an XML-based file obtained from the desktop component and filling in local structures with appropriate information for use by the PDA component. Also contains code for formatting the details present in the local structure back into an XML file for use by the desktop component.

Business Logic Layer

ActualRoute.cpp / ActualRoute.h
Contains code for managing internal structures holding mediapoint details, mediafile details, and actual route details. Also contains code for interacting with the GPS layer for tracking the user's path.
MapController.cpp / MapController.h
Acts as a wrapper over the ActualRoute class.
GPS Layer
GPSWrapper.cpp / GPSWrapper.h
Contains code for initializing the GPS device and getting information about the current location. Requires the GPS Intermediate Driver to be configured appropriately.
UI Layer
JourneyView.cpp / JourneyView.h
Acts as a wrapper class that takes care of invoking appropriate methods on selection of icons and menu options on the main screen.
RemoveFileDlg.cpp / RemoveFileDlg.h
Handles the UI behavior for the Remove File dialog and interacts with the Business Logic Layer for file removal.
AddFileDlg.cpp / AddFileDlg.h
Handles the UI behavior for the Add File dialog and interacts with the Business Logic Layer for addition of files.
AddMediaPointDlg.cpp / AddMediaPointDlg.h
Handles the UI Behavior for Add MediaPoint dialog and interacts with the Business Logic Layer for the addition of mediapoints.
UpdateMediaPointDlg.cpp / UpdateMediaPointDlg.h
Handles the UI behavior for Update MediaPoint dialog and interacts with the Business Logic Layer for managing mediapoints.
WayPointDlg.cpp / WayPointDlg.h
Handles the UI behavior for the WayPoint Details dialog and interacts with the Business Logic Layer for providing waypoint details.

Extending the Annotated Travel Log

  • The application can be extended to have facility for creating waypoints at any zoom level. Moreover the freezing of the map can be optional.
  • Search functionality for waypoints/mediapoints in a plan can be extended.
  • Pre-fetching and caching of map images from MapPoint and to facilitate smooth dragging and zooming of the map.
  • Enhancements for points of interests for selected points can be made. The points of interests can include restaurants, lodging, drinking places, etc.; museums, art galleries, botanical and zoological gardens, airports, and so on can also be mapped.
  • Application can be extended to provide directions from one point to another (searching a route). This information can be based on less time or less distance.
  • Transparent Synchronization of Desktop and PDA components: This can be achieved by maintaining an independent application folder wherein we save our import-export files along with partial plans. In addition we can have serialized structures of finalized plans that will provide association between a plan, a mediapoint on the plan, and the links to corresponding media files. This way the user is only expected to choose to synchronize the two components and the application can take care of porting appropriate files to the PDA component. It will also make sure that files that will not be accepted by the PDA component—e.g., a Desktop partial plan—is not ported onto the PDA device. Similar changes will have to be made on the PDA component too.
  • More details during travel: The desktop component can access more details such as nearby hotels, hospitals, etc. using the MapPoint Web service. These details may be ported onto the PDA device and made accessible to the user whenever required during the travel.
  • Accessing media files on the PDA component: Currently the PDA component shows all the media files associates with a mediapoint. The user can choose to delete and add new media files. We can also provide the functionality for viewing media files by launching them using appropriate applications.
  • Travel Diary: We can provide a "personal diary" feature to the user wherein he can maintain logs of his journey and associate them with waypoints and mediapoints, as well as actual route points.
  • More control over tracking: Currently tracking is done every minute. We can allow the user to specify the time interval between calls to the tracking device. This will also help in performance improvement since ideally the user might not want to track his route every minute. Additionally, the Travel Log can provide another icon on the screen that enables the user to get details of the last time his position was tracked. This will be more user-friendly than having to use navigation keys to locate an actual route point which, in any case, won't be visible if the user is not within the limits of the map.