Developer Reference ManageENC API

  1. Home
  2. Developer Reference
  3. ManageENC API

Why?

The easiest way to get ENC charting installed for display is to just run ManageENC.exe or have your application run it for your customers to use.

If you want to install ENCs that are not in a transmittal, install a subset of a tranmittal or want to provide your own UI then you may want to control ManageENC programmatically via its COM API.

Registering the Library

You must first register the API on any machine you will use ManageENC on. This may have to be part of the installation for your application. You can do this from the command line by running ManageENC with the parameter -regserver. You can undo this registration using -unregserver.

C:\Program Files\ENCX SDK\Chart Management>ManageENC -regserver

You will need to be running as an administrator for this registration to succeed. On Windows 7 you should run the cmd.exe as an adminstrator (right click on Cmd.exe and choose "Run as Administrator" - do this even if you are logged in as an admin. (Yes, it's probably different if you've turned UAC off and Windows 7 and Vista behave differently and so on).

Adding a reference to ManageENC

Most programming environments then need you to add a reference to the API. In this article we use C# (if you do not know how to do it for your chosen programming tool please contact me and I'll try to help).

1. In your C# project in the solution explorer right click on References and choose Add Reference.

2. Choose the COM tab and Chersoft ManageENC 1.0 Type Library.

3. Click OK.

Adding a reference

Basics

ManageENC uses a background thread to actually do the work. Calling a method to install a transmittal just starts the process and returns control to you. Various events happen during an installation to allow you to track the install.

  • Messages. Text strings e.g. "Cell whatever installed and updated" suitable for displaying to the user in a box or logging to a file.
  • Progress. Percentage complete suitable for driving a progress bar in UI applications.
  • Finished. To tell you that your installation has finished.

This asynchronous call and events model is fine for most windowing UI applications which are very event driven anyway. But we did find that for console applications waiting for completion of an install got quite ugly. So we added a Busy property.

SENCS

SENC stands for System ENC and is the implementation specific way that ENC data is held. Different manufacturers have different SENC formats. This can give rise to confusion - a Chersoft SENC is not interchangable with a SevenCs SENC. In UI text we are moving towards calling the SENC an ENC Chart Folder to avoid burdening the user with jargon.

The method Manager.IsValidSencFolder will return true if you give it the path to a SENC. If you want to create a SENC at a particular place on your file structure call CreateSencFolder. The path must be to a non-existent folder or an empty folder.

Chersoft ENCX SENCs are compatible with Chersoft Henry Navigation System SENCs.

Installing a transmittal (simplest possible command line way)

Most functions in the API are accessed from the Manager class. There are a few other classes which support its operation.

ManageENC.Manager m = new ManageENC.Manager();
m.SencFolder = @"c:\mySenc";

The code above creates a manager and points it at a SENC. If there is not a SENC in the location specified an exception will be thrown. See SENCs above to find out how to find out if a folder is a valid SENC or not.

m.InstallTransmittal(@"d:\sampledata\transmittal");
while (app.Busy)
{
    System.Threading.Thread.Sleep(100);
}

InstallTransmittal starts the transmittal installing and returns control to our program. If we had registered for progress and other notifications we would receive updates during the installation. Instead we just wait until the transmittal finishes by repeatedly polling the Manager.Busy property and then sleeping for a tenth of a second.

Installing a transmittal (more polished windows UI way)

These are excerpts from the snappily named InstallCellsWithManageENC sample. Full source code download available.

As can be seen from the screen shot the application has a box for logging messages and two progress bars. One progress bar charts the progress of the installation of the current cell and the other the overall progress. There's also a stop button. As noted above the sample code is available for download. Here I will just draw attention to a few important points...

We have to register to receive events telling us of progress and so on. Do it like this...

manageEnc.OnFinished += new _IManagerEvents_OnFinishedEventHandler(manageEnc_OnFinished);
manageEnc.OnMessage += new _IManagerEvents_OnMessageEventHandler(manageEnc_OnMessage);
manageEnc.OnProgress += new _IManagerEvents_OnProgressEventHandler(manageEnc_OnProgress);

The sample has 3 event handling methods...

void manageEnc_OnProgress(int nProgress, int nOverall, string sDescription)
{
    ControlSetter.SetLabel(labelActivity, sDescription);
    ControlSetter.SetProgressBar(progressTop, nProgress);
    ControlSetter.SetProgressBar(progressBottom, nOverall);
}

void manageEnc_OnMessage(string sInfo)
{
    ControlSetter.AddLine(messages, sInfo);
}

void manageEnc_OnFinished()
{
    ControlSetter.AddLine(messages, "Finished");
    ControlSetter.Enable(buttonStop, false);
}

ControlSetter is a helper class to handle a threading issue that can arise where an event happens on a different thread to the main UI thread (in which the UI's control where created). The presence of this situation is detected using the InvokeRequired property of the control (e.g. a progress bar) and if invoke is required the Invoke method is used to control the control. All this made the sample more difficult to understand so this stuff has been hidden away in the ControlSetter class.

Enumerating the cells in a transmittal

A subset of the cells in a collection can be installed using the Manager.InstallCells method. In order to build up your list of cells to install ManageENC allows you to enumerate the cells in a transmittal using the EnumCells method.

ICells cells = manager.EnumCells(@"c:\sampleData\transmittalPath);
foreach(ICell cell in cells)
{
    Console.WriteLine(cell.Name);
}

That code lists the cells in a transmittal to the console.

Partial installation of a transmittal

You can create a CellsForUpdate object and add cell names to it. The CellsForUpdate object is then passed to the Manager.InstallCells method along with the transmittal path and only cells in the CellsForUpdate from the transmittal are installed or updated.

The following code just installs the Harbour cells from a transmittal:

string transPath = @"d:\sample\trans";
ICells cells = m.EnumCells(transPath );
CellsForUpdate cellsHarbor = new CellsForUpdate();
foreach(ICell cell in cells)
{
    if(cell.NavPurpose == 5) // 5 == "ENC Harbour"
    {
        cellsHarbor.Add(cell.Name);
    }
}
m.InstallCells(transPath, cellsHarbor);

Installing Permits

If you are installing encrypted commercial ENCs you need to install the Permits for the ENCs before you install the chart data. Calling InstallPermit method on your Manager object will merge a permit file into the permits already held in the SENC. Permits are provided by chart suppliers in a file called PERMIT.TXT (some chart suppliers might supply this file as part of a zip archive).

Stopping

You can request that installation of permits or cells is stopped by calling Stop on your manager object. The installation hasn't stopped until you get a Finished event and the Busy property becomes false. Cells or permits that have been completely installed stay in the SENC (i.e. there is no rollback, this is stop not cancel). The InstallCellsWithManageENC sample demonstrates this. See downloads.