Alpha.Community

В разделе Документация вы найдете все для уверенного старта и работы с Альфа платформой: от пошаговых инструкций по установке и конфигурированию до подробного описания работы компонентов и подсистем. Для поиска необходимых тем и вопросов в документации, воспользуйтесь поиском и фильтрацией результатов.

Вызов внешних функций

Alpha.HMI позволяет вызывать функции, определенные в сторонних динамических библиотеках (файлы .dll для Windows и .so для Linux).

Как вызвать внешнюю функцию

Для вызова внешней функции выполните следующие шаги:

  1. Создайте новую функцию в проекте Alpha.HMI через контекстное меню (правый клик → Создать функцию).

  2. Откройте редактор функции двойным щелчком по созданной функции.

  3. Настройте параметры функции:
    1. Укажите тип возвращаемого значения в соответствии с типом, возвращаемым внешней функцией. Если функция не возвращает значение, выберите void.

    2. Добавьте входные аргументы с типами данных, соответствующими параметрам внешней функции. Например: result: double.

    3. Для параметров, передаваемых по ссылке, установите флажок Ссылка.
  4. Выберите тип действия Вызвать внешнюю функцию в выпадающем списке.


  5. Определите параметры вызова внешней функции:
Параметр Описание
Имя модуля

Путь до DLL-файла. Можно указать:

  • Абсолютный путь.

    Введите полный путь к файлу на компьютере. Например:

    C:\MyLibraries\mylib.dll
  • Переменные среды.

    Введите путь с использованием переменной среды, которая автоматически заменяется на системный путь, например, папку текущего пользователя: 

    $env:USERPROFILE\Libraries\mylib.dll

    Здесь $env:USERPROFILE будет автоматически заменено на путь к папке текущего пользователя (например, C:\Users\YourName).

  • Переменные Alpha.HMI.

    Введите путь относительно расположения проекта. Переменные автоматически заменяются на пути, связанные с проектом.

    $hmi:proj:Folder\Libraries\mylib.dll          — путь к папке, в которой находится файл проекта (.hmi)
    $hmi:proj:ResourceFolder\Libraries\mylib.dll — путь к папке ресурсов проекта
    $hmi:proj:File — путь к самому файлу проекта (.hmi)

  • Только имя файла (если DLL находится в корне каталога Alpha.HMI): mylib.dll.
Имя функции Имя вызываемой функции, определенной в динамической библиотеке.
Тип вызова

Способ вызова функции:

  • CDecl — стандартный C-вызов
  • StdCall (Win API) — вызов в стиле Windows API

    Подробнее о соглашениях вызова:

Кодировка

Кодировка символов:

  • UTF8
  • UTF16
  • ANSI
Опции маршалинга

Настройки направления работы аргументов в формате JSON:

  • ["in"] — входной аргумент (по умолчанию)
  • ["out"] — выходной аргумент
  • ["in", "out"] — входной/выходной аргумент
  • ["out", "buffer"] — выходной строковый аргумент с буфером

Пример вызова внешней функции

Рассмотрим пример создания функции для вызова внешней функции CalculateSum из библиотеки mathlib.dll. Скачать готовую библиотеку mathlib.dll с функцией CalculateSum можно здесь или скомпилировать самостоятельно, используя приведенный ниже исходный код.

Исходный код внешней функции CalculateSum (написан на языке C++):

#include "pch.h"
#include <Windows.h>

extern "C" __declspec(dllexport)
double __stdcall CalculateSum(double a, double b, double* result) {
    *result = a + b;
    return *result;
}

BOOL APIENTRY DllMain(HMODULE hModule, DWORD ul_reason_for_call, LPVOID lpReserved) {
    switch (ul_reason_for_call) {
        case DLL_PROCESS_ATTACH:
        case DLL_THREAD_ATTACH:
        case DLL_THREAD_DETACH:
        case DLL_PROCESS_DETACH:
            break;
    }
    return TRUE;
}

Функция принимает два входных параметра (a и b) и возвращает их сумму как через возвращаемое значение, так и через выходной параметр result.

Настройка функции в Alpha.HMI

  1. Создайте функцию с именем CallCalculateSum.
  2. Настройте параметры:
    • Тип возвращаемого значения: double

    • Входные аргументы:
      1. a: double
      2. b: double
      3. result: double (с установленным флажком Ссылка)
    • Выберите тип действия Вызвать внешнюю функцию в выпадающем списке.

  3. Параметры вызова внешней функции:
    • Имя модуля: C:\MyLibraries\mathlib.dll

    • Имя функции: CalculateSum

    • Тип вызова: StdCall (Win API)

    • Кодировка: UTF16

    • Опции маршалинга: {"result": ["out"]}

Использование функции в коде

  1. Добавьте текстовое поле на форму, в нём будет выводиться рассчитанная сумма.
  2. Настройте обработчик события Opened формы, чтобы при её открытии автоматически вызывалась внешняя функция CallCalculateSum. Пример кода:

    // Объявляем переменные
    inputA: double = 5.0; // Первое число для сложения
    inputB: double = 3.0; // Второе число для сложения
    outputResult: double = 0.0; // Переменная для хранения результата (будет заполнена функцией)
    
    // Вызываем внешнюю функцию для вычисления суммы inputA и inputB
    // &outputResult — передаём адрес переменной outputResult, чтобы функция могла записать туда результат returnValue: double = CallCalculateSum(inputA, inputB, &outputResult); // Выводим результат Text_1.Text = "Сумма: " + String.ToString(outputResult);

    Передача параметров по ссылке выполняется через символ &.

  3. При открытии формы в рантайме в текстовом поле отобразится результат выполнения внешней функции CallCalculateSum, которая вычисляет сумму числовых аргументов inputA = 5.0 и inputB = 3.0.