Using the Tracking Server Data Link ATL Class Template

Complexity: Beginner Data Requirement: ArcGIS Tutorial Data for Desktop

Prerequisite:

A data link provides a way to transfer data between Tracking Server and another entity.

The C++ Tracking Server Data Link Class Template can be used to create a custom data link.

Using the Tracking Server Data Link Class Template

CautionCaution:

When creating data links using the C++ ATL class template, make sure that the development drive is physically located on the same machine as Tracking Server. This is required due to file access permission issues with the system account that Tracking Server runs under.

Steps:
  1. Start Visual Studio and create a new project. The New Project dialog box appears.
  2. In the Project types listing, select Visual C++ > ATL.
  3. Select ATL Project from the list of installed templates.
  4. Enter additional information required for your new project and click OK to create the project. For example, you might want to change the name and location of your project.
  5. On the ATL Project Wizard dialog box, ensure that the server type is set to Dynamic-link Library (DLL) and no additional options are specified.
  6. Click Finish to create the project.
  7. Select the option to add a class to your new project. This can be done by selecting Project > Add Class from the main menu or right-clicking on the new ATL Project and selecting Add > Class. The Add Class dialog box appears.
  8. In the Categories listing, select Visual C++ > ArcGIS > TrackingServer.
  9. Select Tracking Datalink from the list of installed templates and click Add. The Tracking Server Datalink Wizard appears.
  10. Enter a name for the new data link class in the Name text box. This specifies the name of the class files that will be created as well as the name that will appear for the data link in the Data Links tab of Tracking Server Manager.
  11. Enter a description for the new data link in the Description text box. This description will appear in the Data Links tab of Tracking Server Manager.
  12. In the ArcGIS Engine/Desktop install directory text box, enter the path to your ArcGIS for Desktop or ArcGIS Engine for Windows installation location. For example, some common installation locations are “C:\Program Files\ArcGIS\Desktop10.1” and “C:\Program Files\ArcGIS\Engine10.1”.
  13. Click Finish to add the new class to your project. You will notice that several files have been added to your project.
  14. Add custom code to the classes in the project to achieve the desired result. To find the areas where it is suggested to modify the code, search for the phrase "TODO" throughout the entire project and follow the instructions.
  15. The sections following this general procedure provide more detailed instructions.
  16. Build the project.
  17. Your custom Tracking Server data link is ready for use.

    Your new custom Tracking Server data link will appear on the Data Links tab in the Tracking Server Manager.

The sections below contain more detailed information that will assist you when creating data links.

Adding Controls

The Resource View of your project shows a new dialog box that has been created with the name of your data link followed by “_CONFIG”. By default, this dialog box has controls used to control your data link including a status indicator and Start, Stop, and Cancel buttons. The methods to support these controls have already been added to yourdatalink_Config.cpp.

Steps:
  1. Navigate to the Resource View of your project. In the Dialog folder, open the dialog box that ends with _CONFIG. Add any controls needed for any communication parameters required to talk to the data source.
  2. Go to your string table and change the caption for the IDS_DataLink_Description to an appropriate description for your data link.
  3. Add code to the yourdatalink_Config.cpp file to manage the controls and parameters you have added.

    Most data link configurations store their parameters in the registry to simplify the access to the parameters by both the configuration and data transfer portion of the link.

  4. Compile and link your code.

    Now you should be able to test the configuration portion of the data link.

  5. Start the Tracking Server Manager and click the Data Links tab. The data link you just created should be in the list of data links.
  6. Double-click the new data link to display the configuration dialog box.

String Table

In the String Table, a string resource with the ID IDS_DataLink_Description is used to display a description on the Data Links tab of the Tracking Server Manager. Change this entry to provide a custom description of your data link that will be displayed on the Data Links tab of the Tracking Server Manager.

Customizing Data Transfer Operations

Now it is time to write the actual data transfer portion of your data link. The customization needed for the code depends on which direction your data is flowing. There are typically two ways this part of your data link can operate. First, it can connect to a data source, receive data, generate messages, and send them to Tracking Server. Second, it can connect to Tracking Server, receive data messages from it, and forward them to a waiting application.

Setting Up a Data Link to Send Data to an Outside Source

Steps:
  1. Search for the word TODO in the .cpp file named after your data link (yourdatalink.cpp).
  2. Use the provided comment block to retrieve configuration parameters from the registry—or wherever you wrote them—and place in connect method.
  3. Go to the method called ProcessQueuedMessageFromTMS and customize the provided comment block to parse or package any data received from Tracking Server and going out to a client.
  4. Go to the Run method and make sure the thread is shut down when the data link is stopped or disconnected.

    The data link runs in a multithread environment, so take care to shut down the thread.

    The following code represents the comment block from the ProcessQueuedMessageFromTMS method:

    HRESULT CoTMS_Datalink::ProcessQueuedMessageFromTMS(esriTrackingAnalyst::IMessage *piMsg)
    {
      enumMessageType          enumMsgType;
      HRESULT                  nEC = S_OK;
    
      nEC = piMsg->get_MessageType((enumMessageType *)&enumMsgType);
    
      if (SUCCEEDED(nEC))
      {
        switch(enumMsgType)
        {
    
        case msgtypeSTATUS:
        case msgtypeCOMMAND:
        case msgtypeRESPONSE:
        case msgtypeDATA:
          //
          // TODO add your code for processing the incoming message
          //
          break;
    
        default:
          break;
        }
      }
    
      return nEC;
    }
    
8/21/2012