#################
Programming Guide
#################

***************
Getting Started
***************

The HOOPS CAE Data Provider Framework is a part of the "|ProductName|" distribution and can be downloaded from 
https://developer.techsoft3d.com. The data provider framework is found in the **DataProviderFramework** folder in the 
Envision distribution. The data provider framework is provided as source code so you can compile with your favorite 
compiler and settings.

To compile the framework, example plugins and example apps, we recommend using CMake. Download CMake from 
https://cmake.org/download/.

To build and run the examples, please follow the steps below:

-   Unzip the "|ProductName|" distribution file info a folder
-   Go to the DataProviderFramework folder in the distribution.
-   Create a build folder (e.g. Build on the same level as DataProvider)
-   `> cd Build`
-   `> cmake ../DataProvider`

On Linux/mac, build the solution with:

::

    > make

On Windows, open the project file and build with the selected compiler (e.g. Visual Studio).

The build step will build:

-   DataProviderHostLib
-   MinimalPlugin
-   TestDriver

To run the test driver:

::

    cd ExampleApps/TestDriver/
    ./TestDriver ../../ExamplePlugins/MinimalPlugin/cdp_MinimalPlugin MINIMAL


*****************************
Creating a DataProviderPlugin
*****************************

There are three steps to creating a DataProviderPlugin

**Step 1: Create the plugin**

The main file defines the plugin. You define a version and a method for creating the Factory. One file can contain many 
data providers. The :func:`initializeDataProviderPlugin` method is called by the host to initialize the 
provider(s).

Example: MinimalPlugin.cpp

**Step 2: Create the data provider factory**

The factory is responsible for instantiation and deletion of the DataProvider, providing information about the provider 
and checking if the provided ModelKey is supported by the provider. To create the factory, derive from 
:class:`CDPDataProviderFactory` and implement the 4 pure virtual methods.

Example: MinimalProviderFactory.h/cpp

**Step 3: Create the data provider**

The provider is where all the CAE data is communicated to the host. To create a provider, derive from 
:class:`CDPDataProvider` and implement the 7 pure virtual methods.

Example: MinimalProvider.h/cpp

****************************************
Using Data Providers in |WebProductName|
****************************************

Data providers can be used with the RemoteModel server (CeeCloudServer). To load your data provider, set the 
`C3_UG_DATA_PROVIDER_FOLDER` environment variable to point to the folder with your data provider. The CeeCloudServer 
will load all data providers in the specified folder. The data provider needs to comply to the following naming scheme:

    cdp_{PROVIDER_NAME}.[dll|so|dylib]

Example:

    cdp_MyDataProvider.dll (Windows), cdp_MyDataProvider.so (Linux)

The server will list the registered data providers when a file is opened.

*****************************************
Using Data Providers in Envision Analyzer 
*****************************************

To use your data provider with HOOPS Envision Analyzer Desktop, define the environment variable 
`CEE_DATA_PROVIDERS_FOLDER` to point to the folder where your data provider is located.
HOOPS Envision Analyzer will load all data providers in the specified folder. The data provider file needs to follow 
the same naming scheme as described above.

Polling of the data provider can be controlled by two settings in the Advanced pane of the Settings dialog:

-   Enable Data Provider polling
-   Show last state when a state is added

