Follow

Workmates component programming

Introduction

Workmates is the feature that enables drivers to see the positions of their colleagues ("Workmates") on the navigation screen of their devices. This helps them work even more efficiently as it simplifies the coordination and the communication among them. This feature can be used by taxi companies that are able to cover the whole area of the city and serve customers even faster. Or it can be used to save seconds when heading to emergency events and accidents is crucial for police, firemen and rescue force teams.

Concept

The Workmates functionality is enabled by use of Workmates Library provided as dll/dlls.
The Workmates functionality is woven into navigation for an easy access and convenient visualization on Sygic map.
Workmates are injected into and managed inside navigation via a set of API calls, thus providing the means for a partner application to gain full control on workmates' visualization per device.
The Workmate API actually assumes the external system (typically partners' database system) maintains the positioning of workmates, while it synchronizes the state with Sygic navigation over Workmate API to individual devices.

Please note there is a difference between Sygic SDK library and Sygic Workmates library in that that the Workmates API calls can be used even without navigation running.

Requirements and limitations

The library is currently supported for the following OS platforms:

  • WindowsXP
  • WindowsCE ARM

And the following programming environments:

  • Visual Studio 2005 or 2008 for .NET application for WindowsCE
  • Visual Studio 2005 or 2008 for .CPP application for WindowsCE
  • Visual Studio 2005 or higher for .NET applications for WindowsXP

The library is currently supported with the navigation version Sygic Fleet 2D release 15h build 00179 or newer.

For navigation to open up the workmates functionality:

  • the configuration file (settings.ini) must contain the two settings: externalFriends=true and friends=on
  • the navigation license (mlm file) must contain the geofiles permission: geofiles=yes

Try demo

1. Getting library

The library with examples is provided in a standalone package.
In order to obtain the package please Contact our sales.

The package content is as follows:

   Drivers\
     WindowsCE\
       WorkmateAPI.dll
     WindowsXP\
       WorkmatesAPI.dll
   Include\
   Lib\
     .NET\
       WorkmatesAPI.NET.dll
     CPP\
       WindowsCE\
         WorkmateAPI.lib
       WindowsXP\
         WorkmatesAPI.lib
   Examples\

2. Configuration

1. For using the library in application development (compilation process) you need to include the proper dll into your project through Add Reference

  • for .NET projects: Lib/.NET/WorkmateAPI.NET.dll
  • for CPP projects on WindowsCE: Lib/CPP/WindowsCE/WorkmateAPI.lib
  • for CPP projects on WindowsXP: Lib/CPP/WindowsXP/WorkmateAPI.lib

2. For application running properly (runtime operation) you need to copy the proper dll(s) next to the application exe file:

  • for .NET projects on WindowsCE: Lib/.NET/WorkmateAPI.NET.dll and Drivers/WindowsCE/WorkmateAPI.dll
  • for .NET projects on WindowsXP: Lib/.NET/WorkmateAPI.NET.dll and Drivers/WindowsXP/WorkmateAPI.dll
  • for CPP projects on WindowsCE: Drivers/WindowsCE/WorkmateAPI.dll
  • for CPP projects on WindowsXP: Drivers/WindowsXP/WorkmateAPI.dll

3. Examples

The library package contains the following examples:

  • WorkmateExampleXP
  • WorkmateExampleCE

The examples can be open through the sln file and compiled by a single click.
For the application to run correctly, please make sure you copy the correct dll(s) next to the application exe as mentioned in the Configuration section.

4. Functional behavior

If correctly set the Sygic navigation opens the Workmates functionality through the Workmates menu icon as shown bellow.

workmates in menu

By entering the Workmate menu a list of existing workmates is presented. You can see the status of workmates and through a single click you can visualize them on map.

workmates in list

On the map the workmate is represented by an icon, avatar and the status.

workmates on map

Library overview

The library is designed so that it allows synchronization of workmates being managed in an external database system into Sygic navigation.
The data are synchronized into the main.dat file, which is the navigation's local database system.
Sygic navigation makes sure the data changes on main.dat are immediately reacted upon.
E.g. updating a workmate GPS position will automatically adapt workmate visualisation on map accordingly.

The library supports the following operations:

-->

OperationDescription
Initialization Opening the API by providing the path to the navigations main.dat
Add Workmate Adding workmate into Workmate list
Delete Workmate Deleting workmate from Workmate list
Update Workmate Changing attributes of a workmate, e.g. name, email, icon, etc.
Set Workmate Address Setting the address or GPS position of a workmate
Clear workmate list Clearing Workmate list
Close API  

The details can be found in Workmates Reference Manual

Getting started

In this section we will show the programming the typical operations when exploiting workmates functionality, such as:

  • initialization
  • managing collection of workmates
  • set and update positions
  • closing

1. Initialization

The initialization of the API is done through the function InitWorkmatesAPI. The input to the function is the path to the navigation's main.dat file.
The function returns the integer, which defines the success or failure of the operation as follows (similarly other functions):

  • ReturnCode.FunctionFailed
  • ReturnCode.FunctionSuccess
    using Workmates;
    ...
    string localdb = "c:/Sygic/Res/main.dat";
    ReturnCode ret = WorkmateApi.InitWorkmateApi(localdb);
    if (ret != ReturnCode.FunctionSuccess)
    {
      // error
    }

2. Managing Workmates

The management of workmates is supported by the operation of inserting, updating and deleting workmate in the local database of Sygic navigation.
The 3 operations work with the class Workmate, which encapsulates various attributes. In this example the functions InsertWorkmate, UpdateWorkmate and DeleteWorkmate are shown.
The important parameter to all of the functions is workmateId, which defines the unique reference to a workmate. The function InsertWorkmate defines the id, while the functions UpdateWorkmate and DeleteWorkmate must follow it. The parameter avatar defines the picture the workmate is visualy presented with in Workmate menus. The value is the name of the picture inside of the Res/avatars folder.
The parameter mapIcon defines the picture the workmate is visually presented on map. The value is the name of the picture inside of the Res/icons/friends folder.

     int workmateId = 1001;
     ReturnCode ret;

     // insert
     string email = "tt@company.com"
     string firstName = "Tim";
     string lastName = "Taylor";
     string iso = "GBR";
     string avatar = "myAvatar.jpg";
     string mapIcon = "_cop.bmp";
     Workmate workmate = new Workmate(email, avatar, firstName, lastName, iso, mapIcon);
     ret = WorkmateApi.InsertWorkmate(workmateId, workmate);

     // update
     workmate.FirstName = "Peter";
     ret = WorkmateApi.UpdateWorkmate(workmateId, workmate);

     // delete
     if (WorkmateApi.CheckWorkmateExists(workmate.ID, out bExists) == ReturnCode.FunctionSuccess)
     {
        if (bExists) ret = WorkmateApi.DeleteWorkmate(workmateId);
     }

3. Set and Update the Workmate position

The operations work with the class WorkmateAddress, which encapsulates attributes related to a position.
In this example the function SetWorkmateAddress shows how to set and update the address of a workmate.
The position is defined through PosX and PosY attributes, which mean Latitude and Longitude coordinates multiplied by 10000 to be representable by integer.
The destination is the string describing an address in a free form.

     // set
     int workmateId = 1001;
     int posX = 0;
     int posY = 5150111;
     string destination = "London centre";
     address = new WorkmateAddress(destination, posX, posY);
     ReturnCode ret = WorkmateApi.SetWorkmateAddress(workmateId, address);

     // modify
     address.PosX = 0;
     address.PosY = 5150222;
     ReturnCode ret = WorkmateApi.SetWorkmateAddress(workmateId, address);

4. Closing API

The closing operation is done by the function CloseWorkmateApi.
Before closing API it is recommended to verify the API status with the IsOpen function.
This way you prevent raising exception when closing API on an already closed API.

    if (WorkmateApi.IsOpen())
    {
       WorkmateApi.CloseWorkmateApi();
    }
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments