Guidelines for Integrating Hybrid DLL

1.Purpose of Hybrid DLL

In our system, we already have an API that provides the necessary functionality for Hanger Selector calculation. However, a hybrid DLL has been introduced to address certain challenges and enhance usability in specific scenarios. This document outlines the purpose of the hybrid DLL, its advantages, and when it should be used.

1.1 Why Do We Need a Hybrid DLL?

While the API offers real-time data and seamless integration, there are cases where a hybrid DLL is beneficial:

1. Offline Access: Users may need to access core functionalities without an internet connection.
2. Performance Optimization: Reducing API calls can improve response times and system performance.
3. Failover Mechanism: Ensures continued operation in case of API downtime or network instability.
4. Security Considerations: Some users may require local processing due to data privacy concerns.
5. Integration with Desktop Applications: Desktop-based solutions can use the DLL without relying on external services.

1.2 Key Features of the Hybrid DLL

• Provides the same core functionalities as the API.
• Stores necessary data locally for offline usage.
• Optimized for performance and minimal resource consumption.
• Supports easy updates to maintain data consistency with the API.
• Can be used as a fallback when API services are unavailable.

1.3 When to Use the Hybrid DLL vs. the API

1.4 Implementation Considerations

• Ensure the hybrid DLL is periodically updated to match API changes.
• Implement synchronization mechanisms to handle data consistency.
• Clearly define fallback strategies between API and DLL usage.
• Evaluate security measures to protect locally stored data.

2. How to integrate

2.1 Prerequisites

• Development environment set up with .NET Framework 4.5 or higher.
• Request the latest version of the offline DLL obtained from Request Access.

2.2 How to integrate

2.2.1 Hybrid DLL integration flow

How it works (Step by step)

1. Import the Hybrid DLL
2. Decide target mode (Online vs Offline) from APIEnum
3. Initialize settings for the chosen mode
   • Online setting parameters refer to the section Hybrid DLL Integration Guide | 2.2.4 Modes of Operation
   • Offline setting parameters refer to the section Hybrid DLL Integration Guide | 2.2.4 Modes of Operation
4. If Online mode, verify a stable internet connection → If not stable, fallback to Offline mode
5. Use the same methods set (Get Hangers, Get Hangers Multiple, Get All Metal Hangers, etc) through the active mode

2.2.2 Adding the DLL to the Project

To integrate a DLL into your project, please follow these steps:

1. Copy the hybrid DLL into your project's library folder
2. Add references to the DLL to your project settings:
   • For .NET: Use "Add Reference" or modify .csproj
   • For Java: Load hybrid DLL using System.loadLibrary (using JNA/JNI to call hybrid DLL)

2.2.3 Initializing the Hybrid DLL

1. Import the required namespace or package.
2. Instantiate the DLL class by selecting the mode (Online or Offline).

Example code:

public static API GetDesktopAPI(APIEnum apiEnum)
{
    if (apiEnum == APIEnum.DesktopAPIOnline)
    {
        DesktopAPISettings settings = new DesktopAPISettings
        {
            environment = ENVIRONMENT, // Target environment (e.g., QA, Staging, Production)
            clientID = DESKTOP_API_CLIENT_ID, // Unique client identifier
            clientSecret = DESKTOP_API_CLIENT_SECRET, // Secret key for authentication
            timeoutMs = DESKTOP_API_TIMEOUT, // API timeout value in milliseconds
            useOfflineAPI = false // Indicates Online Mode
        };
        return new API(settings);
    }
    else if (apiEnum == APIEnum.DesktopAPIOffline)
    {
        DesktopAPISettings settings = new DesktopAPISettings
        {
            useOfflineAPI = true // Indicates Offline Mode
        };
        return new API(settings);
    }
    return null;
}

2.2.4 Modes of Operation

The Hybrid DLL supports two modes, determined by the APIEnum parameter:

Online Mode (APIEnum.DesktopAPIOnline)

Calls the Hanger Selector API to retrieve results.

Offline Mode (APIEnum.DesktopAPIOffline)

Uses built-in logic and local data to perform calculations and return results.

APIenvironnement Options

2.3 Auto Update

To keep data consistent, the DLL includes an auto-update mechanism. This ensures that your offline DLL version is always up to date with the latest release.

How it works (Step by step)

1. Step 1: Check for Updates

• Call the method API.CheckForNewVersion(ref message).

• This checks if a newer offline DLL version is available.

2. Is a new version available?

• No → Stop the process
• Yes → Continue to download

3. Step 2: Download the New Hybrid DLL Package

• Call the method API.DownloadNewVersion(ref message).

• This retrieves the latest DLL package.

4. Verify Download

• If the download fails → Stop the process
• If the download succeeds → Continue

5. Replace the Old Files

• Extract the downloaded .zip file into your current working directory
• Replace the old DLL and data files with the new ones

Method References

• Check for new version: API.CheckForNewVersion(ref message)
• Download the new version: API.DownloadNewVersion(ref message)

3. Error Handling in Hybrid DLL

3.1 Exception Overview

The Hybrid DLL defines a set of custom exception types that enable the integration team to identify errors consistently and implement appropriate handling strategies.

3.2 Exception Types

4. Mapping between Hybrid DLL methods and Hanger Selector API