==============================================================================
  CGOS Library API for the .NET Framework                  DATE: 2016.02.17
==============================================================================

PURPOSE:
--------

The CGOS (congatec OS) Library API provides access to congatec specific board
information and features.

The API is compatible and identical across all congatec boards and all 
supported operating systems.

the CgosClr is compatible with all current versions of the .NET Framework 
including version 4.5.

The CgosClr.dll is an assembly that allows easy access to the CGOS API from 
CLR (Common Language Runtime) .NET Framework languages like C#, Visual Basic, 
J#, and managed C++.

In an effort to maintain maximum compatibility with other platforms all 
CGOS function calls and parameters, their order and semantics are identical 
to the native CGOS API.

All declarations are made in the CgosClr name space.

All functions and all constants are defined static in the class Cgos. So they 
must be prefixed by "Cgos." when used.

All typedef structures are defined as individual classes.

To provide ease of use under CLR languages some data types have changed.
Most parameters are 32 bit unsigned so they use UInt32 which turns into 
uint for C# and UInteger for VB.

The HCGOS CGOS handle also uses that type and must be explicitly passed to each
function.

Most return values are Boolean.

All strings use the String class with the exception of returned strings which use
the StringBuilder class.

Please refer to the CGOS API documentation for further details.

Below are two samples that show the syntax of how to use the API and pass parameters
under C# and VB.


.NET Framework Versions:
------------------------

The standard assembly is compiled against .NET Framework 2.0. This can also be under 
.NET 4.0 and later.

However as with any assembly that also works with older framework versions you 
need to make a small change to your project's app.config file.

With C# this file is created by default. 

With VB you need to create it like this:
In Visual Studio 2010 or later in the Solution Explorer pane select the project.
Right click and an then Add New Item.
Under Common Items select General and then Application Configuration File.
Click the Add button.

After the second line in app.config with <configuration> add these lines:
    <startup useLegacyV2RuntimeActivationPolicy="true">
       <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0,Profile=Client" />
    </startup>

Alternatively you can also create a file named YOURAPP.exe.config with the 
following content:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <startup useLegacyV2RuntimeActivationPolicy="true"> 
       <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0,Profile=Client" />
    </startup>
</configuration>

Please note that the above .config file needs to be shipped and 
reside in the same directory as the .exe

Alternatively FOR YOUR CONVENIENCE we also provide a build of CgosClr that is compiled 
against .NET 4.0 in the NETV4 directory which does not require the above steps.


32 vs. 64 bits:
---------------

By default CgosClr uses the 32-bit version of the CGOS.DLL. This is the prefered way even 
on 64 bit systems. You need to set the x86 architecture instead of "Any CPU" 
in your application.

Alternatively you can also mark the executable with the .NET Framework tool CorFlags:
CorFlags.exe" MyApp.exe /32bit+

Alternatively FOR YOUR CONVENIENCE we also provide a build of CgosClr that is compiled 
to use the 64 bit version of CGOS.DLL which does not require the above steps.


Strong Name:
------------

The recommendation is to use the default CgosClr versions that do not enforce version numbers.
We also provide a version that enforces strong names and can be uses in the GAC.
Please note that you need to build you application with a reference to the strong name
CgosClr. This means that you need to RECOMPILE your application whenever the CgosClr is
updated. You also cannot go back to the standard version without recompiling.
For those reasons it is not recommended to use the strong name version.


CgosClr Versions:
-----------------

CgosClr.dll             x86, Framework V2.0++, DEFAULT, RECOMMENDED, works on all versions
NETV2x64\CgosClr.dll    x64, Framework V2.0++
NETV4\CgosClr.dll       x86, Framework V4.0++
NETV4x64\CgosClr.dll    x64, Framework V4.0++
NETV4SN\CgosClr.dll     x86, Framework V4.0++, Strong Name
NETV4SNx64\CgosClr.dll  x64, Framework V4.0++, Strong Name


c# Sample Application:
----------------------

using System;
using System.Text;

using CgosClr;

namespace CgosClrTestCS
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("CgosClrTestCS");
            
            Console.WriteLine("Cgos Library Version {0:X8}", Cgos.CgosLibGetVersion());
            if (!Cgos.CgosLibInitialize())
                Console.WriteLine("Could not open Cgos library.");

            Console.WriteLine("# of Boards: {0}", Cgos.CgosBoardCount(0, 0));

            bool ret;
            uint hCgos=0;
            Console.Write("Opening first board: ");
            ret = Cgos.CgosBoardOpen(0, 0, 0, ref hCgos);
            Console.WriteLine("ret {0} hCgos {1}", ret, hCgos);

            StringBuilder sb=new StringBuilder((int)Cgos.CGOS_BOARD_MAX_SIZE_ID_STRING);
            ret = Cgos.CgosBoardGetName(hCgos, sb, (uint)sb.Capacity);
            Console.WriteLine("Board name: {0}", sb);

            uint i=0;
            ret = Cgos.CgosBoardGetBootCounter(hCgos, ref i);

            CGOSBOARDINFO bi = new CGOSBOARDINFO();
            Cgos.CgosBoardGetInfo(hCgos,bi);
            Console.WriteLine("Serial Number: {0}",bi.szSerialNumber);
            
            i = Cgos.CgosStorageAreaSize(hCgos, Cgos.CGOS_STORAGE_AREA_EEPROM);
            Console.WriteLine("EEPROM User Bytes Size: {0}", i);

            byte[] b=new byte[8];
            Cgos.CgosStorageAreaRead(hCgos,Cgos.CGOS_STORAGE_AREA_EEPROM,0,ref b[0],(uint)b.Length);
            Console.Write("EEPROM User Bytes: ");
            foreach (byte bb in b) Console.Write("{0:X2} ", bb);
            Console.WriteLine();

            Cgos.CgosBoardClose(hCgos);
            Cgos.CgosLibUninitialize();
        }
    }
}



Visual Basic Sample Application:
--------------------------------

Module Module1

    Sub Main()
        Console.WriteLine("CgosClrTestVB")
        Console.WriteLine("Cgos Library Version {0:X8}", Cgos.CgosLibGetVersion())
        If Not Cgos.CgosLibInitialize() Then
            Console.WriteLine("Could not open Cgos library.")
        End If

        Dim i As UInteger
        Dim hCgos As UInteger
        Cgos.CgosBoardOpen(0, 0, 0, hCgos)

        i = Cgos.CgosStorageAreaSize(hCgos, 0)

        Dim bi As New CGOSBOARDINFO
        Cgos.CgosBoardGetInfo(hCgos, bi)

        Dim b(7) As Byte
        Cgos.CgosStorageAreaRead(hCgos, Cgos.CGOS_STORAGE_AREA_EEPROM, 0, b(0), b.Length)
        i = Cgos.CgosStorageAreaSize(hCgos, Cgos.CGOS_STORAGE_AREA_EEPROM)

        Cgos.CgosBoardClose(hCgos)
        Cgos.CgosLibUninitialize()

    End Sub

End Module